Balsamiq

Last updated October 2nd 2011.

BMML is the Balsamiq Mockups Markup Language, the flavor of XML used by Balsamiq Mockups to save its data.

This document outlines the BMML file format, in the hope that this will be useful to you when integrating Mockups in your daily work. You could for instance import BMML into your tool, write a BMML parser which generates HTML or MXML or XAML or running code...the sky is the limit!

Warning: there are some things that aren't documented here, like what properties each control type supports. To figure those things out, just open Mockups, drag a control type to the stage, change some properties in the property inspector and look at the resulting BMML. In other words, we try our best to keep this document up-to-date, but you should trust shipped code more. :)

Remember that XML syntax is case-sensitive. <tag> and <Tag> are different.

Quick Overview#

Here's a sample BMML containing a single Callout control:

As you can see, the top-level tag is a 'mockup' tag. Within it, there's a 'controls' tag, which includes a list of 'control' elements, one for each control in the mockup. Each control elements can include an optional 'controlProperties' element, with different children depending on the type of element. We will see below what all the attributes mean in details.

The Mockup Tag#

Here's the DTD snippet for the mockup tag:

A 'mockup' tag includes a 'controls' tag, described below. measuredW and measuredH are the dimensions, in pixels, of the mockup, including the top-left white space around it. mockupW and mockupH (added on 9/14/2009) are the dimensions of the mockup without any space around it. In other words, this would be the size of the PNG if you exported it. The skin tag is not used right now, and is always "sketch". The version tag is for the version of the BMML specification, which is 1.0 so far. The controls tag is simple, it doesn't have any attributes and just contains a list of 'control' tags.

The Control Tags#

Here's the DTD snippet for the control tag:

The control tag can contain a controlProperties tag, described below.

• controlID is always unique for this list of controls and identifies this control's instance in the mockup controlTypeID is the control type (listed below).
• w and h represent the size in pixels of the control.
• A value of -1 means that you should look at measuredW or measuredH instead.
• measuredW and measuredH represent the size in pixels of the control, when shown in its 'natural state', i.e. it's the preferred dimension of the control as dictated by the control itself. For instance, for a Label control, measuredW would be large enough to show the whole text with no cropping.
• x and y represent the position in pixels of the control, relative to the top-left corner of the canvas. 
• zOrder represents the layer ordering of this control. 
• Values are unique and sequential within the current list of controls. 
• isInGroup tells you if a control is part of a group (-1 means "no", otherwise it uses the controlID of the group)
• locked tells is a flag that tells you...you guessed it!

The ControlProperties Tag#

The controlProperties tag contains a child for each property that can be modified for a control (using the property inspector). Here's a list of the different control properties and where they are used:

