oren / mithril-employee-directory

Mithril version of React-employee-directory

Sample Mobile Application with Mithril and Cordova

Mithril is my favorite Javascript framework. It has a simple API, it's lightweight, it's very fast and it's just Javascript. I believe it deserves a few more tutorials and sample applications to illustrate how great it is.

Inspired by what Jonny Buchanan (@insin) did for large datasets, this tutorial is unashamedly copying a sample mobile app developped by Christophe Coenraets (@ccoenraets), a developer evangelist working at Salesforce, who regularly publishes awesome tutorials, using the latest javascript technologies. His blog can be found here and the model for the following tutorial can be found here.

The focus of this tutorial will be to highlight the similarities and differences between React and Mithril, when developing this sample application.

• No JSX, no tools, only javascript
• No templates: Components are the building blocks. By keeping the markup and the corresponding UI logic together, you have the full power of Javascript to express the UI.
• Virtual DOM. In Mithril, rendering a component means creating a lightweight description of the component UI. Mithril diffs this new description with the old one (if any), and generates a minimal set of changes to apply to the DOM.

Introduction

As @ccoenraets says, there is nothing like building an app to get familiar with a new language or framework. “App” is the application container that will transition pages in and out of the UI. Only one page is displayed at any given time.

In this article, we will build the application going through several iterations, from a simple static prototype to the final product. The source code for the application, including the different iterations and a Cordova version, is available in this repository. If you plan to run the application locally, you need to load it from a local web server, not from the file system

Iteration 1: Static Version

In this first version, we create and render the HomePage component with some hardcoded (static) sample data.

View source | Run it

Code Highlights:

We create 3 mithril components for our website: Header, SearchBar, and EmployeeList.

Creating components is easy: You create a JavaScript object with a key called 'view'. This key is a function that returns the UI description. The element returned by the view function is not an actual DOM node: it’s a description of the UI that will be diffed with the current description to perform the minimum set of changes to the DOM.

Using a component is done with the m.component() function - m.component(EmployeeList). For example, HomePage is made of three other components: Header, SearchBar, and EmployeeList.

Side Note: If you don't like the sytax of m('input[type=search]') you can use MSX (which is similar to JSX in React).

Iteration 2: Data Flow

In this second version, we define an array of employees in the HomePage component, and we make the data flow down the component hierarchy to EmployeeList and EmployeeListItem. In this version, the list of employees is hardcoded: we’ll work with dynamic data in iteration 4.

View source | Run it

Code Highlights:

In JSX, you can add attributes to your custom component tags to pass properties to the component instance.

m.component(EmployeeList, {employees: employees})

Properties passed by the parent are available in this.props in the child. For example EmployeeList can access the list of employees provided by HomePage in this.props.employees. In a list component (like EmployeeList), it’s a common pattern to programmatically create an array of child components (like EmployeeListItem) and include that array in the JSX description of the component.

var EmployeeList = {
	view: function(ctrl, args) {
		var items = args.employees.map(function(employee) {
			return m.component(EmployeeListItem, {
				key: employee.id,
				employee: employee
			})
		})
		return m('ul', items);
	}
}

The key attribute (like in EmployeeListItem above) is used to uniquely identify an instance of a component (useful in the diff process).

Iteration 3: Inverse Data Flow

In the previous version, the data flew down the component hierarchy from HomePage to EmployeeListItem. In this version, we make data (the search key to be specific) flow upstream, from the SearchBar to the HomePage where it is used to find the corresponding employees.

View source | Run it

Code Highlights:

In this version, the inverse data flow is implemented by providing the child (SearchBar) with a handler to call back the parent (HomePage) when the search key value changes.

Iteration 4: Async Data and State

In this version, we implement employee search using an async service. In this sample app, we use a mock in-memory service (defined in data.js) that uses promises so you can easily replace the implementation with Ajax calls. We keep track of the search key and the list of employees in the HomePage state.

View source | Run it

Code Highlights:

The state (this.state) is private to the component and is changed using this.setState(). The UI is automatically updated when the user types a new value in SearchBar. This is because when the state of a React component is changed, the component automatically re-renders itself (by executing its render() function). getInitialState() executes once during the component lifecycle and and is used to set up the initial state of the component. ###Iteration 5: Routing

In this version, we add an employee details page. Because the application now has more than one view, we add a simple view routing mechanism.

View source | Run it

Code Highlights:

There are many options to implement routing. Some routing libraries are specific to React (check out react-router), but you can also use other existing routing libraries. Because the routing requirements of this sample app are very simple, I used a simple script (router.js) that I have been using in other sample apps.

componentDidMount() is called when a component is rendered.

Iteration 6: Styling

Time to make the app look good. In this version, we use the Ratchet CSS library to provide the app with a mobile skin.

View source | Run it

Code Highlights:

Notice the use of className instead of class

Iteration 7: Maintaining State

If you run iteration 6, you’ll notice that when you navigate back to HomePage from EmployeePage, HomePage has lost its state (search key and employee list). In this version, we fix this problem and make sure the state is preserved.

View source | Run it

Code Highlights:

To keep track of the state, we introduce a new parent container (App) that maintains the state (searchKey and employee list) of the Home page and reloads it when the user navigates back to the Home Page.

Iteration 8: Adding animations

Coming soon!

Iteration 9: Running in Cordova

Coming soon!