Learning Onsen UI is not difficult at all. In this section, we’ll cover all the fundamentals for building your very first mobile app.
In the application world, a page is commonly referred as a window or a page view. In Onsen UI, a page is a container that fully covers the viewport (usually a screen). In Onsen UI, a page can be defined by wrapping in ons-page component.
The following sample code illustrates the most basic app that contains a page and toolbar. Inside the page container you can add any other native HTML DOM elements or Onsen UI components.
<body>
<ons-page>
<ons-toolbar>
<div class=”center”>Toolbar</div>
</ons-toolbar>
<!-- Your page content here. -->
</ons-page>
</body>
Now you’ve got your first Onsen UI app containing a single page! Adding more components will make this app even more great.
Usually, an app may have multiple pages with transitioning screens. In the next chapter, we will cover how to manage multiple pages.
Most applications have multiple pages (screens), which in Onsen UI can be achieved by defining multiple ons-page components.
In order to create multiple pages, we need to understand the concept of “template”. A template defines a generic layout that is used during execution time to create instances. If a template is modified at a given time, it won’t change the already created instances but will affect the ones created later on. In Onsen UI, this layout must always be an ons-page component (one single root node). Any other component must be a child of the page.
A template must be given a unique ID that will be used later on to reference the template. Templates can be defined in two different ways:
Separate files: *.html files that contain a single ons-page component as the root. Their ID is given by the path in the project, e.g. ./my/views/page1.html.
Using <template> elements inside index.html: Sometimes is useful to have a bunch of templates in the main file (index.html). HTML template elements can hold pages just like separate files do. Their ID must be manually specified by the id attribute. For example:
<template id="page.html">
<ons-page><!-- Content here--></ons-page>
</template>
<ons-template> element is also supported for the same purpose, but native <template> is preferred since v2.4.0
But, how can you move between these pages and switch their visibility? Onsen UI has 3 components that are used to manage multiple pages: ons-navigator, ons-tabbar and ons-splitter.
If the app contains multiple pages in a hierarchical order, consider using the navigator component. It provides a page stack where you can push and pop pages with transition animations. Check out ons-navigator reference.
If the app contains multiple pages at the same level, a tab bar is the appropriate choice. Users can pick which page to display by tapping the item on the tab. Check out ons-tabbar reference.
Although it is named a splitter, small devices will create a side menu which can be shown/hidden by the user interaction. On larger screens, this will split a single page into two. Check out ons-splitter reference.
By using these components, an app can have multiple pages, allowing creation of everything from simple to complex user interfaces. They are composable, meaning that you can combine them to achieve the desired routing for your specific app. In general, external routers are not necessary thanks to these 3 components.
Now you have the necessary skills and information to layout a page, as well as manage multiple pages. It’s time to access the component using JavaScript and make it a dynamic component.
The ons JavaScript object is globally available, and has several useful methods and properties.
For example, ons.ready(callback) method can be used to wait for app initialization. Specifically, this function waits until “DOMContentLoaded” and Cordova’s “deviceready” events are fired. This is useful, for instance, to know when is safe to make calls to Cordova APIs.
<head>
<script>
ons.ready(function() {
// Cordova APIs are ready
console.log(window.device);
});
</script>
</head>
Note that ons.ready() has nothing to do with ons-page initialization (see lifecycle section for that).
The Onsen UI component is a simple DOM Element (JavaScript object). Thus, it has its own properties, methods, and events. These can be used to configure behavior or call a specific function during runtime. Let’s take ons-navigator for example and see how it can be used.
An attribute either modifies the default functionality or specifies how the component should perform. Most of the attributes are optional. Note that some attributes need to be specified before the page initialization. For instance, ons-navigator can take “animation” attribute and change it at any time.
<ons-navigator animation="slide"></ons-navigator>
<script>
var myNavigator = document.querySelector('ons-navigator');
myNavigator.setAttribute('animation', 'lift');
</script>
A component has properties which can be accessed from DOM Element. For instance, you could access the topPage property of an ons-navigator component to get information about the top page.
var myNavigator = document.querySelector('ons-navigator');
console.log(myNavigator.topPage);
A method is a function that trigger a specific action for the component. The following example is calling pushPage method to open a new page.
var myNavigator = document.querySelector('ons-navigator');
myNavigator.pushPage('page2.html');
DOM Events are fired at a specific timing. To listen for an event, use JavaScript’s addEventListener() function. An event is also supplied with an event object, which is useful for getting some details.
var myNavigator = document.querySelector('ons-navigator');
myNavigator.addEventListener('postpush', function(event) {
console.log("'pushPage' is completed!", event);
});
Events can bubble up, which means that event listeners can be added to parent components or directly to document instead.
Great job! That’s it for Onsen UI’s 101. By now, you should have a fairly good understanding of the basics. Feel free to escape this documentation and surf around some of our useful resources: Playground (Interactive Tutorial), GitHub repository, or Community Forum!