• alternateRowColor, rowHeight, hasHeader, vLines, hLines: used for Lists and Data Grids controls
• backgroundAlpha (0..1): the transparency of the background
• bgPattern (one of 'allWhite', 'allBlack', 'topOnly', 'topBlueBottom', 'topBlackBottom'), topBar (bool): used by the iPhone control
• bold, italic, underline, align, size: used by any control with text in it
• borderStyle ('none' or 'square'): used by all controls which can show a border or not
• close, minimize, maximize, dragger, topheight, bottomheight: used by the Dialog / Window control
• color (int): the color of the text or the background of a component, depending on the control type
• crop (x,y,h,w): four comma separated values with range [0,1000] that represent cropped bounds ratios respect to full control size. For example 0,0,1000,1000 represents the full control.
• customData (String): added on 10/21/2009, see here for details
• customID (String): added on 10/21/2009, see here for details
• filter: used by the Image control: true if the image should be sketched
• direction ('left', 'center', 'right', 'bottom', 'top'): used by Arrows, Tabs, Curly Braces, Pointy Button etc
• href: used by all controls that can have a single link to other controls, like Button, Canvas, etc. Mockups saved before 9/14/2009 only contain the file name to link to, i.e. foo.bmml with no path. Mockups saved after 9/14/2009 contain a string of this form: <name>&bm;<viewURL>&bm;<loadURL>&bm;<editURL>. The last 3 values are all the same for Mockups for Desktop but are different in the plugin versions.
• hrefs: like href, but used by controls that link to multiple files, like the Accordion, Link Bar, etc. It's a comma-separated list of strings formatted the same way as a single href string (see previous bullet).
• icon: a string composed of both iconID of the icon to use for this control and its size, like this "iconID|48". There are over 220 icons, each with a unique ID (see below). The sizes are either 16, 24, 32 or 48. As of version 2.1.7, the left part can also be a src, either ./assets/filename or $ACCOUNT/assets/filename, based on where the custom icon is loaded from.
• indeterminate (bool) and scrollbarValue (0-100): used for Progress Bar controls
• labelPosition ('bottom' or 'right'): used in the Icon and Label control
• leftArrow (bool), rightArrow (bool), curvature (-1, 0, 1): used by the Arrow controls
• map (string): added on 9/14/2009: an escaped image map for the linked areas of the mockups, following the same format as the HTML map tag.
• onOffState ('on' or 'off'): used by the Switch control
• orientation ('portrait' or 'landscape'): used by the iPhone, iPhone control
• override: used by the Component control (see below)
• position ('left' or 'right'): used by Vertical Tab Bar
• selectedIndex (-1 for none): the selected item in a list
• src: used by the Image and Component controls. It's either a relative path (for images loaded from disk) or an http url. If it starts with $ACCOUNT/assets, it means the image is in the account assets folder.
• state ('up', 'selected,', 'focused', 'disabled', 'disabledSelected'): the state of the control
• tabHPosition and tabVPosition: used by the Tab Bar controls
• tooltipDirection (NW, N, NE, E, SE, S, SW, W): used by the tooltip control
• value: the value of a scrollbar, from 0 to 100
• verticalScrollbar (bool) and value (0-100): whether the control has a scrollbar or not, and its value (0 means "top", 100 means "all the way down")

The Component Control#

The Component control, known as "Symbol" in Mockups, contains a link to another bmml (here are the docs for the Symbols feature). The link is an url with an optional anchor. If the anchor is missing, then the whole bmml is the target. Otherwise, the target is a group which has the same name of the anchor. The group must be at top level in the bmml. <control controlID="1" controlTypeID="com.balsamiq.mockups::Component"

The ControlProperties tag of a Component control can contain an override tag, for the properties of the Symbol that have been overridden in this symbol instance. Attributes of override tag:

• controlID: id of the overridden control as in the symbol definition. In case the control is nested in groups, then the controlID is the relative path to the control (for example, "2:3:0" is the control with id 0 belonging to group 3 nested in group 2 in the symbol definition).
• x, y, w, h: (optional) these attributes override the original size and position of the control. Measured dimensions are not saved in the bmml.

It is not possible to override the zOrder attribute. It is not possible to add or remove controls in the symbol instance.

Control Type IDs and Icon IDs#

