Advanced

This section is for developers who need a full understanding of the MH5 Framework for Mobile HTML5, because the predefined configuration is not enough for their goals. Here you will find out how to create your own pages and lay them out.

To get started quickly, refer to the API Reference to see the entire JavaScript documentation of the MH5 Framework for Mobile HTML5. Otherwise, feel free to browse through the main topics of the MH5 Framework for Mobile HTML5 below.

Figure 1. MH5 Levels

Core Level

The lowest level of the MH5 Framework for Mobile HTML5 is the core level. It contains helpers to build classes, to manipulate DOM, and other various utilities. Check out API Reference for more details.

UI Framework Level

The second level of the MH5 Framework for Mobile HTML5 is the UI Framework level. It contains basic UI controls like button, list, text input, and so on. All of them are built on top of nokia.mh5.ui.Control. More complex controls containing other controls as children are derived from nokia.mh5.ui.Container. The namespace nokia.mh5.ui provides also a possibility to lay out children inside a container. For example:

var actions = {
	control: nokia.mh5.ui.Container,
	layout: {
		type: nokia.mh5.ui.ColumnLayout
	},
	children: ["dial", "share", "route", "website"],
	dial: {
		control: nokia.mh5.ui.Button,
		text: "Call"
	},
	share: {
		control: nokia.mh5.ui.Button,
		text: "Share"
	},
	route: {
		control: nokia.mh5.ui.Button,
		text: "Route"
	},
	website: {
		control: nokia.mh5.ui.Button,
		text: "Web"
	}
};

The most complex container is called nokia.mh5.ui.Page. The best feature of this container is that it completely fills the DOM node containing the application. Check out the namespace nokia.mh5.ui for more details.

Component Framework Level

Complex elements containing a whole functional flow are called components. Check out the Components section of this documentation and the namespace nokia.mh5.components for more details.

Application Framework Level

This level makes it easier to build an application. An application in the MH5 Framework consists of pages. By defining different application layouts, you can define not only a different set of pages but also a different controller for every target platform if the application flow is different. Please note that each of these controllers must implement the switchTo function. For more details check out nokia.mh5.app.controller. You cannot access the active controller directly; therefore, you must access them via nokia.mh5.app.controller. By default, the MH5 Framework for Mobile HTML5 provides two layouts: nokia.mh5.app.phoneLayout and nokia.mh5.app.tabletLayout, as well as a default controller nokia.mh5.app.controller, which is currently the same for both layouts. The proper layout from these two will be selected automatically. Of course you can overwrite this default layout or define your own ones with a specific application flow. In the latter case, you will need to define a handler that decides at runtime which layout should be selected on the current device.

nokia.mh5.app.embed ({
	domNode: "#node",
	appId: "_peU-uCkp-j8ovkzFGNU",
	appCode: "gBoUkAMoxoqIWfxWA5DuMQ",
	layouts: ["myLayout1", "myLayout2"],
	myLayout1: {
		controller: myController1
	},
	myLayout2: {
		controller: myController2
	},
	getLayout: function () {
		if (isLayout1Better) {
			return "myLayout1";
		} else {
		return "myLayout2";
		}
	}
});

As mentioned earlier, layouts define pages (nokia.mh5.ui.Page). If you do not define an initial page, the first page from the "pages" property will be taken.

nokia.mh5.app.embed ({
	domNode: "#node",
	appId: "_peU-uCkp-j8ovkzFGNU",
	appCode: "gBoUkAMoxoqIWfxWA5DuMQ",
	layouts: ["myLayout1", "myLayout2"],
	myLayout1: {
		controller: myController1,
		pages: ["page1", "page2"],
		initialPage: "page2"
	},
	myLayout2: {
		controller: myController2,
		pages: ["page1", "page3"]
	},
	getLayout: function () {
		if (isLayout1Better) {
			return "myLayout1";
		} else {
			return "myLayout2";
		}
	}
});

Now you can define the content of every single page you have.

