Briefs are image-based prototypes. That means you’re defining your interface as a series of connected images that outline the path(s) a user can take through your application.
At its core, every brief is an XML text file that contains references to images relative to its location in the file system. This can be compacted into a jumbo binary file with the raw image data embedded in the resulting .brieflist file. This allows for a single file, containing all pertinent data, to be shared and transmitted as you see fit.
However, before a brief becomes a binary XML file, it is authored using the BS scripting language. Its name is short for BriefScript, a simple scripting syntax that defines a brief as a series of scenes and actors. These scripts can be identified by their file extension, .bs.
To begin writing a brief, just open your favorite text editor and save a new file with the .bs extension. Each brief begins with a simple declaration:
start: Springboard
defaultImage: imgs/blank.png
The start property defines the scene to load when the brief is launched. In BS, you identify a scene by its name (above, “Springboard”). Keep reading to find out how to define scenes & actors. Optionally, you can define a default image that will be use for all scenes. In the example above, “imgs/blank.png” is a filesystem reference to an image (in this case, relative to the location of the .bs file).
With this declaration out of the way, you’re ready to start writing your first scene.
It’s easy to visualize your app as a series of screens that are presented to the user. A scene represents the particular state of a screen for a given workflow. In other words, a scene represents a screen configuration consisting of labels, controls and graphics that support a user accomplishing a particular task. Each scene is a stepping stone in your brief, telling the user where they are and what they can do while they’re here. When designing a scene, think first about the task(s) the user should perform. Then determine what controls should be available to them.
In Briefs, you define a scene as follows:
scene: Springboard
image: imgs/0-springboard.png
The scene property defines the name of the scene (in this case, “Springboard”). The image property identifies the path (“imgs/0-springboard.png”) of the image that represents the screen background for the scene.
Key Concept: When you define a scene, you are defining an image that will appear on screen. By default, the image you specify will be scaled to the entire size of the device.
A scene by itself isn’t particularly interesting until you add things to touch, grab and spin inside of it. That’s where actors enter from stage left. An actor, just like a scene, is represented on screen by an image. However, unlike a scene, an actor can perform an action when tapped by the user. The following section goes into more detail on actions.
In Briefs, a basic actor is defined as such:
actor: Pick SMS App
image: img/an-actor.png
position: 19, 25
size: 55, 55
action: goto(Main)
The actor property defines a name for the actor. Next, the image property identifies an image to display in the area occupied by the actor. The position property tells Briefs where it goes (top left corner) and the size property tells it how big to make it (width, then height). By default, an image is stretched to fit in the defined size. There are various ways to define these properties. The following actors are equivalent in position and size:
# Verbose
# Also use ('x', 'y', 'w', 'h')
actor: Sample Actor
left: 19
top: 25
width: 55
height: 55
# Compact
# Also use ('xywh', 'bounds')
actor: Sample Actor
frame: 19, 25, 55, 55
# Paired
# Also use for position ('offset', 'xy', 'coord')
# Also use for size ('wh')
actor: Sample Actor
position: 19, 25
size: 55, 55
Note: We’re using # character to denote inactive lines of code, called comments. You can use them to make notes to yourself while writing your Briefs. When you build your .brieflist the compiler will ignore these lines.
Since actors are the most, er, active part of your brief, it makes sense for them to react to touch. There are three different states that an actor can support by providing alternative images for display.
For example:
actor: Touchy Actor
image: touch-me-im-an-actor.png
disabled: taking-a-smoke-break.png
touched: how-you-doing.png
Both the touched and disabled are optional properties that provide alternative representations of the control. When an actor is disabled, the actor becomes inert and will display the image identified by its disabled property. This image should say “go away, I won’t do anything!”. Conversely, the touched property supplies its image when the user touches the actor, but hasn’t yet released it. This allows your briefs to feel more responsive.
And if you want to hide your actor when the scene first loads, Briefs has you covered:
actor: Can't Touch This!
frame: 100, 10, 230, 200
image: hidden-gem.png
visible: false
By setting the visible property to false, you hide the actor from sight only to appear in all its glory when you choose to show it. It’s an optional property that is true by default.
When the iPhone was first demoed in 2007, it’s safe to say scrolling stole the show. It is easily one of the defining visual characteristics of the platform and is something that is believed only after experiencing first-hand. This is such a critical feature to the platform that Briefs includes a way to make an actor scrollable.
Below is an example:
actor: Scroll Baby, Scroll!
image: larger-image.png
frame: 0, 0, 30, 60
scrollable: true
When you set the scrollable property to true, the actor’s image is placed inside of a scroll view that framed according to the size and position defined for the actor. Unlike default actors, a scrollable actor does not scale its image. Instead an image larger than the frame specified will scroll either vertically or horizontally (or both) as needed to display all of the image. In the above example, only 30 pixels by 60 pixels of larger-image.png will be shown at a time.
Note: Scrollable actors can still have actions that will be triggered when you tap directly on the actor (without gesturing to scroll the actor up and down).
As stated above, actors can perform an action when tapped. Not all actors need perform an action, (it’s an optional property) but it is the primary way you navigate from scene to scene. Actions can be performed on scenes and other actors — an actor can even act upon itself!
To invoke an action when an actor is tapped, merely add the action: property to your actor definition. As so:
actor: Little Less Conversation
frame: 0, 0, 50, 50
action: goto(Little More Action, slideLeft)
The action property defines a goto operation which will send the user to the “Little More Action” scene using the slideLeft transition.
The goto action, show in the example above, allows an actor to navigation the brief to the scene defined in the goto property declaration. Optionally, the user can specify a transition (defined later). The scene is identified by name for ease of use.
An example scene group that contains a goto:
scene: Little Miss Muffet
image: muffet.png
actor: Sitdown
frame: 0, 0, 50, 50
action: goto(A Truffet, zoomIn)
scene: A Tuffet
image: tuffets.png
# blank scene for illustration
In the example above, the actor “Sitdown” takes the user to the scene “A Tuffet” when tapped.
Actors can also perform actions on other actors (or even themselves). Animating controls is a common idiom in iPhone programming and essential part of the user experience on the device. For instance, the keyboard will slide into view when the user needs to enter text.
To accomplish this in Briefs, one would include the following:
scene: Great American Novel
image: composer-window.png
actor: Show me the Keyboard
frame: 20, 127, 280, 80
action: move(Keyboard, 0, 220)
actor: Keyboard
image: keyboard.png
frame: 0, 480, 320, 259
In the above scene, there are two actors: the first displays the keyboard, while the second is the keyboard image itself. When the scene is first display, the “Keyboard” actor is drawn off-screen. The actor, “Show me the Keyboard” contains the move action that will slide the keyboard from it’s current position (0, 480) to a new position (0, 220). The new position causes the “Keyboard” actor to be visible on screen.
The move action takes three parameters: (1) the Actor name, (2) the x position to move the actor and (3) the y position to move the actor. When an actor with a move action is tapped, the actor specified will be animated to the new location from its current position.
In addition the move action, an actor can also resize itself or another actor. The syntax is very similar to the move command:
scene: Size Does Matter
image: spitting-match.png
actor: Super-size Me
frame: 0, 0, 50, 50
action: resize(Just Right, 200, 100)
actor: Honey, I Shrunk the Actor
frame: 0, 75, 50 50
action: resize(Just Right, 50, 50)
actor: Just Right
frame: 50, 100, 100, 75
Above you see two different actors with resize actions, one that shrinks the “Just Right” actor and another that expands it. Like the move action, the resize takes three parameters: (1) the Actor name, (2) the new width of the actor, (3) the new height of the actor. When an actor with a resize action is tapped, the specified actor will animate itself to the new size.
Note regarding the stacking order of actors: Resizing or moving an actor does not change its ability to trigger its own action. However, if you move or resize an actor such that its final state is below another actor, it’s possible to obscure its ability to trigger an action. Actors are stacked by the order they appear in the scene description. For example, in the example above, the “Just Right” actor sits above the other two actors since it is specified last.
Within a given scene, it is sometimes desired to have actors appear only when needed (perhaps for a particular workflow). A scene can also be hidden at launch by using the visible property.
Consider the example below:
scene: I can see the Light
image: dark-place.png
actor: Show me the Light
frame: 0, 0, 50, 50
action: show(The Light)
actor: Put out that Light
frame: 0, 75, 50, 50
action: hide(The Light)
actor: The Light
frame: 100, 100, 120, 120
image: thelight.png
visible: false
Above you’ll notice the actor, “The Light” is not visible when the scene is first shown. The actor “Show me the Light” uses the show action to show “The Light,” while the the actor “Put out that Light” will hide “The Light” using the hide action. The only parameter for both actions is the name of the actor they wish to act upon. Unlike all other actions, the show action cannot be performed on the actor specifying the action. Only for the simple reason that a hidden actor will not trigger an action when tapped.
When discussing the alternative images that can be provided for an actor, a disabled property defined the image that would be shown when an actor was disabled. To disable an actor, one would use the toggle property, specifying the actor (by name) that wants to be disabled.
Example:
scene: Don't Cry For me
image: argentina.png
actor: Disable the Button
frame: 0, 0, 50, 50
action: toggle(The Button)
actor: The Button
frame: 10, 40, 300, 65
image: button.png
disabled: button-disabled.png
In this example, one the first actor (“Disable the Button”) is tapped, “The Button” will switch from displaying the “button.png” to the “button-disabled.png” for the actor. Also, an actor that has been disabled cannot be tapped. This means that a disabled actor becomes a bystander, unable to perform its action.
The iPhone put straightforward animation in the hands of everyday developers. As such, animations are an integral part of the iPhone experience and something that should be conveyed in early mockups. Briefs supports six standard scene transitions that can be attached to the goto action.
Consider the example:
actor: Zoom, Zoom
frame: 0, 0, 50, 50
action: goto(Infinity & Beyond, zoomOut)
The actor “Zoom, Zoom” above performs an action that navigates to the scene “Infinity & Beyond.” The second parameter in the goto action specifies that the current scene should be zoom forward and cross-faded with the incoming scene, “Infinity & Beyond.” (similar in feel to animation which occurs when an app is launched from the home screen)
Each of the six transition types has a default direction or you can override it with any of the supported directions. Below is a description of each transition along with supported directions.
Note: The transition and direction can be offered together, as seen above, or separately e.g., goto(Table Details, push left).
The most common animation seen in iPhone applications occurs when you select an item in a table and the new view “pushes” the existing view off the left side of the screen. This is the default animation that is built-in to the iPhone OS as part of the UINavigationController. You can mimic that animation by using the push transition, specifying the left direction.
An example of this:
actor: Standard table stuff
frame: 0, 0, 320, 40
action: goto(Table Details, pushLeft)
Supported Directions: left, right, up, down.
The standard utility application template, provided by Apple, defaults a standard view that one flips over horizontally to reveal the another view when a standard information button is tapped. To accomplish a similar transition between two scenes in Briefs one can use the flip transition.
Example:
actor: Later Holmes
frame: 0, 0, 50, 50
action: goto(The Flip Side, flipRight)
Supported Directions: left, right.
One of the more distinctive animations on the iPhone is the page curl animation. If first appearing in the Notes app that shipped with the original iPhone, seen when one navigates to another page. In Briefs this is primarily a vertical curl (the iPad has numerous examples of horizontal page curls).
Example use:
actor: Curling Iron
frame: 0, 0, 50, 50
action: goto(Curl your Hair, curlUp)
The above example will curl the current scene upwards to reveal the “Curl your Hair” scene below.
Supported Directions: up, down
The cover transition is the first of two basic animations that involve sliding an incoming scene on top of the existing scene. Any direction is supported, while the bottom direction will directly emulate a modal view in standard iPhone parlance.
Consider the following example:
actor: Pop Modal View
frame: 0, 0, 50, 50
action: goto(Modal View, coverUp)
By tapping the “Pop Modal View”, the “Modal View” scene will be brought in from the bottom of the screen, covering up the existing scene.
Supported Directions: left, right, up, down.
The converse of the cover transition is the reveal transition which slides away the current scene to reveal the new scene below it. Continuing the modal view example, the reveal transition should be used when one wants to dismiss the modal view returning to the original.
Consider an expanded example from above:
scene: Standard View
image: standard.png
actor: Pop Modal View
frame: 0, 0, 50, 50
action: goto(Modal View, coverUp)
scene: Modal View
image: modal.png
actor: Dismiss Modal View
frame: 0, 0, 50, 50
action: goto(Standard View, revealDown)
In this expanded example, the second scene “Modal View”, contains an actor “Dismiss Modal View” that will return the user back to “Standard View.” The reveal transition is used to animate the scene when it is dismissed.
Supported Directions: left, right, up, down.
Supported Directions: in, out.