Purpose of this document

Mobify Studio provides two ways to match templates to pages: URL matching and JavaScript matching.

This guide will walk you through the different ways you can build JavaScript functions that will connect your pages to their mobile templates.

After completing this guide, you will know:

  • Why you may want to use JavaScript matching
  • What the JavaScript matching function does
  • How to write different types of matching functions
  • When to use different types of matching functions

Prerequisites

  • You must have a basic knowledge of HTML and CSS.
  • A firm grasp on JavaScript and jQuery-like selectors is required.

Why use JavaScript matching?

In the vast majority of cases, matching a template to an individual page or group of pages is easy to do with a simple URL match. However, if you want to match a template to pages that don't have a consistent URL structure, using JavaScript matching will allow you to do so.

What does the JavaScript match do?

Simply put, JavaScript matching boils down to searching for an object or word on a page, or property of its DOM, and returning true when this is found. What follows are a few different ways to write these JavaScript matches.

The JavaScript match is written as a function expression that returns a truthy value on pages you wish to match and a falsey value on those you don't:

function() {
    // return some value or object
}

A falsey value is any expression x, where x == false (e.g. the number 0, the empty string "", the special values null and undefined, and the boolean value false). Additionally, any object with a length property equal to 0 will be considered falsey for matching templates. This includes the empty array [] and empty array-like objects such as Zepto or DOM collections.

Any other value will be considered truthy. This includes the boolean value true, numbers like 1 or -247, non-empty strings like "hello!", functions and other objects with no length property or a length property other than 0, such as an array like this ["One", "Two", "Three"], or a Zepto collection that matched one or more elements.

If you use a JavaScript match for your template, you will have to write a function that returns a truthy value for the pages that you wish to use the template for and a falsey value for all other pages. Then, when you navigate to the page this template is matched to, the matching function will evaluate to TRUE and the template will be rendered.

Two different ways to write a JavaScript match

There is no specific limit to what type of function you can write to evaluate whether to match a template, but there are a few guidelines:

  • Don't make any changes to the DOM from within your matching function.
  • Make the matching logic as simple as possible.

Find a unique element on the page

The easiest type of function is one where you search for an element on a page. Good examples of this would be searching for a product div in the product page template:

// Matching function for the product template
function() {
    return $('div#product');
}

Now, any page that contains the element <div id='#product'> will match our product template.

You can write any kind of selector using Zepto functions and regular JavaScript within the matching function.

Use a regular expression

As the saying goes: Some people, when confronted with a problem, think "I know, I'll use regular expressions." Now they have two problems.

You may agree with this saying, but regular expressions are quite powerful when applied correctly. One such example is if you have two pages with different URLs that should use the same template but can not be matched with URL matching. For example, if you want to match both:

  • /someurl/
  • /other/different/url

then, the following regular expression will do the trick:

function() {
    re = new RegExp("^/(someurl|other/different/url)(/)?$");
    return re.test(location.pathname);
}

While the regular expression method is more difficult to write than a simple selection, this method is quite flexible. We recommend using a tool like RegExr to design your regular expressions.

Last Edited