Join Joe Marini for an in-depth discussion in this video Understanding jQuery Mobile page architecture, part of jQuery Mobile Essential Training.
There are a couple of different ways of defining pages inside jQuery Mobile. So let's take a few moments to learn about jQuery Mobile's page architecture. Now, if you watched the movie in the previous chapter where we built our first jQuery Mobile app, you'll recall that we had two individual pages in one HTML file. Now in jQuery Mobile, that's called an internal page. So internal pages are built by having your body content in the HTML file just like you normally would.
And then you have a container element, and in this case it's a div, but it could be any container element. And you set the data role attribute to the value of page, and then inside that container you declare your page content. And if you recall we had two of these in our file, so I had two individual distinct pages with page content in them. And conceptually this basically looks like your HTML file with two individual pages, and jQuery Mobile can navigate between these two and animate them into place and make them look like individual screens in an application.
What you're building really is, you know, applications. This aren't just like documents, right? You're building screens in a web app. So hopefully that won't become too much of an issue. But again, you can get around it using script just to scroll the right elements into view. Now in addition to internal pages, there's also the concept of external pages. External pages are essentially links to external documents and they work pretty much as you'd expect them to. But the way that this works is jQuery Mobile actually uses Ajax to request the page from your server and then animate the content into place.
So you declare an external page using a link tag. And you'd have the href set to some URL to the external document just like you normally would. And what's going to happen is jQuery will try to load that page using Ajax. It's not going to just simply tell the browser to go there. It will actually request the content from the server, and then it will parse it and then add it to the page's DOM. And once it does that, the widgets in the page (and we haven't covered widgets yet, but we will in a little bit--these are form controls and everything else). Those widgets are then automatically initialized by the jQuery Mobile framework.
Then the new page is animated into place using a transition. The default transition is that fade effect, but you have control over that if you want to. So external pages can also be loaded without the AJAX behavior. In other words, you can link to external files, and they'll just be treated as non jQuery Mobile pages. So, for example, you can do this by setting the rel attribute to the value of external. You can do this by saying data ajax equals false, or you can do this by giving it a target.
If you set the target attribute to something that's not, you know, an empty string, then jQuery Mobile will treat that as a page that's not part of the framework, and it will be considered an external page to your web app. So let's jump over to the code and see how this works in real life. All right, so here in the code I've got my chapter two folder open and I've scrolled down to my external page navigation section. And I'm going to open up pagenav_start. Now here in pagenav_start I've already included the links and the meta tag, and you can see here that I have a section with an ID of internal page and a data roll of page.
So this is my internal jQuery Mobile page and it's going to link to an external page. So here I have my header which is set to a data role of header and this tells jQuery Mobile that should be a header tool bar. And over in the snippets, what I'm going to do is copy this div right here and I'm going to paste that in, in here inside the section, okay? And you can see that I have a div.
Its class is set to UI content. UI content is one of the predefined jQuery Mobile CSS classes that jQuery Mobile uses to mark up the app's content. And you can see that I have two links. So I've got one link to an external page, and I've got another link to an external page right here. But this one has rel equals external on it. Now both of these pages are defined over here. There's external page one and external page two. So let's take a look at external page one. And you can see that in external page one, I've got this markup on this div with data role equals page, just as if it were an internal page in the original HTML file.
And I've got this random content in this paragraph out here. But jQuery Mobile is going to ignore that. When the Ajax request completes and this document is returned to the library, it's going to look for contents that are inside the role of the page. And it's going to ignore everything else. Now, lets take a look at external page two. You can see that this is just a regular web page. There's no script being included that has anything to with jQuery Mobile or anything like that. It's, you can imagine this is some external page out on the web somewhere.
So let's go back to the page nav. Now, this is an example where you're going to have to run this from a web server. And again, it's making an Ajax request, so if you try to run this in Chrome or Safari or whatever without running it from a web server you're probably going to get an error. So, what I'm going to do is run this from within Aptana Studio and that will automatically start up Aptana Studio's built-in web server so we can see this in action. So up here in this little menu, I'm going to click on Run As Firefox.
Okay, and you can see that Firefox comes up. So here is my page. You can see that here's the header bar, right here, and this is page one. So I'm going to click on the first link. Now, this links to the external page that has the data role of page inside of it. And you can see that when I do that, the content gets animated into place and the Ajax request completes, and everything looks great. And you can see that that paragraph that had the random content in it isn't there, right, because it's being ignored because it's not inside that div with the data role of page on it. So let's go back.
Now let's link to the external page that's outside of the jQuery Mobile system. Remember, this has the rel equals external attribute on it. So when I click on this, you'll see that it just gets loaded as a regular web page. There's not toolbar. There's no jQuery Mobile markup or any kind of styling. It's just treated as an external page. Okay, so that covers the two different ways that you can define pages in jQuery Mobile.
- Building your first jQuery Mobile app
- Understanding the page architecture
- Using page transitions and dialog widgets
- Working with forms and controls
- Creating toolbars
- Working with list views
- Using jQuery Mobile's content formatting features
- Adding events to detect and respond to changes
- Configuring and customizing jQuery Mobile