Integrating jQuery Mobile into Kentico CMS
In the previous articles, "
Introducing jQuery Mobile" and "
jQuery Mobile – Pages and Dialogs", Thomas Robbins looked in detail at general usage of jQuery Mobile. I know from implementing the mobile version of our new E-commerce Sample Site, that when you have to integrate a framework like jQuery Mobile into a complex system like Kentico CMS, life is not quite as easy as writing the term “jQuery Mobile markup” on a blank piece of paper! But don't worry my friends – We have successfully integrated jQuery into our Kentico CMS project! And we’d like to share the lessons we learned in the process with you now, to help ease your own mobile website development.
Check out the
Kentico E-commerce Sample Mobile Site
In this explanation, I assume you know the basics of jQuery Mobile and web site development with Kentico CMS. If you need more basic information, I recommend Thom's blog posts mentioned above.
First, let me try to quickly describe the way we approached our E-commerce Sample Site development:
-
For users, the web site appears to be two separate Web projects – the desktop one and the mobile one. In fact, all documents are stored in one Content tree and all root documents have their own Master page template. The mobile one uses the capability of jQuery Mobile.
-
The mobile part of the E-commerce Sample Site project is dependent on data stored in the Desktop part of project. The reason for this is to feed both web sites from one source, keeping content on both web sites consistent.
And now it's time for tips!
Structure your content
The basic jQuery Mobile Documentation leads us to write markup of all web site pages within one document. It's a great approach when keeping things simple, but is not suitable in the case of Kentico CMS where it is supposed that one document in the Content Tree represents one web site page (with a few exceptions).
Fortunately, jQuery Mobile works across documents, so we can use the classic scheme of Kentico web site development via Master page template with Placeholder Web Part inside and Page templates which inherits the Master page template.
Master page template layout (used on “Mobile” document [see picture above]. Notice its position in the Content tree):
<!DOCTYPE html>
<html>
<head>
<title>E-commerce site - Mobile</title>
<meta http-equiv="pragma" content="no-cache" />
<meta content="width=device-width, minimum-scale=1, maximum-scale=1" name="viewport" />
<link href="~/CMSPages/GetResource.ashx?stylesheetname=EcommerceSiteMobile"
type="text/css" rel="stylesheet"/>
<link rel="stylesheet" href="~/CMSScripts/jquery/JQueryMobile/jquery.mobile-1.1.0.min.css" />
<script src="~/CMSScripts/jquery/JQuery/jquery-1.7.0.min.js" type="text/javascript"></script>
<script src="~/CMSScripts/jquery/JQueryMobile/jquery.mobile-1.1.0.min.js" type="text/javascript"></script>
</head>
<body class="LTR Safari Chrome Safari5 Chrome5 ENUS ContentBody">
<div data-role="page" id="Page">
<div data-role="header" data-position="fixed">
<cms:CMSWebPartZone ZoneID="zH" runat="server" />
</div>
<div data-role="content">
<cms:CMSWebPartZone ZoneID="zC" runat="server" />
</div>
<div data-role="footer" data-position="fixed">
<cms:CMSWebPartZone ZoneID="zF" runat="server" />
</div>
</div>
</body>
</html>
Repeater is your best friend
In most cases, Kentico CMS Web parts generate their own HTML code on the web page. This behavior isn't wanted in the case of jQuery Mobile because it uses special attributes in markup like data-role, data-theme, etc. In fact, the Mobile part of the project reflects data stored in the Desktop part of project, so we have to repeat them somehow.
By way of example, I would like to show you how we’ve created a navigation menu on the “Home” document in the Mobile part of project. We would usually use the “CSS list menu” Web part, but we’ve been pushed to use the “Repeater” Web part to be able to generate special jQuery Mobile markup.
There is a “Repeater” Web Part in the “Home” document’s Web part zone. Look at its properties defining markup:
Content before:<div data-role="collapsible-set" data-theme="a" data-content-theme="a">
Transformation:<div data-role="collapsible" data-theme="c" data-content-theme="c">
<h3><%# Eval("DocumentName") %></h3>
<ul data-role="listview">
<cms:CMSRepeater ID="wSM" runat="server" MaxRelativeLevel="1"
TransformationName="EcommerceSite.Transformations.MobileSubNavigation" Path="./%"
ClassNames="CMS.MenuItem" SelectOnlyPublished="true" />
</ul>
</div>
Content after:</div>
Be aware of page life cycle
Integrating jQuery with Kentico CMS (a .NET platform) can sometimes present problems with the page life cycle, especially when postback is called. If there is an issue with page life cycle, you must become Sherlock Holmes and debug your website JavaScript. To be more specific, I would like to give you an example of a common problem.
Kentico “On-line forms” and other controls like “Wishlist” call postback on button press. The problem is that no data is stored in the database because of inconvenient URLs in the action attribute in the form tag. This is how we solved the problem:
jQuery("#Page").live('pageinit', function(event) {
jQuery("input[type=submit]").click(function(event) {
jQuery.mobile.ajaxEnabled = false; //jQuery Mobile will automatically handle link clicks and form submissions through Ajax, when possible. If false, URL hash listening will be disabled as well, and URLs will load as ordinary HTTP requests.
jQuery("form").removeAttr("action");
jQuery("form").attr("action", document.URL);
});
});
You can see Kentico E-commerce Sample Mobile Site here. If you have any other tips on jQuery Mobile integration with Kentico CMS don’t hesitate to contact me or write a comment. Thanks!