Mulberry from Toura is a mobile application framework built on top of PhoneGap. Within minutes, Mulberry can have you up and running with a native application built with web technologies like HTML, CSS, and JavaScript.
Prerequisites
Let's take a look at what we need to get started with Mulberry.
At the moment, Mulberry only officially supports OS X Snow Leopard and Lion. According to the documentation, it might be possible to run on Linux, but doing so is not fully supported. In addition to a compatible OS, you will also need the latest version of PhoneGap and Ruby should also be installed.
In order to complete this tutorial, you should also have some experience using git.
Step 1: Download and Install
You can get the latest version of Mulberry from Toura's github repository. You can clone the repository to the directory of your choosing using the command git clone [email protected]:Toura/mulberry.git
Next, we need to add the full path to mulberry/bin to our environment path variable, so we need to edit our .profile file. We can do this by executing the following command in the terminal.
export PATH=$PATH:/path/to/mulberry/mulberry/bin
If you do not have the Ruby gem 'bundler' installed, you will have to go ahead and install that now, like so:
sudo gem install bundler
And then from the root of the repository run the command:
bundle install
Now you are ready to build your first app with Mulberry.
Step 2: Scaffolding Your First App
To get our application structure we need to run the following command in the terminal wherever we want the app to be built. Let's say we want to make an app for cat lovers and we are going to call the app Cats.
mulberry scaffold cats
You'll get a bunch of copyright material and some basic terms and conditions spit out at you, but what will also happen is your app structure has now been done for you. Open up your project folder and take a look.
The first thing we need to do is go ahead and open up the config.yml file and make some changes if needed. The config file is really well commented, and so it is pretty easy to see what you need to add or modify. You will see your app name and the theme details. At the moment, there is no documentation on theming, but you can set some base colors here. You can then specify the platforms you are building for. For this demo, I'm just going to build for iOS, so I will delete the Android option. I am also going to just target the phone platform too, so delete the tablet option.
You can see that we can choose whether we will include jQuery in the project and then there are some API options for Facebook, Twitter, Urban Airship, and Flurry. I'm sure that we are all aware of the first two, but Urban Airship is a service for push notifications over the air. Flurry is a traffic analytics tool specifically made for mobile applications. For this demo, I'm not going to go into details of the integration of these APIs with Mulberry, so I'll just leave those fields blank.
Save your config file and open the sitemap.yml file. This is where we will set out the page structure for our app. You can see we already have two entries Home and About. We are going to add some links to our home page next:
- home - black-and-white - cats-with-macs - cats-with-hats - kittens - about
Now we need to generate the new pages we have defined in our site map. Go back to your terminal and enter the following:
mulberry create_page black-and-white
You will get a confirmation of the page being created. The pages are created in the Markdown format. If you've never used Markdown before, don't worry, there is nothing overly complicated about it. In fact, it's one of the really nice things I like about Mulberry, as I use the markdown format on a daily basis. Once you are used to the simple syntax, it really is quicker than writing pages in HTML.
We can go ahead and use the same command to create our other pages, and once they're done, you will find them in the pages folder.
Step 3: Working with Pages
If you go ahead and open up the markdown files you will see that the file has a header represented by the --- characters:
--- title: # required! template: phone: default tablet: default # these should optionally point at an image in the images dir header_image: background_image: # each of these properties can include an array of filenames images: videos: audios: feeds: locations: data: ---
Let's edit this header for what we need. For now, we don't need the header image or background, and as we are just targeting phones, we can set that template to images-and-text-phone which is a predefined template built into mulberry. We are also going to be just using images for now, so the head of your file should look just like this for now:
--- title: Black and White template: phone: images-and-text-phone images: - cat-bw-1.jpg - cat-bw-2.jpg - cat-bw-3.jpg ---
The images are located in an images folder within the assets folder.
Note: The amount of whitespace when you indent something is important. Be sure that your tabs are set to 2 spaces, otherwise the code will not compile correctly.
Head back to your terminal and type mulberry serve. All the content will then be ready for viewing in a browser or the iOS Simulator on your localhost (usually port 3000).
Step 4: Other Pages, Videos, and Captions
Let's go ahead and modify the header of some of the other pages.
--- title: Cats with Hats template: phone: images-and-text-phone images: - hats-1.jpg - hats-2.jpg - hats-3.jpg ---
--- title: Cats with Macs template: phone: images-and-text-phone images: - macs-1.jpg - macs-2.jpg - macs-3.jpg ---
Let's also take a look at what the video template will look like.
--- title: Kittens template: phone: videos-and-text-phone videos: - kitten.mp4 ---
Go ahead and run mulberry serve again and check the output in a browser. It should look something like this -
And the video page should look like the following -
Let's have a quick look at the captions that you can create for these carousels of images or videos.
Create three files in the images/captions folder and name them imagename.md, so for the demo I have created cat-bw-1.md, cat-bw-2.md, cat-bw-3.md. Each of the files looks something like this:
--- name: Cat 1 --- This is a Black and White Cat
Now if you serve your app again, you will see the content below the images change as you flick through the images:
Step 5: Testing Your App
Open your terminal and run mulberry test. Your code will now compile in a builds folder. Xcode will launch and you will see your app's structure, including a www folder where all your files are. You can now hit build and run in Xcode and your app will launch in the simulator as a native running application.
The Debug Bar
Mulberry now comes with built in support for Weinre which is a web inspector targeted at mobile devices (it's awesome!). The small toolbar in the bottom right of your corner allows you to use Weinre on Toura's own hosted version of Weinre. If you go ahead and click the Weinre button, you will get a code that you can enter on the site to get a remote debugger up and running. With this, you can test out Javascript or CSS to see how your DOM has been constructed by Mulberry.
To turn off the debug bar on the bottom right of the screen there are some options located in the TouraConfig.js file located in build/www/javascript/toura/app that you need to configure. You can see a full overview of the features here but the ones you want to set to false are debugToolbar and debugPage. debugPage is an in-app debugging page. You're going to want to turn these off before you build your app ready for production.
Step 6: Deploy
When you are ready to deploy, just run mulberry deploy in your terminal and all the various binaries for your devices specified in the config.yml file will be created.
More to Explore
There is so much more to explore in Mulberry apart from what I've been able to show in this very high-level overview. The purpose of this tutorial is really just to show you how quick and easy Mulberry is to use. If you are feeling brave, check out some of the demos that come with the Mulberry repository, where you will find a great kitchen sink app that pretty much gives you many of the things you might like to use.
If you'd like to know more about Mulberry, the official documentation is pretty good, although it is still a work in progress. If you would like to see a more thorough and in-depth look at Mulberry development, including creating components for things like Twitter and Facebook, let us know in the comments section!
Comments