All the control type IDs start with the "com.balsamiq.mockups::" prefix. Here's the full list of the control type IDs supported as of today (case sensitive): AddCommentIcon, AddPageIcon, AIMIcon, AlarmClockIcon, Alert2Icon, AlertIcon, ArchiveIcon, AsteriskIcon, BackSpaceIcon, BaloonIcon, BatteryIcon, BloggerIcon, BoldIcon, BookIcon, BulletsIcon, CalendarIcon, CameraIcon, CartIcon, CellBarsIcon, CellPhoneIcon, ChartColumnIcon, ChartLineIcon, ChartPieIcon, CheckMarkIcon, CircledMinusIcon, CircledPlusIcon, CircledXIcon, CircleIcon, ClockIcon, CloudIcon, ClubIcon, ColumnsIcon, CommentsIcon, ContactIcon, ContactsIcon, CopyIcon, CopyrightIcon, CoverFlowIcon, CreativeCommonsIcon, CursorIcon, CutIcon, DashIcon, DataBaseIcon, DeliciousIcon, DiggIcon, DocEmptyIcon, DocExcelIcon, DocPDFIcon, DocWordIcon, DollarIcon, DotHollowIcon, DotIcon, DoubleArrowIcon, DownArrowIcon, DownFillTriangleIcon, DownLeftArrowIcon, DownloadIcon, DownRightArrowIcon, DownTriangleIcon, EjectIcon, EllipsisIcon, EmailIcon, EmoticonIcon, EmptyIcon, EuroIcon, ExclamationPointIcon, ExportIcon, EyeIcon, FacebookIcon, FileIcon, FilterIcon, FlagIcon, FlickrIcon, FolderClosed, FolderIcon, ForbiddenIcon, ForwardChapterIcon, ForwardIcon, FriendFeedIcon, FullScreenExitIcon, FullScreenIcon, GearIcon, GeoLocation2Icon, GeoLocationIcon, GMailIcon, GoogleIcon, GridIcon, GtCircledIcon, GtIcon, HandClosedIcon, HandOpenIcon, HandPointIcon, HeartIcon, Help2Icon, HelpIcon, HLinesIcon, HomeIcon, HomeMobileIcon, HourGlassIcon, IBeamIcon, ImageIcon, ImportIcon, IndentIcon, Info2Icon, InfoIcon, ItalicIcon, JewelIcon, JumpBackIcon, JumpOutIcon, LeftArrowIcon, LeftFillTriangleIcon, LeftTriangleIcon, LightBulbIcon, LightningIcon, LineIcon, LinkedInIcon, LinkGlobeIcon, LinkIcon, ListIcon, LockIcon, LockOpenIcon, MicIcon, MinusIcon, MusicIcon, Number0Icon, Number1Icon, Number2Icon, Number3Icon, Number4Icon, Number5Icon, Number6Icon, Number7Icon, Number8Icon, Number9Icon, NumberedListIcon, OpenIDIcon, OutdentIcon, PagesIcon, PaperClipIcon, PasteIcon, PauseIcon, PencilIcon, PhoneDialIcon, PhoneHangUpIcon, PlusBigIcon, PlusIcon, PopOutIcon, PortletEditIcon, PortletHelpIcon, PortletMaximizeIcon, PortletMinimizeIcon, PoundIcon, PowerIcon, PrintIcon, PushPinIcon, RecycleIcon, RedditIcon, RedoIcon, RegisteredIcon, ReloadIcon, RepeatIcon, RewindChapterIcon, RewindIcon, RightArrowIcon, RightFillTriangleIcon, RightTriangleIcon, RSSIcon, SadFaceIcon, SaveIcon, ScreenIcon, SearchIcon, ShapesIcon, ShareIcon, ShiftIcon, ShuffleIcon, SimpleArrowIcon, SkypeIcon, SlideShareIcon, SmallClockIcon, SpadesIcon, SpinningIcon, SquaredMinusIcon, SquaredPlusIcon, StarIcon, StopIcon, StrikeThroughIcon, StumbleUponIcon, SuitcaseIcon, TableIcon, TagIcon, TapeIcon, TelephoneIcon, TextAlignCenterIcon, TextAlignLeftIcon, TextAlignRightIcon, ThreeGIcon, ThumbnailsIcon, ThumbsDownIcon, ThumbsUpIcon, TrademarkIcon, Trash2Icon, TrashIcon, TruckIcon, TwitterIcon, UnderlineIcon, UndoIcon, UpArrowIcon, UpdateIcon, UpDownFillTriangleIcon, UpFillTriangleIcon, UpLeftArrowIcon, UpRightArrowIcon, UpTriangleIcon, UserIcon, UsersIcon, VideoCameraIcon, VLinesIcon, VolumeIcon, WirelessIcon, WorldIcon, WriteIcon, XIcon, YIMIcon, YouTubeIcon.