A toolkit for making interactive iPhone wireframes. (@briefsapp on Twitter)

This framework is currently a work in progress. Please contact me with any questions about future status and feature requests.

[email protected]

The Briefs toolkit was created for rapidly building & iterating app prototypes for the iPhone. These prototypes run directly on the phone, like actual apps, but require much less time and code to produce. Less code means faster cycles and cheaper development.

The purpose of Briefs is to create better apps that have a tested interaction design before they are built. Unlike traditional mockups, briefs are used just like an actual app not just seen. And because they use the same frameworks that regular apps are built upon, briefs can potentially take advantage of animation, device rotation and gestures. You can even design the experience around app interruption due to an incoming phone call. Thinking about these interactions will ensure a more thought out experience for your users.

At it's core, each brief is merely a text file that references a series of static images. These text files carry the extension .brieflist and can be compacted, which dereferences the images embedding the raw data into the brief. This allows for only a single file to be transferred between you and your testers.

The organization of a brief is divided into scenes which represent a single state for any given screen inside of your application. Each scene contains a transition style that controls how the image associated with the scene appears and exits.

Controls and events are modeled as actors that belong to a given scene. An actor can also contain an image reference that is optional. The location, size and action must all be defined for an actor. (0,0) starts in the top-left and the size is specified in pixels.

A briefcast is a way to share your briefs with the world. It's a standard RSS 2.0 feed that uses enclosures (much like podcasts) to embed briefs inside. The briefs.app can read this feed and allows you to download the brief onto your device. With briefcasts you don't need Xcode to embed your briefs: instead copy new versions of your briefs to your briefcast, then pull them down on the device.

Briefs is comprised of three major projects, all hosted on GitHub. There is (1) this project, Briefs.app, (2) the Briefs-data project and (3) the Briefs-util project. All are combined to create the Briefs ecosystem.

First and foremost, Briefs is an application that runs on your iPhone. For testers of your briefs, this is the primary touch point of the toolkit. From the application, a user can organize briefs stored on the device, download new briefs using briefcasts and play those briefs on the device. The code inside of Briefs.app is responsible for playing and storing briefs.

The BFPresentationDispatch is a singleton class that launches a new brief after it is selected by the user. It contains a reference to a BFSceneViewController, the class that is responsible for rendering the current scene as it is selected by user action.

The Briefs-data project is a Cocoa library that reads, writes and manages briefs data. It is maintained as a separate project to enable enterprising Cocoa developers to build products that support the briefs data format. More information can be found on its project page.

Briefs-util is a series of utilities for authoring briefs. It includes a parser called BS that compiles .bs or briefscripts into the .brieflist format. Briefscript is a more concise language built for speed and readability. More information can found on its project page.

After you download the source, either by cloning the repository or downloading the source manually, open the project in Xcode. (if you are seeing missing files, see the section Installation Notes below to get them to appear) Once open, a quick Build & Go will launch briefs.app in the simulator.

1. Write a Brief

Start building your brief, first by visiting the Briefs-util project and downloading the bs parser. Read the documentation on the project page for writing a .bs file. The following code fragment is from a .bs file:

start: Springboard
defaultImage: imgs/blank.png

scene: Springboard
image: imgs/0-springboard.png

    actor: Pick SMS App    
        position: 19, 25 
            size: 55, 55   
          action: goto(Main)

Then compile the script (in the example, we're assuming the name foo.bs) running the following in terminal.app:

bs foo.bs > foo-source.brieflist

This will compile your script into a foo-source.brieflist file.

2. Compact the Brief

Inside Xcode, switch your target to BriefsCompactor and build the project. (You might have to switch the SDK) Copy the resulting script, compact-briefs onto your local path, for instance in /usr/local/bin/. Once on your path, go back to terminal.app and run:

compact-briefs foo-source.brieflist foo.brieflist

This will create a single file foo.brieflist that contains all of the raw image data.

3. Copy into Briefs.app

Back in Xcode (don't forget to switch your target back to Briefs), copy foo.brieflist into your Xcode project, under the group My Briefs. Make sure in the Briefs target the file is being copy under the Copy Bundle Resources task. Once again, select Build & Go and when Briefs.app launches you should see foo.brieflist in the table. Select the brief and see your prototype come to life.

Using the code below as a reference, change the relevant information and include references to your briefs inside the items section. It is important that you include a fully qualified path to your brief!

<?xml version="1.0"?>
<rss version="2.0">
    <channel>
        <title>Briefcast Demo</title>
        <link>http://giveabrief.com/briefcast/</link>
        <description> Demonstrate how awesome it is to use a briefcast to get briefs on the iPhone.</description>
        <language>en-us</language>
        <pubDate>Thu, 12 Nov 2009 03:05:00 GMT</pubDate>
        <lastBuildDate>Thu, 12 Nov 2009 03:05:00 GMT</lastBuildDate>
        <item>
            <title>Kitchen Shopping Sketch</title>
            <enclosure url="http://giveabrief.com/cast/shopping.brieflist" length="29230" type="application/brief" />
            <description>An example brief showing how you can use scanned-in pencil sketches.</description>
            <pubDate>Sun, 13 Sep 2009 03:05:00 GMT</pubDate>
            <guid>http://giveabrief.com/cast/1#item1</guid>
        </item>
    </channel>
</rss>

Copy this .xml file to your server in a publicly accessible location, along with any referenced briefs.

Where are the missing files? Oh no, Briefs is broken, why is it broken?

It's not broken, the Briefs-Data project is linked as a git submodule. So there are extra steps you have to take to pull down the data model code. The steps you take depend on how you put the project on your computer:

If you downloaded the bundle, go to the Briefs-Data project, http://github.com/capttaco/Briefs-data, download that project and place the unzipped contents into the /data directory. Open up Xcode and the missing files should have returned.

If you cloned (or forked) the repository from the public url, then you just have to initialize the submodule.

git submodule init
git submodule update

And you're done!

Why is Briefs-Data a submodule? Good question. We wrote it this way to maintain a separate Cocoa library that just reads and writes Briefs. Then later, after you've invested time and effort in writing Briefs, other savvy developers (perhaps yourself) can write & sell applications that can read your Briefs.

And since it's open-source, this ensures that you'll always have access to your data. Nobody likes closed data formats, and it guarantees you can still read your Briefs 50 years from now using your hyper-kinetic visor while teleporting to Mars.