nokia.mh5.app.embed ({
	domNode: "#node",
	appId: "_peU-uCkp-j8ovkzFGNU",
	appCode: "gBoUkAMoxoqIWfxWA5DuMQ",
	layouts: ["myLayout"],
	myLayout: {
		//let's take the default one
		controller: nokia.mh5.app.controller,
		pages: ["page1", "page2"],
		initialPage: "page1"
		page1: {
			children: ["map", "forward"],
			layout: {
				type: nokia.mh5.ui.RowLayout
			},
			map: {
				control: nokia.mh5.components.Map
			},
			forward: {
				control: nokia.mh5.ui.Button,
				text: "Page2",
				onClick: function () {
				nokia.mh5.app.controller.switchTo ("page2");
				}
			}
		},
		page2: {
			children: ["label", "back"],
			layout: {
				type: nokia.mh5.ui.ColumnLayout
			},
			label: {
				control: nokia.mh5.ui.Control,
				rootHtmlElementName: "label",
				innerHTML: "You are on page 2"
			},
			back: {
				control: nokia.mh5.ui.Button,
				text: "Page1",
				onClick: function () {
					nokia.mh5.app.controller.switchTo ("page1");
				}
			}
		}
	}
});

Check out the namespace nokia.mh5.app for more details.

MVC (Model-View-Controller) and MH5

MH5 supports the MVC concept to some extent. There is no native model for the entire application but rather for every page. Based on the application flow, we figured out that there is not much common data among pages. The views are instances of nokia.ui.Page. The controller is nokia.mh5.app.controller.

Every page has its own model nokia.ui.Page.model object, which can contain whatever data you want. But the model does not provide any validation of data. So it is up to you to take care of it. If you want to be notified in the case of any updates of a specific property, then use the concept of MH5 bindings nokia.mh5.ui.Control.watch. Below you can find how the application flow exactly happens. Note that every change of the "visible" property of the page notifies the visibileDidChange function.

Figure 2. MVC Diagram

How can my application benefit from the native browser history?

The MH5 Framework for Mobile HTML5 enables you to attach the native browser history changes to your application. That means you can benefit from the usage of the browser's back/forward buttons into your application flow. To achieve that MH5 uses the HTML5 history API. You can get a good overview from Mozilla's Developer Network.

If you use the application layer of the MH5 Framework for Mobile HTML5 and the default nokia.mh5.app.controller, then the necessary methods are already in place. If you call the nokia.mh5.app.controller.switchTo function to switch to a new page, then it will push the new page to the history stack. You can influence this through "switchToParams" parameters of the function. If you set the switchToParams.dontPushToHistory property to true, then the new page will not be pushed. If you set the switchToParams.replaceLastHistoryEntry to true, then the new page will replace the current one on the history stack instead of being just pushed to it.

If referring to pushing a page to the history stack, then that means to push a state of it. The state of the page is returned by the nokia.mh5.ui.Page.getNavigationState function. The default state will be the content of nokia.mh5.ui.Page.model. This means that if the user clicks the forward/back button in the browser and lands on a page previously put to the history stack, then the controller will call the nokia.mh5.ui.Page.setModel function with the state from the history and then set the "visible" property of the page to true.

Sometimes it makes sense to push a new state to the history staying on the same page. For example, you want to put all of a user's search requests that are triggered on the search page to the history stack, so that the user with the back button can go through the all previous search results. In this use case, you can use the nokia.mh5.app.controller.pushHistoryEntry function every time the user triggers a new search. Other times you may just want to update the current history state without switching to another page. In this case, you might want to keep only the latest search result in the history, so that the user jumps over all previous search results with one click on the back button. For this use case, you can use the nokia.mh5.app.controller.updateHistoryEntry function every time the user triggers a new search.

The MH5 Framework for Mobile HTML5 enables you to manipulate the URL at the same time that you change the history stack. This gives the user the opportunity to bookmark or to share the current state of the application (e.g., a special place or a special route). Every time the history is manipulated by the controller, the nokia.mh5.ui.Page.getHash function is called. The returned value is added after the "#" to the base URL of your web application.