Permalink
Browse files

Merge pull request #86 from mobify/further-urlmatch-documentation

Further urlmatch documentation
  • Loading branch information...
2 parents 18fce8e + a9b8bc6 commit ab951f87853e2f02ca2a090a4f7071f602959a15 @johnboxall johnboxall committed Jan 8, 2013
Showing with 72 additions and 18 deletions.
  1. +38 −9 www/docs/konf-reference.md
  2. +34 −9 www/docs/matching-to-urls.md
@@ -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**
@@ -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}
@@ -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:
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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'
@@ -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.
@@ -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.
@@ -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.