Mojito Quickstart Guide

The Mojito QuickStart Guide is both an introduction to Mojito concepts and an example application.

The application has twelve tiles that you can click or tap to learn the basics of Mojito. The layout adapts to the device used to view the application--tiles rearrange themselves on a tablet or phone for better usability.

The application is available at http://y.ahoo.it/mqsg. See also the Mojito documentation.

Copy and Run the Application Locally

git clone git://github.com/yahoo/mojito.git
cd examples/quickstartguide
npm i
./script/start_server

You can now view the application at http://localhost:8666/.

Analysis

The Mojito Quickstart Guide provides a total of 12 documentation topics that are stored locally for reading.

Tiles (Topics)

Each tile displayed by the application represents a documentation topic. These topics, also known as "guides", are static Markdown (.md) files that reside in a guides/ directory. The titles of the tiles are based on the top-level heading of Markdown files. Since all the data is in guides/, we use one centralized model to access this dataset. Next, let's look at the mojits and the model that power our application.

Breakdown of the Mojits and the Model

Shelf Mojit

The Shelf mojit iterates through each Markdown files to obtain the titles. For each title, Shelf will display it in an independent tile and also add a link to introduce the tile to the Read mojit.

1. Create a container for the tiles.
2. Access model getGuides() to obtain the guide titles and filenames.
3. Iterate through each guide, push into tile collection, and create a link to map the tile to Read mojit.
4. Display the tile. Use CSS to expand the clickable area over the entire tile.

Read Mojit

The Read mojit will take raw Markdown file and render it into HTML and display the content.

1. Obtain the filename from URL parameters.
2. Access the model with getGuide() with filename to obtain the raw Markdown file.
3. Access model method getAdjacentGuideFilenames() to find out the prev/next guides of the current guide and provide a link to each.
4. Render the Markdown.
5. Display the guide and links to other guides.

Model

In this application, both Shelf and Read mojits access the same data set: the guide files. Therefore, there is only one universal model to support both of the mojits.

1. Load necessary configs or libraries with the public function init.
2. Return the filenames and displays the title of each guide with public function getGuides.
3. Take the filename and output the raw content of the guide with public function getGuide.
4. Take the filename and return the links to sibling guides with public function getAdjacentGuideFilenames.

Application Logic Flow

All Mojito applications have a similar application flow. The diagram below gives an overview of the logic flow of this application.

Logic Flow for the Landing Page

The logic flow below describes what happens when you start the application and see the landing page that displays twelve topic tiles.

1. http://y.ahoo.it/mqsg: Starting with accessing the Web app on http://y.ahoo.it/mqsg, and it brings you to the index view of the application.

2. routes.yaml: To find out what happened in the code, we come to routes.yaml to determine which instance is called. In this case it's something called shelf.index. We can then tell it's calling an index from a shelf so we go to application.yaml to figure out what index or shelf mean.

3. application.yaml: In application.yaml, we see shelf is under master specs and it's an HTMLFrameMojit that has a child of a type Shelf. shelf.index calls the index method of a HTMLFrameMojit, but actually all HTMLFrameMojit does is just to generate an HTML skeleton, and pass the rest of the executions to its children's index method, Shelf mojit in this case.

4. mojits/Shelf/controller: Now we realize it's calling index method of Shelf, which contains the main logic to pull out data and show them to display.

5. models/GuideModel: In the index function, you can see there is a call: model.getGuides() which goes to the model, so we come to models/GuideModel to see how data is obtained there. (Sometimes you will have different models for different mojit, but in this case, both Shelf and Read mojit access the same data set, so it becomes a global model)

6. mojits/Shelf/views/index: In the end of index function of Shelf controller, ac.done(view_data) is called, which will pass the view_data to mojits/Shelf/views/index to display in Handlebar syntax.

Logic Flow for Viewing Documentation Pages

The logic flow below describes what happens when a tile is clicked to read a topic.

1. http://y.ahoo.it/mqsg: Go to http://y.ahoo.it/mqsg and click on any of the tiles. You will notice the URL end with read.html?filename=0X.XXXXX format.

2. routes.yaml: To find out what happened in the code, we come to routes.yaml to determine which instance is called. In this case it's read.index. We can then tell it's calling index method on read. so we go to application.yaml to figure out what read mean.

3. application.yaml: In application.yaml, we see read is under master read and it's an HTMLFrameMojit that has a child of a type Read. read.index calls the index method of a HTMLFrameMojit, which passes the executions to its children's index method, Read mojit in this case.

4. mojits/Read/controller: Now we know it's calling index method of Read, which processes the main logic to pull out data and show them to display.

5. models/GuideModel: In the index function, there is a call: model.getGuide() which goes to the model, so we come to models/GuideModel to see how data is obtained there.

6. mojits/Read/views/index: In the end of index function of Read controller, ac.done(view_data) is called, which will pass the view_data to mojits/Read/views/index to display in Handlebar syntax.

7. mojits/Read/binders/index.js: After view is generated, the associated binder will be executed. e.g. index.js will run after index.html(naming convention). In this case, we can come to mojits/Read/binders/index.js and see what happens after the view is generated.

Mojit Logical Flow

Shelf.index Flow Diagram:

Read.index Flow Diagram:

See Also

• Mojito Introduction
• More code examples:
  • Basic Configuration of Applications
  • Configuring Routing
  • Simple Logging
  • Creating a Simple View with Handlebars
  • Adding CSS
  • Generating URLs
  • Localize program generated strings
  • Frame Mojit
  • Startup Requirements for Mojito in Hosting Environments