- Home
- Download
- Documentation
- FAQ
- Contact Us
Documentation
Want to write a Jarnaby story? Just follow these instructions:
Developing Your Story
First, decide what story you want to tell. The beauty of Jarnaby Reader is that it lets the reader view a story from the perspective of multiple characters, so an ideal Jarnaby story should have multiple characters that collaborate some of the time, but also do things on their own. We suggest writing down your story as a storyboard and working on each character's path through the story separately. Your story's plot will dictate when the characters' paths intersect and diverge.
As you develop each character's path, plan strategic locations where you want to insert links from one character's path to another. Make sure you have prepared text and/or artwork for each page of your story. Once you have everything planned out and ready, you can then go on to create the .xml file which Jarnaby Reader uses to render your story.
Creating Your Story's .xml File
Jarnaby Reader uses the simple XML structure of elements and attributes to bring your story to life. The general format for a Jarnaby story .xml file is divided into three main sections: Image creation, Page creation, and Path creation. We recommend first-time users to refer to the sample Little Red Riding Hood .xml file as an overall example. To keep things simple we'll start at the top and work our way down.
All story files must begin with an opening <jarnaby> tag along with the version number(example: <jarnaby version="1.0">). Below that you'll need an opening <story> tag. These two tags will enclose the whole file. The first thing below the <story> tag will be the <title> element, the contents of which will designate the title of your story (example: <title> Little Red Riding Hood </title>).
Following the <title> element you will use a series of <image> elements to designate the images which you will be using for your story. The <image> element has two attributes: 'id' and 'file'. The 'id' will be a single string used to distinguish each image, and the 'file' will be the file name of the image (example: <image id="lrrh_intro" file="lrrh_intro.png"/>).
Next, you will use the <page> element to put together each page of your story. The <page> element has two attributes: 'id' and 'image_id'. The 'id' is an integer used to distinguish each page, and the 'image_id' is the 'id' of the image (set in the previous section) which will be displayed on that page (example: <page id="1" image_id="lrrh_and_mom">). Within each <page> element are two additional elements: <text> and <link>. The contents of the <text> element will be displayed as the story text for that page. The <link> element is used to designate points where the reader may switch to another character's perspective path, it has three attributes: 'pageref', 'pathref' and 'text'. The 'pageref' is the 'id' of the page to which the link leads. The 'pathref' is the 'id' of the path (set in the next section) to which the link leads. The 'text' is the word within the page's text which will become clickable in order to follow the link (though this feature is not yet implemented in the Android version as of 1.0). Within the <link> element there is an optional <rect> element which designates a specific area of the page's image which may be clicked to follow the link, it has four attributes: 'x', 'y', 'width', and 'height'. The 'x' and 'y' designate the pixel location of the top left corner of the area, the 'width' and 'height' are the dimensions of the area. All four attributes are expressed in relation to the image size as a number between 0 and 1 (example: <rect x="0.25" y="0.3428" width="0.1562" height="0.2142"/>).
Lastly, you will use the <path> element to compose the series of pages which constitute each characters' path. Two of the attributes, 'name' and 'id', are used to distinguish each path (example: <path name="Grandma" id="3">), while the third attribute, 'default', designates the default or beginning path. Within the <path> element will be a series of <pageref> elements which have but one attribute, 'id', which contains the 'id' of the page to be displayed at that position in the path (example: <pageref id="19"/>). Once you have created <path> elements for each character's path, close it all up with the ending </story> and </jarnaby> tags, and you're done!
Testing Your Story on Jarnaby Reader
To try out your story on the Android version, all you need to do is place the folder containing your story (xml file, image directory, and sound directory) into the "stories" folder located within the "Jarnaby" folder which was created when you first ran Jarnaby. Once you have done this, the next time you start up Jarnaby a screen will come up in which you can choose to view your story.
For the iOS version, you will need to download the source code for Jarnaby. It is distributed as a zipped Xcode project. Extract the source into the IDE of your choice, and test it to make sure it works. You will be replacing the default story (Little Red Riding Hood) with your own. You will also need to replace all the images in the images folder, copying in the images from your story.
Element Index
*text links not yet implemented
