Barry's jQuery Mobile Demos: Pages

Pages

jQuery Mobile treats a mobile screen as a page. You can have multiple pages in the one HTML file which is very useful for slow internet connections. Having multiple pages loaded at once into the mobile device allows very fast transition between pages. This is because the page load time is eliminated. Nevertheless, many of your jQuery Mobile websites will be constructed in multiple pages (like this one). You will need to judge when a fast transition is essential.

A jQuery mobile page is divided into three sections: a header, an area for main text and a footer. An example of a page definition is as follows.

<div data-role="page" id="page name">
  <div data-role="header">
	<p>Page header</p>
  </div>
  <div data-role="main" class="ui-content">
    <p> main text area of the page.</p>
  </div>
  <div data-role="footer">
	<p>Page footer</p>
  </div>
</div>

There are several things to note about the page definition. First, every page has name identified by the id attribute in the main <div data-role="page"> tag. The page name will be used for links between pages. You can also leave out any of the three header, main and footer <div> tags which will remove that section from the page. The header and footer are usually areas for headers, tool bars used for navigation, search and other actions for the user to interact with the website. The class="ui-content" attribute of the main area adds extra margin around the content area of the page.

Navigating between pages

As mentioned above, we can use the id attribute to navigate between pages. The following simple example shows two pages (with no header or footer that are linked together. The first page called "jQM-Pages" has a link to the second page called "ExamplePage".

<div data-role="page" id="jQM-Pages">
  <div data-role="main" class="ui-content">
    <a href="#ExamplePage"> go to example second page.</a>
  </div>
</div>

<div data-role="page" id="ExamplePage">
  <div data-role="main" class="ui-content">
    <a href="#jQM-Pages">go back to main page.</a>
  </div>
</div>

You can see how this works by clicking on the following button. It will take you to the page with id="ExamplePage" defined exactly as above. Notice that jQM-Pages is also the name of the page you are currently reading.

View example second page

Notice how the link is a local reference to the page with the reference href="#ExamplePage" appearing in the first link to link to the second page, similarly for the reverse link.

At the time this tutorial was written, there is also an extra attribute necessary when linking between jQuery mobile pages in separate HTML files. We must add the attribute rel="external" to a link. For example, a simple link to this page would need to look like:

  <a href="jQM-Pages.html" rel="external">Pages</a>

You can verify this by looking at this page's name and the link to it in the home page for this tutorial.

Using a page as a dialog box

Another interesting feature of jQuery Mobile is that apage can be used as a dialog box. This is done by displaying the page on the mobile device as the whole screen and returning to the launching page afterwards.

To define a page as a dialog we simply add the attribute data-dialog="true" to the page <div> tag. For example, the following dialog box definition will simply provide a link back here when you show it by clicking on the button below.

<div data-role="page" data-dialog="true" id="ExampleDialog">
  <div data-role="header">
    <p>Example dialog</p>
  </div>
  <div data-role="main" class="ui-content">
    <a href="#jQM-Pages">Close the dialog</a>
  </div>
  <div data-role="footer">
    <p>Click above link or X button to close the dialog</p>
  </div>
</div>
  
Try dialog

If you view the code for this page you can see the jQueryMObile code for the dialog appears as above. For this example we have included a header and a footer definition so you can see how they appear in a dialog. As for normal pages, you can omit these if you wish.

If you have tried the above dialog you will notice that when you click on the link to return from the dialog the page is positioned at the top of the page. This can be annoying with larger pages because you have to scroll down to where you clicked the button. You can force the browser to reposition at the point where you went to the dialog by creating a link in the dialog with href="#" and adding the attribute data-rel="back" to the link. For example, we can create an almost identical dialog as follows.

<div data-role="page" data-dialog="true" id="ExampleDialog2">
  <div data-role="header">
    <p>Example dialog</p>
  </div>
  <div data-role="main" class="ui-content">
    <a href="#" data-rel="back">Close the dialog</a>
  </div>
  <div data-role="footer">
    <p>Click above link or X button to close the dialog</p>
  </div>
</div>
  

You can test it with the following button.

Try dialog with data-rel="back"

Notice that the close icon "X" always returns to the position you left in the same way.

See also

We can add transitions to introduce special effects when screen is changed between a new page or a new dialog. We can also chose to make the header and footer stay stationary while the page scrolls. This is explained in the Toolbars demonstration.

Home

go back to main page.

Example dialog

Close the dialog

Click above link or X button to close the dialog

Example dialog 2

Close the dialog and go back to place we started from

Click above link or X button to close the dialog