Welcome to the Balsamiq Mockups Help
Thank you for using Balsamiq Mockups. We hope you'll be able to find the answer to your problem here and be able to get back to work on your mockups quickly. All of the help documentation is on this page so hopefully a "Find..." operation can take you to your answer quickly.
If you cannot find the answer you're looking for here, I encourage you to try the GetSatisfaction forums, or to look at the Mockups support page for other options.
Overall Application Structure
Balsamiq Mockups is made up of three major blocks. From top to bottom: the application bar, the UI library and the mockup canvas. Each is described below.
The Application Bar
The application bar includes menus, the Quick Add tool and the toolbar. Each is described below.
The Mockups menus should be pretty self-explanatory. The only tricky bit is that the Mockup menu contains different items depending on what version of Balsamiq Mockups you are using. In general, that's where you'll find the About Box and commands related to your mockup as a whole, like saving, exporting to XML or PNG, etc.
The Quick Add tool is the fastest way to add UI controls to your mockup. To use it, simply type a few letters from the name of the UI control you wish to add and Quick Add will show you a list of suggestions. Use your mouse or arrow keys to scroll down the list to the UI control you wish to add, hit the ENTER key and voila', a new control is placed on the mockup canvas for you. For instance, typing "bu" shows a list containing "Button", "Button Bar", "Help Button", "Radio Button" and "Round Button". Typing "hel", on the other hand, only returns "Help Button". Pressing the ESCape key makes the list disappear, as one would expect.
Try out Quick Add now! As you become familiar with it, you could even hide the UI Library (through the View menu) and simply use Quick Add to add UI elements to your mockup. This maximizes both your mockup canvas area and your speed!
The toolbar includes most of the same commands as the Edit menu: undo, redo, duplicate, cut, copy, paste and delete. Not all versions of Balsamiq Mockups support the same keyboard shortcuts (more info here), so the Toolbar gives you a handy way to perform common actions. Notice that you'll find the same commands in the Property Inspector as well.
The UI Library
The UI Library, or UI Controls Library, is the long strip of UI Controls just below the Application Bar. It lists all of the different UI control types that Mockups supports, alphabetically. The main goal of the UI Library is to let you add UI Controls to the mockup canvas, but you can also use it to see what's possible and to get inspiration for your UI mockup.
To add a new UI control to the canvas, simply select the control type you wish to add, then you can either "drag and drop" it to the mockup canvas below or simply double-click and Balsamiq Mockups will place it on the mockup canvas for you.
The Mockup Canvas
This is the main working area of Balsamiq Mockups, where your UI mockup comes to life. Once you add UI controls to it, you can move them, resize them and tweak them to your heart's content until your UI mockup is ready. See the sections below for instructions.
The mockup canvas grows and shrinks with your browser or application window, so you can make room for bigger mockups if you need to.
Working with UI Controls
Adding UI Controls
To add new UI controls to your mockup, you can use the UI Library or the Quick Add tool, described above.
Another way to add new Ui control is to duplicate the selected controls. You can either use copy and paste to do so, or the duplicate menu command or button, or simply hold down the ALT key (OPTION key on a Mac) and drag the selection. This will duplicate it in place and let you move it all at once.
Selecting UI Controls
There are a few different ways to select UI controls. If you are familiar with graphics software, these should be of no surprise.
- Clicking on a UI control selects it.
- Drawing a rectangle which encloses many UI controls selects them
- SHIFT+CLICK on a control adds it to the selection
- CTRL+CLICK on a selected control removes it from the selection
Moving UI Controls
Once you have selected one or more UI controls, there are a few different ways to move it on the canvas.
- you can drag it with your mouse.
- you can "nudge it" a few pixels with your keyboard's UP/DOWN/LEFT/RIGHT keys
- you can "nudge it" with bigger steps by holding down SHIFT and using your keyboard's UP/DOWN/LEFT/RIGHT keys
- you can move your controls to be aligned in one direction by using the align tools found in the Property Inspector.
Resizing UI Controls
Resizing the selected controls is easy. You can just grab one of the 8 little squares of the selection rectangle and drag it. If you want to constrain proportions while dragging from a corner square, hold the SHIFT key while dragging.
Another way to resize some controls to their "natural size" is to use the Auto-Size function found in the Property Inspector.
Layering UI Controls
You can layer controls as if they were pieces of paper on the mockup canvas. To do so, you select the controls you want to layer and select one of four layering commands available via the Property Inspector: bring to front, send to back, bring forward and send backward.
Deleting UI Controls
To remove some UI controls from the mockup canvas, select them and hit the DELETE key. Alternatively you can click on the eraser button in the toolbar or select "delete" from the Edit menu.
Grouping UI Controls
Sometimes you might wish to group some controls to better align them or to move them all at once. To group a set of controls, select them and hit CTRL+g on your keyboard. Once grouped, the controls will behave as one when moving or aligning. Note that you will not be able to edit the controls text or other properties once they are grouped. To ungroup controls, you hit CTRL+SHIFT+g on your keyboard. Groups can be nested.
Working with Text
Some UI controls, such as Button, Label or DataGrid, have text in them. To edit the text, double-click on the control and start typing. Or if you have the control selected, hit ENTER or F2 to start editin. To commit the text you typed, simply click anywhere other than the text field you typed in. If you want to discard the text changes you just made, hit the ESCape key.
A note on special characters: some controls use some characters as separators. For instance, to create multiple buttons in a button bar, you separate them with a comma. Or a space character separates tags in a Tag Cloud control. Some other controls, like the Tree, use other characters alltogether. In such cases the default text for the Control includes explanations on how to use it.
Note: you cannot edit text in a control that is part of a group. Ungroup the control first to edit it.
Working with Icons
Balsamiq Mockups comes packed with over 70 hand-drawn icons for you to use. The UI controls that support icons are: "Icon", "Icon and Text Label", "Button", "Menu Bar" and "ComboBox". There are two ways to select an icon to use, the icon search and the icon library.
Icon Search: if the controls you selected support icons, you will see the icon search box in the property inspector. This works much like the Quick Add tool: just type a few letters from the name of the icon you are looking for and a list of suggestions will pop up. In this case, the list is a grid of icons to choose from. Just click on the one you want to select it.
The Icon Library: if you'd like to explore all the icons that are available, click on the little down-pointing arrow to the right of the icon-search box. This will bring out the icon library. The icon library is pretty self-explanatory, let me know if you'd like more detailed info about it. One little trick is to double-click on the icon you'd like to select, instead of clicking and clicking on the "Select" button.
Once you have selected an icon, you can resize it, or remove it, via the Property Inspector.
The Property Inspector
The property inspector is the little floating rectangle that appears once you select one or more UI controls. It allows you to perform some common functions such as copying/pasting, layering, and aligning controls, as well as some control-specific customizations.
The Property Inspector fades in and out of view in an effort to be out of your way. You can also drag and drop the Property Inspector to move it, it will re-appear where you left it next time you need it.
Common Inspectors
|
Editing Inspector
|
Always present, always at the top. From left to right: undo, redo, duplicate, cut, copy, paste, delete, group, ungroup, lock |
|
Layering and Position & Size
|
Always present, always in the second row (below the editing inspector). Layering, from left to right: bring to front, send to back, bring forward, send backward. Position and size shows you the size and position of the selection, in pixels. Clicking on the numbers lets you edit them. The format is "X,Y WxH" where X is the x position, Y is the y position (0,0 is top-left, growing right and down), W is the width and H is the height of the selection. |
|
Align
|
Shown whenever more than one control is selected. Lets you align the selected elements horizontally to the left, center and right and vertically to the top, middle and bottom. The last two icons on the right distribute the centers of the selected items horizontally or vertically. |
Other inspectors
|
Arrow
|
Lets you decide the direction of the arrow, as well as whether to show or hide arrow pointers. |
|
Auto-Size
|
Clicking on the autosize button will resize the component to its natural size, with everything showing and no extra space |
|
Border
|
Shows or hides the selected controls; border |
|
Color
|
Lets you select the foreground or background color of the selected controls (depending on the control type), as well as the background color's opacity (only in some controls, see right). |
|
Icon
|
The icon inspector lets you select, resize and remove an icon to the selected controls. You simply click on the search field, start typing the name of the icon you need and you'll be presented with suggestions that match your string. Use the arrow keys or your mouse to select the icon you want, then use the slider to resize it. To remove an icon, click on the eraser icon next to the slider. To see the full list of icons available, click the little triangle which will open the Icon Library. |
|
Icon Label Position
|
Lets you specify whether the label should be positioned below or to the right of the icon |
|
Image
|
The Image inspector lets you select which image to use for the selected image controls. You can select the default placeholder, add a new image or select from a list of images already present in the mockup. You can additionally "sketch" the image to make it look a bit more hand-drawn by selecting the "Sketch it!" checkbox. |
|
List and DataGrid
|
Lets you specify whether the selected controls should have a header row, two colors for alternating row backgrounds, the height of the row and which row should be selected, if any. In the DataGrid control, you can additionally toggle the visibility of vertical and horizontal dividing your table's columns and rows. |
|
Progress Bar Type
|
Lets you toggle between a progressive and an indeterminate (candy-cane) progress bar. |
|
Scrollbar
|
Lets you quickly add a scrollbar to the selected controls. |
|
Selection
|
Lets you specify which elements of the selected control should be selected, if any. |
|
State
|
Lets you specify the state of your control, whether it's in focus, selected, disabled etc. Different control types support different states. |
|
Horizontal Curly Brace Direction
|
Lets you specify whether the horizontal curly brace should point up or down |
|
Tabs Position
|
Lets you specify whether the tabs should be above or below the canvas, as well as their horizontal alignment relative to the canvas. |
|
Text Styles
|
Lets you specify whether the font of the text in the selected controls should be bold, italic or underlined, as well as its horizontal alignment and point size. |
|
Vertical Curly Brace Direction
|
Lets you specify whether the vertical curly brace should point left or right |
|
Vertical Tabs Position
|
Lets you specify whether the tabs should be to the left or right of the canvas. |
|
Window / Dialog
|
Lets you toggle window chrome controls like minimize, maximize and close, as well as a dragging affordance. You can also specify the height of the top and bottom bars. |
Keyboards Shortcuts
Below is a list of all the keyboard shortcuts and modifiers which you can use in Balsamiq Mockups. While all of the shortcuts will work in the Desktop version, some might not work when you edit mockups in a browser.
If you are running OS X, you can use the Command Key (the Apple Key) wherever you read CTRL in the list below.
| Working with Controls | |
|---|---|
| Add to selection | SHIFT+CLICK |
| Toggle selection | CTRL+CLICK |
| Select All | SHIFT+A |
| Edit the selected control's text | ENTER or F2 |
| Resize maintanining aspect ratio | Hold SHIFT |
| Disable snapping during move or resize | Hold CTRL |
| Nudge selection 2px | arrow keys |
| Nudge selection 20px | SHIFT+arrow keys |
| Clone selection | ALT+drag |
| Undo last command | CTRL+Z |
| Redo last command | CTRL+Y |
| Cut the selected controls | CTRL+X |
| Copy the selected controls | CTRL+C |
| Paste | CTRL+V |
| Delete the selected controls | DELETE or BACKSPACE |
| Duplicate the selected controls | CTRL+D |
| Select All | CTRL+A |
| Group the selected controls | CTRL+G |
| Ungroup the selected groups | CTRL+SHIFT+G |
| Lock the selected controls | CTRL+2 |
| Unlock all locked controls | CTRL+SHIFT+2 | Quick Add |
| Sending focus to Quick Add | / (forward slash) or + (plus sign) |
| Navigating the Suggestion List | arrow keys |
| Closing the Suggestion List | ESCAPE |
| Sending focus back to the Canvas | ESCAPE | Working with Icons |
| Navigating the Suggestion List | arrow keys |
| Using the selected icon | ENTER |
| Closing the Icons Library | ESCAPE |
| Closing the Suggestion List | ESCAPE | Editing Text |
| Committing the current text in a one-line field | ENTER, or click anywhere |
| Ignoring the current edit | ESCAPE | Working with Mockup Files |
| New Blank Mockup | CTRL+N |
| New Clone of Current Mockup | CTRL+SHIFT+N |
| Open a mockup file | CTRL+O |
| Save the current mockup file | CTRL+S |
| Save all open mockups | CTRL+SHIFT+S |
| Close current mockup | CTRL+W |
| Close all mockups | CTRL+SHIFT+W |
| Export this mockup's XML | CTRL+E |
| Import mockup | CTRL+SHIFT+E |
| Quit Balsamiq Mockups | CTRL+Q | Other |
| Hide/Show the UI Library | CTRL+L |
Importing and Exporting
Exporting and Importing via XML
Balsamiq Mockup gives you the ability to export your mockup as an XML file, which is useful for creating copies of your mockup, or emailing the mockup to someone else, or possibly exporting it to another format (bring your own code for this).
Exporting a mockup is easy, just select "Export Mockup..." from the Mockup menu, and you'll see this dialog:
Once you have the XML, you can use it to create a new mockup by just importing it via the "Import Mockup" dialog:
Note that importing a mockup will erase the contents of your mockup canvas
Exporting to an image
If you just want to get an image of your mockup to send around, you can simply select the "Download PNG image" command from the Mockup menu.
Confluence Integration
This section of the help describes the points of integration between Balsamiq Mockups Plugin For Confluence and Confluence itself
Installing Mockups for Confluence
To install it just go to Confluence Administration > Plugins, then Browse your computer for mockups-1.0.xx.jar to upload it. You can also install Mockups for Confluence through the Plugin Repository.
Creating a new mockup
There are two easy ways to add a new UI mockup to your wiki pages. The easiest way to add a UI mockup to your page is to click on the "Add UI Mockup" link found in the "Add Content" menu section of your wiki page.
This will take you directly to the Balsamiq Mockup editor. Once you are happy with your mockup, just select "Save and Close" from the Mockup menu, and you'll be asked to give it a unique ID. This is required and allows you to include more than one mockup on the same page.
Once you name your mockup you'll be taken back to Confluence, with your mockup placed at the top of the page. To move it down to your preferred location, just edit the page, find the {mockup:your_mockup_name|1} macro definition at the top, cut it, scroll down to where you want your mockup to be and paste. Save the page and you're done!
Another way to add a mockup to a page is to simply write {mockup} where you want your new mockup to be. Once you save the page you'll see this:
Clicking on the link will take you to the editor...and you know what to do from there.
Editing a mockup
If you have editing rights on the wiki page that contains a mockup, you'll see a "edit this mockup" link right under the mockup image.
Simply click on the link and you'll be taken to the editor. Click "Save and Close" or "Discard changes" to go back to Confluence.
If you select “Save and Close”, you’ll have a chance to enter an optional comment about your edit:
As the dialog says, if you leave the field blank no notifications will be sent. Otherwise your comment will appear on the Issue’s comments list, and watchers will be notified.
Deleting a mockup
To remove a mockup from a page, simply edit the page, find the appropriate {mockup} macro, delete it and save the page again. You might also want to delete the mockup's XML and PNG attachment files from the page.
Looking at a mockup's history
Each ui mockup is saved as two separate attachments, one for the PNG image and one for the XML representation of the mockup. Confluence supports versioning of attachments, and Balsamiq Mockups takes advantage of it so that you can see how your mockup evolved over time, or roll back to a previous version.
Rolling back to a previous version of a mockup
This is a bit tricky but it can be done. Go to the attachments view for your page, find the mockup you want to roll back, get the XML for the version you want to roll it back to and copy it. Now you can go back to the page, edit the mockup and import your old XML via the "Import" dialog.
Moving a mockup on a page
To move a mockup to a different location on a page you edit the page, find the {mockup:your_mockup_name|1} macro definition for the mockup you want to move, cut it, scroll down to where you want your mockup to be and paste. Save the page and you're done!
If instead you'd like to left-align or right-align the mockup's image relative to your page, you can add an optional third parameter to the macro. For instance {mockup:your_mockup_name|1|LEFT} will left-align (as will "left", "L", "l" and any word starting with an "l"), while {mockup:your_mockup_name|1|RIGHT} will right-align the image (as will "right", "R", "r" and any word starting with an "r").
Managing the Balsamiq Mockup Plugin for Confluence
Managing your Balsamiq Mockups for Confluence is very simple. Go to the "Administration" page on your wiki, click on "Plugins", click on "Balsamiq Mockups" and you'll see something like this:
This view will give you the version of the plugin, and has a "Configure Plugin" link, which takes you to this:
This is where you can enter your license information and see the status of your current installation.
Mockups and Adaptivist's Theme Builder integration
If you are using Adaptivist's Theme Builder, you'll have to manually add a "Add UI Mockup..." link to the edit menu. Here's how:
- Go to Theme Builder's Layout Manager (administration / themes / configure theme / layout manager)
- Go to the Menus tab and click "Edit..." at the bottom
- Go to the Edit Menu tab and add the following right under the "Comment..." compound-menuitem:
{menuseparator}
{compound-menuitem:webui|location=system.space.actions|key=com_balsamiq_confluence_plugins_mockups_addmockup|caption=Add UI Mockup...} - Save your layout
That's it! you will now see a nice "Add UI Mockup..." link in your edit menu.
JIRA Integration
Installing Mockups for JIRA
To install it just go follow Atlassian's Instructions here.
Adding a UI Mockup to a JIRA Issue
To add a UI Mockup to a particular JIRA issue you simply click on the “Add/Edit UI Mockup to this issue” link:
You will be taken to the Mockups editor. When you are happy with your mockup, you simply go to the Mockup menu:
and select “Save and Close” (also note the “Save as New Mockup” menu item, which is exclusive to Mockups for JIRA. More on that below).
You will be prompted to name your mockup, and the software will auto-generate a simple date-based name for you, which is handy when you have many mockups on the same issue:
You can just hit enter to accept that name or give it whatever name you wish.
You will be taken back to the issue. Here's a sample one (click for a larger view):
Notice how the UI Mockup is now attached to the issue, both as an image and as a bmml data file (BMML is the flavor of XML that Mockups uses). Also notice how Mockups for JIRA has added a comment to the issue for you, saying “Added UI Mockup: <mockup name>“. This means that if any of your co-workers is watching the issue, they’ll get an email notification to check out your new work of art. :)
So that’s the basic workflow of creating a new mockup for an issue. It gets better!
How to edit / iterate on Mockups
Say you want to tweak an existing UI mockup or create a new mockup as a variation of an existing one. The workflow is simple. Click the “Add/Edit UI Mockup to this issue” link again:
This time you will be presented with a dialog like this one:
You will then be able to either start from a blank canvas or edit an existing Mockup from the ones already attached to the current issue.
To simply iterate on the same mockup, you just select “Save and Close” from the Mockups menu, to create a new mockup variation, you select “Save as New Mockup” instead.
If you select “Save and Close”, you’ll have a chance to enter an optional comment about your edit:
As the dialog says, if you leave the field blank no notifications will be sent. Otherwise your comment will appear on the Issue’s comments list, and watchers will be notified.
That’s it! Couldn’t be simpler right? :)
Administration Interface
Balsamiq Mockups for JIRA has a simple interface to register your serial key and to keep track of your support period. Simply go to the ADMINISTRATION tab and notice the “Balsamiq Mockups License” link on the left:
This will take you to the licensing screen, which looks very similar to JIRA’s licensing page (click for a larger view):
XWiki Integration
Please refer to the Balsamiq Mockups for XWiki Online Help page.
The Desktop Version
The Desktop version of Balsamiq Mockups allows you to work on your mockups when you are not connected to the Internet. It also supports all keyboard shortcuts and some say it performs faster than the online version.
The Mockup menu for the Desktop version includes some extra commands:
New: creates a new empty mockup.
Open: Lets you select an XML file from your computer to load a mockup
Save: Saves the current mockup in an XML file.
Save As...: Same as "Save" but lets you specify a name for your mockup. Don't forget to specify XML as a file extension or you won't be able to open the mockup file again unless you manually rename it.
Export PNG snapshot: Exports the mockup to an image file on your desktop.
Installing The Desktop Version on Linux
Mockups uses Adobe AIR as the underlying technology to bring web applications to the desktop. Unfortunately the linux version of AIR is still in beta, which means that you need to go through some trouble in order to install Mockups, and some of its features of Mockups won't work (nothing critical). Adobe is actively working on linux support for AIR so we can expect these inconveniences to be temporary.
Here's how to install Mockups on your linux machine. I tested on Ubuntu 7.04 but I think the instructions should apply to all modern linux distributions:
- Install Adobe AIR: http://labs.adobe.com/downloads/air_linux.html - I had to make sure I closed Firefox before running the installer, and I had to run it as root.
- Using Firefox, download the Mockups For Desktop .air file: MockupsForDesktop.air - you should be prompted to open the file in AIR.
- Follow the quick installation instructions (basically say Yes, Approve, Launch whenever prompted) and Mockups for Desktop should start up automatically after installation.
What won't work on linux:
- From my initial tests, dragging and dropping controls from the UI library doesn't work. As a workaround, you can either double-click on a control to add it or just use the Quick Add tool
- Native menus don't work in AIR for linux so I have to draw my own menus. Keyboard shortcuts still seem to work though
If you find any other problems or if these instructions didn't help you enough, please email me and we'll sort it out.
Command Line Options
Mockups for Desktop can be controlled via the command line with the following commands:
Balsamiq Mockups export <inputXMLFilePath> <outputImageFilePath>
exports the provided xml file to a PNG file
Balsamiq Mockups register <organizationName> <serialKey>
registers this Mockups copy with the provided serial key info
Balsamiq Mockups unregister
un-registers Mockups from this computer
Balsamiq Mockups version
prints the current version of Mockups for Desktop
You only need to register your copy once per machine, then you can export PNGs from your Mockups' XML files whenever you need to.
The export process is near-instantaneous, and you should only see a quick “flashing” of the app.
You can find some scripts to export multiple mockups using the command-line here.
