Skip to content
This repository has been archived by the owner on Aug 5, 2020. It is now read-only.

Commit

Permalink
Merge pull request #86 from mobify/further-urlmatch-documentation
Browse files Browse the repository at this point in the history 
Further urlmatch documentation
  • Loading branch information
@johnboxall
johnboxall committed Jan 8, 2013
2 parents 18fce8e + a9b8bc6 commit ab951f8
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 18 deletions.
47 changes: 38 additions & 9 deletions www/docs/konf-reference.md
View file
Expand Up @@ -10,8 +10,9 @@ title: Konf Reference

## `$(selector)`

Inside the `{<konf} ... {/konf}` block, `$` references the [Zepto](http://zeptojs.com/)
object. Its context is bound to the source DOM document.
Inside the `{<konf} ... {/konf}` block, `$` references the
[Zepto](http://zeptojs.com/) object. Its context is bound to the source DOM
document.

**Differences from the Regular DOM**

Expand Down Expand Up @@ -103,7 +104,7 @@ passed to `context.tmpl` for output with _OUTPUTHTML_:

This assigns the value `"home"` to the templateName key. `context.data`
looks up the value and passes it to `context.tmpl` which finds the matching
template and renders it. The result is then output ot the browser!
template and renders it. The result is then output to the browser!


## `context.choose(obj1[, obj2[, ...]])` {#context-choose}
Expand All @@ -128,7 +129,7 @@ start with `!`, evaluate to truthy values:
}

In this example, the first argument matches if the function assigned
to the _!home_ evalutes to a truthy value. If it doesn't, the next
to the _!home_ evaluates to a truthy value. If it doesn't, the next
argument would be tested.

An argument with no required keys always matches:
Expand Down Expand Up @@ -204,11 +205,34 @@ a required key, it may affect evaluation later in the konf leading to
difficult to debug errors. Do not alter the DOM in required keys. Move
DOM altering operations to non-required keys.

### Matching URLs with Mobify.urlmatch()

Mobify.js provides the `Mobify.urlmatch()` function as a convenient method of
making matches based on patterns in the path portion of the URL.

It takes as an argument a string containing a
[path expression](../matching-to-urls#path-expressions), or a JavaScript
`RegExp` object, and returns a function that will match the expression against
`window.location.pathname`.

The returned function takes no arguments, and will return a regular expression
object when it matches, and false otherwise.

See the document [Matching Templates to URLs](../matching-to-urls) for further
reference.

## Reserved Keys

The konf is extended by a default konf containing the following reserved
keys:

`!__match`
: A template matching function, used by Mobify Studio

`__url`

: A template's prototype page url, used by Mobify Studio

`$html`
: Reference to the source DOM `<html>` element

Expand All @@ -234,7 +258,8 @@ keys:
: A boolean flag that will be true if Mobify.js is running in debug mode

`config.orientation`
: A string that will be "portrait" if the device is taller than it is wide, or "landscape" if it is wider than it is tall
: A string that will be "portrait" if the device is taller than it is wide, or
"landscape" if it is wider than it is tall

`config.os`
: A string representing the detected operating system of the device
Expand All @@ -249,16 +274,19 @@ keys:
: Version of the Mobify tag used on this site

`config.touch`
: A boolean flag that will be true if touch events are supported, false otherwise
: A boolean flag that will be true if touch events are supported, false
otherwise

`configName`
: A property pulled from _project.json_ - most likely the unique identifier for your site
: A property pulled from _project.json_ - most likely the unique identifier for
your site

`cssName`
: A function returning the name of the css file to be applied

`imageDir`
: A function returning a path to where mobify adaptation specific images are kept
: A function returning a path to where mobify adaptation specific images are
kept

`mobileViewport`
: Contents of the meta viewport tag to be sent
Expand All @@ -267,7 +295,8 @@ keys:
: An object containing analytics configuration information

`touchIcon`
: The location of a file to be used as the bookmark icon for this website on iOS devices
: The location of a file to be used as the bookmark icon for this website on iOS
devices

`unmobify`
: An internal flag used to record whether the page has been unmobified
Expand Down
43 changes: 34 additions & 9 deletions www/docs/matching-to-urls.md
View file
@@ -1,18 +1,20 @@
---
layout: doc
title: Matching Tempaltes to URLs
title: Matching Templates to URLs
---

# Matching Templates to URLs

Though you're encouraged to match tempaltes in Mobify.js by locating unique DOM
Though you're encouraged to match templates in Mobify.js by locating unique DOM
elements, you can also match templates against URLs.

Mobify.js provides the `Mobify.urlmatch()` helper function to enable this. In
your konf, you pass it a string containing a Mobify path matching pattern, or a
regular expression, and it will return a function to be used to check whether the URL of the page matches that pattern or expression.
regular expression, and it will return a function to be used to check whether
the URL of the page matches that pattern or expression.

For example, in your konf, in a call to the choose function, you could cause the about template to be selected like so:
For example, in your konf, in a call to the choose function, you could cause the
about template to be selected like so:

{
'templateName': 'about'
Expand All @@ -22,7 +24,7 @@ For example, in your konf, in a call to the choose function, you could cause the
}
}

## Mobify.urlmatch() Path Expressions
<h2 id="path-expressions"> Mobify.urlmatch() Path Expressions </h2>

Path expressions let you match templates to URL paths of pages on your site.

Expand All @@ -35,7 +37,7 @@ from 2012 with `"/articles/2012/*/*/"`. Here we see that `*` is used to mark a
path component as a variable that is allowed to differ, but must be present.

If our URL structure were different, and we used a category as the first
compoenent of the URL like `/science/articles/72633/` and
component of the URL like `/science/articles/72633/` and
`/politics/articles/95828`, but would like to match articles regardless of
category, we could use the expression `"/*/articles/*/"` to match both of these.

Expand All @@ -46,9 +48,32 @@ this we use wildcard matching. For example, in a blog, a post without titles
would have a path such as `/post/29803152490` and a post with a title would have
a path of `/post/29800908081/10-best-10-best-lists of all-time`.

We can match both of these with the expression `"/post/*"`. Note the lack of a trailing slash in comparison to the placeholder match: ending the expression
with `*` will cause any path compoenents after the one specified to match.
We can match both of these with the expression `"/post/*"`. Note the lack of a
trailing slash in comparison to the placeholder match: ending the expression
with `*` will cause any path components after the one specified to match.

### Examples


| Path Expression | Matching Path Examples |
|-----------------|------------------------|
| `"/"` | `/` |
| `"/*"` | Any path* |
| `"/*/"` | `/foo`, `/bar/` |
| `"/foo"` | `/foo`, `/foo/` |
| `"/foo/*"` | `/foo/bar`, `/foo/baz/`, `/foo/bar/baz`|
| `"/foo/bar"` | `/foo/bar`, `/foo/bar/`|
| `"/*/bar"` | `/foo/bar/`, `/baz/bar` |
| `"/foo/*/baz"` | `/foo/bar/baz`, `/foo/qux/baz` |
| `"/foo/*/baz/*"`| `/foo/bar/baz/qux`, `/foo/qux/baz/quux/bar` |


\* The expression `"/*"` is a special case of the wildcard expression, it will
match any and every path, including `/`, other paths ending in the wildcard
match require _at least_ one path component present in place of the `*`.

## Matching with Regular Expressions

You can also use JavaScript's built in regular expressions to match the path.
You can also pass in a JavaScript `RegExp` object, the returned function will
call the `RegExp`'s `.test()` method against `window.location.pathname` and if
it matches, return the expression, and otherwise return false.

0 comments on commit ab951f8

Please sign in to comment.