diff --git a/doc/combo.md b/doc/combo.md deleted file mode 100644 index 1c6bd8be..00000000 --- a/doc/combo.md +++ /dev/null @@ -1,12 +0,0 @@ -# Using Combo for Intelligent Script Loading - -Mobify provides a javascript API and web service to provide optimized loading of external javascript files. - -Minimizing the number of HTTP requests made is a key technique in web page performance enhancement. - -Groups of external javascript files loaded using this API are downloaded in a single HTTP request, which is cached for later re-use by our CDN. Additionally, the individual scripts are cached in HTML5 localStorage, so that they need not be redownloaded for use with subsequent pages that use a different grouping of scripts. - -There are two functions provided for making use of this: - -* `Mobify.$.fn.combineScripts()` removes from the DOM and rewrites all script members and script children of the jQuery collection it is called on, and returns a collection of script tags that will load all of the external scripts and run them in the original document order, when added to a Mobify template. Use this when scripts elements have dependencies on eachother. -* `Mobify.$.fn.combineScripts({async: true})` - removes from the DOM and rewrites all script members and script children of the jQuery collection it is called on and returns a collection of scripts that will load all of the external scripts and run them in an order of the browser's choosing. Use this when there are no dependencies betweens cript elements (e.g. externally loaded asynchronous analytics scripts). \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index f1ed05d6..378b13b8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,161 +3,163 @@ layout: doc title: Getting Started --- -Getting Started -=============== +# Getting Started * TOC {:toc} -Mobify.js adapts existing websites for mobile devices using their source HTML. -The Mobify.js tag loads a bundle, which contains the Konf, templates and other -resources. Using the 'Konf', we select and adapt HTML elements from the -original site content, then we render the adapted content using 'templates' to -produce a new page for the browser. +Mobify.js adapts existing websites for mobile devices using their +source HTML. The Mobify.js tag loads a bundle, which contains the +Konf, templates and other resources. Using the 'Konf', we select and +adapt HTML elements from the original site content, then we render the +adapted content using 'templates' to produce a new page for the +browser. -This guide will help you understand the contents of your project. - -You will learn how to: +In this guide you will learn how to: * Use the Konf to select content from your site's source DOM. * Output your adaptation to the browser using templates. -## Tutorial requirements +## Tutorial Requirements -**We assume you have have created a project and installed the mobify client.** +**We assume you have have created a project and installed the Mobify +Client.** -**[If you haven't, go do it now!](http://portal.mobify.com/projects/new/)** +**[If you haven't, go do it now!](http://cloud.mobify.com/projects/new/)** -## Previewing your work +## Previewing Your Work -The Mobify Client allows you to preview changes you make to your local bundle. +The Mobify Client allows you to preview changes you make to your local +bundle. Do the following: - 1. In a *Terminal* window in your project's directory, run: `mobify preview` +1. In a *Terminal* window in your project's directory, run: + `mobify preview` - This command compile your bundle locally, on the fly, as you edit your files. - You'll want to keep this window open to see debugging information as you - work on your mobified site. + This command compile your bundle locally, on the fly, as you edit + your files. You'll want to keep this window open to see debugging + information as you work on your mobified site. - 2. On , navigate to your project, then click _'Preview'_ - in the left-hand navigation. If preview is running, then _'localhost'_ - will be selected by default. +2. On , navigate to your project, then click + _'Preview'_ in the left-hand navigation. If preview is running, + then _'localhost'_ will be selected by default. -Each time you make a change to your files, you can hit the refresh button to -see your changes. If you ever refresh, and suddenly you are viewing your -desktop site, try opening up the javascript console. +Each time you make a change to your files, you can hit the refresh +button to see your changes. If you ever refresh, and suddenly you +are viewing your desktop site, try opening up the JavaScript console. ## What is a 'Konf'? -The Konf is JavaScript that selects and adapts content from a site's source -DOM. The selections made in the Konf are used as the context to render a -template, producing the mobified page. The Konf file is required in any Mobify -project, and by default lives at **'src/mobify.konf'**. +The Konf is JavaScript that selects and adapts content from a site's +source DOM. The selections made in the Konf are used as the context +to render a template, producing the mobified page. The Konf file is +required in any Mobify project, and by default lives at +**'src/mobify.konf'**. ## Templates -A template is a text file that contains variables which are replaced when the -template is rendered. In Mobify.js, templates are used to remix the source DOM -and give you control over the output of your mobified page. +A template is a text file that contains variables which are replaced +when the template is rendered. In Mobify.js, templates are used to +remix the source DOM and give you control over the output of your +mobified page. By default, a project starts with four templates: - - **base.tmpl**: An example base template which contains the HTML skeleton - of your project, which contains a default css file, viewport, and set of - sane block placeholders which are ment to be overridden in other - templates (such as home.tmpl). - - - **home.tmpl**: An example template for use with a home page + - **base.tmpl**: An example base template which contains the HTML + skeleton of your project, which contains a default css file, + viewport, and set of sane block placeholders which are ment to be + overridden in other templates (such as home.tmpl). - - **\_header.tmpl**: A template which gets included immediately below the - opening body tag in base.tmpl + - **home.tmpl**: An example template for use with a home page. - - **\_footer.tmpl**: A template which gets included immediately above the closing - body tag in base.tmpl + - **\_header.tmpl**: A template which gets included immediately + below the opening body tag in base.tmpl. + - **\_footer.tmpl**: A template which gets included immediately + above the closing body tag in base.tmpl ## Creating a template for a different page of your site -Up to this point, we have a base template, a home template, a header template, -and a footer template. To mobify more pages, you will need more templates! +To mobify more pages, we need more templates! -We'll adapt a hypothetical 'About' page for the purposes of this tutorial (If -you don't have an 'About' page, or want to try mobifying a different set of -pages, you can follow along, substituting 'About' with the page you want to -mobify) - -You will want to uncomment the following block in your mobify.konf file: - -{% highlight javascript %} /*{ - '!templateName': 'about', - '!phonenumber' : function() { - return $('.selector_for_phone_number'); - }, - '!blurb': function() { - return $('.selector_for_blurb'); - } - }*/ -{% endhighlight %} +We'll adapt a hypothetical 'About' page for the purposes of this +tutorial. If you don't have an 'About' page, or want to try mobifying +a different set of pages, just substitute another page you want to +mobify. + +Start by uncommenting the following block in your mobify.konf file: + + /* { + '!templateName': 'about', + '!phonenumber' : function() { + return $('.selector_for_phone_number'); + }, + '!blurb': function() { + return $('.selector_for_blurb'); + } + } */ - Make sure you change `.selector_for_phone_number` and `.selector_for_blurb` to something that is unique to the page you're mobifying. - -You may have noticed that this object you uncommented is an argument that gets -passed into `context.choose()`. In order to determine what template to use, the -Mobify frameworks determines which template to render by asking you to -describe what DOM elements must match for a particular template to render. -This DOM description is also used as the context which is used when rendering -templates - so you can see in the example above, you have a -`!phonenumber` and `!blurb` key, and if those keys match the DOM of the page, -then the **"about"** template will be rendered. These keys are then accessible as -data within the template (so, for example, you could access the phone number -like this: `{content.phonenumber}` ). Keys with `!` prefixed are -_required_ in order for the template to render. Sometimes, -you may want to extract data from a page, but it isn't something that is -required in order to render the page. In that case, you simply add a key -without the `!` prefix. - -Now, you need to create a corresponding template for the 'About' page. Here is -an example of what it may look like. +You may have noticed that this object you uncommented is an argument +that gets passed into `context.choose()`. In order to determine what +template to use, the Mobify frameworks determines which template to +render by asking you to describe what DOM elements must match for a +particular template to render.This DOM description is also used as the +context which is used when rendering templates - so you can see in the +example above, you have a `!phonenumber` and `!blurb` key, and if +those keys match the DOM of the page, then the **"about"** template +will be rendered. These keys are then accessible as data within the +template (so, for example, you could access the phone number like +this: `{content.phonenumber}` ). Keys with `!` prefixed are _required_ +in order for the template to render. Sometimes, you may want to +extract data from a page, but it isn't something that is required in +order to render the page. In that case, you simply add a key without +the `!` prefix. + +Now, you need to create a corresponding template for the 'About' page. +Here is an example of what it may look like. #### about.tmpl -{% highlight html+django %} {>base/} + + {base/} {About page

My phone number: "{content.phonenumber}"

{content.blurb}

{/content} -{% endhighlight %} Simply navigate to the about page (make sure `mobify preview` is still -running!, and you will see your About page rendered through Mobify.js. If for -some reason you see your desktop site, open up the javascript console to see -any potential errors. +running!, and you will see your About page rendered through Mobify.js. +If for some reason you see your desktop site, open up the JavaScript +console to see any potential errors. ## Pushing a bundle up to Cloud -Now that your site is looking decent, you might want to start thinking about -pushing up bundles to the Cloud in order to view them on your mobile device, if you -have a bundle that you think you might want to publish to production. +Now that your site is looking decent, you might want to start thinking +about pushing up bundles to the Cloud in order to view them on your +mobile device, if you have a bundle that you think you might want to +publish to production. -In order to do that, you can simply go to the root directory of your project folder -and execute this command: +In order to do that, you can simply go to the root directory of your +project folder and execute this command: mobify push --message "Initial Push" -After you've pushed, go back to the Preview page and refresh, and you will see the bundle -you just pushed in the "Available Bundles" dropdown. Once you select your bundle, -you'll notice that you can email this link to yourself or someone else in order to -see it on your mobile phone through the interface on Cloud. +After you've pushed, go back to the Preview page and refresh, and you +will see the bundle you just pushed in the "Available Bundles" +dropdown. Once you select your bundle, you'll notice that you can +email this link to yourself or someone else in order to see it on your +mobile phone through the interface on Cloud. ## Publishing to Production -Once you've gone through and modified your mobile site to your liking, you can publish your -bundle to production. Just click on the "Publishing" page on the left hand side, and you'll -see a list of bundles that you've pushed up to cloud. From there, you can select the one -you want to publish! +Once you've gone through and modified your mobile site to your liking, +you can publish your bundle to production. Just click on the +"Publishing" page on the left hand side, and you'll see a list of +bundles that you've pushed up to cloud. From there, you can select the +one you want to publish! diff --git a/docs/glossary.md b/docs/glossary.md index 458d277d..fc4b89d0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -13,19 +13,25 @@ title: Glossary ### Attributes > Additional data values which may be returned along with variables. -> Each attribute maps to a specific member key within the parent key in the konf. +> Each attribute maps to a specific member key within the parent key +> in the konf. ### Context -> A set of key-value pairs that is used to provide values for variables in templates. The Mobify.js konf produces a context, built from your selections, and renders a template with that context. [Learn more about context](https://support.mobify.com/customer/portal/articles/511697-template-reference) +> A set of key-value pairs that is used to provide values for +> variables in templates. The Mobify.js konf produces a context, +> built from your selections, and renders a template with that +> context. [Learn more about context](https://support.mobify.com/customer/portal/articles/511697-template-reference) ### Keys -> A name that uniquely references a selection you make within the konf file, also serves as a variable name within your templates. +> A name that uniquely references a selection you make within the konf +> file, also serves as a variable name within your templates. ### Konf -> A JavaScript file that enables content selection and template rendering from a source DOM. +> A JavaScript file that enables content selection and template +> rendering from a source DOM. ### Rendered DOM @@ -33,16 +39,21 @@ title: Glossary ### Selections -> DOM elements or other data returned by functions defined in the konf file, provide the values of the variables in templates to produce the rendered DOM. +> DOM elements or other data returned by functions defined in the konf +> file, provide the values of the variables in templates to produce +> the rendered DOM. ### Source DOM -> The DOM built from your site's original HTML, without running javascript, ie. the DOM you'd see if you viewed source before Mobifying. +> The DOM built from your site's original HTML, without running +> JavsScript, ie. the DOM you'd see if you viewed source. ### Templates -> A text file that contains regular HTML markup and variables that are replaced when the template is rendered. +> A text file that contains regular HTML markup and variables that are +> replaced when the template is rendered. ### Variables -> Context mapped data provided to your template from the konf selections. Each variable maps to a key in the context. +> Context mapped data provided to your template from the konf +> selections. Each variable maps to a key in the context. diff --git a/docs/konf-reference.md b/docs/konf-reference.md index 582b9b98..755a4a65 100644 --- a/docs/konf-reference.md +++ b/docs/konf-reference.md @@ -16,17 +16,24 @@ title: Konf Reference ## 1\. Using Konf -The Mobify.js konf selects elements from the source DOM to be rendered on the mobile site. To make selection easy, Mobify.js includes Zepto, a minimalist JavaScript DOM library optimized for mobile with a jQuery-compatible API. +The Konf selects elements from the source DOM to be rendered +on the mobile site. To make selection easy, Mobify.js includes Zepto, +a minimalist JavaScript DOM library optimized for mobile with a +jQuery-like API. -A simple selection to assign the site's logo to a key might look like this: +A simple selection to assign the site's logo to a key might look like +this: 'logo': function() { return $('.identity img') }, -This key will apply to every page where the selector evaluates to true. Note that the corresponding page template needs to include a variable that references the key for it to render. +This key will apply to every page where the selector evaluates to true. +Note that the corresponding page template needs to include a variable +that references the key for it to render. -The konf is also used to determine which templates will render for each page by evaluating jQuery-like selectors against the current page: +The konf is also used to determine which templates will render for +each page by evaluating selectors against the current page: return context.choose({ 'templateName': 'homePage', @@ -40,9 +47,17 @@ The konf is also used to determine which templates will render for each page by }, } -The first selector will search the current page for an element with the id of `product-carousel`. If it finds it, the required key `products` evaluates to true and the page will immediately be rendered with _homePage.tmpl_. If not, then (and only then) the second selector is evaluated and if an element with a `product-list` class is found, the page will instead be rendered with _productPage.tmpl_. See below for more on how `context.choose` works. +The first selector will search the current page for an element with +the id of `product-carousel`. If it finds it, the required key +`products` evaluates to true and the page will immediately be rendered +with _homePage.tmpl_. If not, then (and only then) the second selector +is evaluated and if an element with a `product-list` class is found, +the page will instead be rendered with _productPage.tmpl_. See below +for more on how `context.choose` works. -Only templates with required keys that evaluate to truthy values will render, and when multiple templates could potentially apply only the first matching template will be chosen for the page. +Only templates with required keys that evaluate to truthy values will +render, and when multiple templates could potentially apply only the +first matching template will be chosen for the page. Template mapping is accomplished through DOM matching. @@ -50,7 +65,9 @@ For example, instead of simply defining templates this way: 'homePage': 'home.tmpl' -You would instead find unique selectors that only apply on the page you want to render with a template, then assign that template using `context.choose`: +You would instead find unique selectors that only apply on the page +you want to render with a template, then assign that template using +`context.choose`: return context.choose({ 'templateName': 'homePage', @@ -59,7 +76,10 @@ You would instead find unique selectors that only apply on the page you want to }, } -Single selectors as above are easy enough, but we recommend instead describing (via selections) the ideal DOM including all elements on the page that you will adapt for your mobile site. Then assign a template to that desired DOM: +Single selectors as above are easy enough, but we recommend instead +describing (via selections) the ideal DOM including all elements on +the page that you will adapt for your mobile site. Then assign a +template to that desired DOM: return context.choose({ 'templateName': 'homePage', @@ -74,18 +94,37 @@ Single selectors as above are easy enough, but we recommend instead describing ( } }, -Why do it this more verbose way? We believe the most robust method of selecting content for your mobile site is by describing the overall makeup of the page rather than having your selectors rely too heavily on any one specific class or id. +Why do it this more verbose way? We believe the most robust method of +selecting content for your mobile site is by describing the overall +makeup of the page rather than having your selectors rely too heavily +on any one specific class or id. -We all know that websites change. When your source DOM becomes even superficially different from when you developed your mobile site, there's a chance that your once-valid selections will stop matching and your mobile users will experience missing content or blank pages. +We all know that websites change. When your source DOM becomes even +superficially different from when you developed your mobile site, +there's a chance that your once-valid selections will stop matching +and your mobile users will experience missing content or blank pages. -With the above example, what happens when the sale ends? Sales items removed from the DOM mean the required `saleItems` key no longer returns a truthy result. Mobify.js has a choice in this situation - it could either stop rendering required items, or fall back to the desktop site. Since `productCarousel` and `customerService` are also required, they would not render at all if we were to choose the former approach. +With the above example, what happens when the sale ends? Sales items +removed from the DOM mean the required `saleItems` key no longer +returns a truthy result. Mobify.js has a choice in this situation - +it could either stop rendering required items, or fall back to the +desktop site. Since `productCarousel` and `customerService` are also +required, they would not render at all if we were to choose the former +approach. -On the chance that `productCarousel`, `customerService` or any other required selections make up the bulk of your home page content, we think it's far better to fall back to the desktop site. This approach will continue to provide your users with content instead of serving them a mostly empty mobile site. +On the chance that `productCarousel`, `customerService` or any other +required selections make up the bulk of your home page content, we +think it's far better to fall back to the desktop site. This approach +will continue to provide your users with content instead of serving +them a mostly empty mobile site. ## 2\. `OUTPUTHTML` -`OUTPUTHTML` is a special key of the konf object. Any string it returns will be rendered immediately as the output of the page. For this reason, it should **always** be declared as the very last key of the konf object: +`OUTPUTHTML` is a special key of the konf object. Any string it +returns will be rendered immediately as the output of the page. +For this reason, it should **always** be declared as the very last +key of the konf object: 'OUTPUTHTML': function(context) { return '

HELLO MOBIFY!

' @@ -94,7 +133,10 @@ On the chance that `productCarousel`, `customerService` or any other required se ## 3\. `context.data(key)` -Returns the value of a previously-assigned key in the konf object. Since the konf object is evaluated from top to bottom, it is possible to access previous keys in later assignments. For example you may wish to reuse a selection made for the `content` within `footer`. +Returns the value of a previously-assigned key in the konf object. +Since the konf object is evaluated from top to bottom, it is possible +to access previous keys in later assignments. For example you may wish +to reuse a selection made for the `content` within `footer`. 'content': function() { return $('.page-content') @@ -103,24 +145,33 @@ Returns the value of a previously-assigned key in the konf object. Since the kon return context.data('content'); } -This passes to `footer` the value of the `content` key, which is in turn the evaluated return of `$('.page-content')`. +This passes to `footer` the value of the `content` key, which is in +turn the evaluated return of `$('.page-content')`. **Variable Resolution** -`context.data(key)` returns the matching key at the closest level. If the key is not found at the current level, it ascends to the parent level and tries again. +`context.data(key)` returns the matching key at the closest level. If +the key is not found at the current level, it ascends to the parent +level and tries again. ## 4\. `context.tmpl(template)` -Returns the specified .tmpl file template, rendered against the evaluated konf object. +Returns the specified .tmpl file template, rendered against the +evaluated konf object. 'OUTPUTHTML': function(context) { return context.tmpl('home') } -This renders the _home.tmpl_ via the `OUTPUTHTML` key. By default, all _.tmpl_ files in the project's _tmpl/_ folder are available to the `context.tmpl` function. +This renders the _home.tmpl_ via the `OUTPUTHTML` key. By default, +all _.tmpl_ files in the project's _tmpl/_ folder are available to the +`context.tmpl` function. -A common pattern is to conditionally assign template names to a specific key in the konf object, access the key with `context.data`, then use `context.tmpl` to render the selected template using the `OUTPUTHTML` key: +A common pattern is to conditionally assign template names to a +specific key in the konf object, access the key with `context.data`, +then use `context.tmpl` to render the selected template using the +`OUTPUTHTML` key: 'template': 'home', 'OUTPUTHTML': function(context) { @@ -128,12 +179,16 @@ A common pattern is to conditionally assign template names to a specific key in return context.tmpl(template) } -This assigns a value of `home` to the key later referenced by `context.data`. The returned value is passed to _context.tmpl_ as a template name, which is returned to `OUTPUTHTML` for rendering. +This assigns a value of `home` to the key later referenced by +`context.data`. The returned value is passed to _context.tmpl_ as a +template name, which is returned to `OUTPUTHTML` for rendering. ## 5\. `context.choose(obj1[, obj2[, ...]])` -Accepts anonymous JSON objects as parameters and returns the first object that matches. An object is considered to match if all internal keys prefixed with `!` evaluate to a truthy value: +Accepts anonymous JSON objects as parameters and returns the first +object that matches. An object is considered to match if all internal +keys prefixed with `!` evaluate to a truthy value: 'content': function(context) { return context.choose({ @@ -147,7 +202,10 @@ Accepts anonymous JSON objects as parameters and returns the first object that m }) } -In this example, the first object would match if the function assigned to the key `!home` evaluated to a truthy value. If it did not, the first object would not match and the next object would be tested. If both match, only the first is returned. +In this example, the first object would match if the function assigned +to the key `!home` evaluated to a truthy value. If it did not, the +first object would not match and the next object would be tested. If +both match, only the first is returned. An object with no required selections always matches: @@ -159,7 +217,8 @@ An object with no required selections always matches: }) } -If no matching objects are found `context.choose` returns undefined. Multiple keys may be prefixed with `!` to create `and` conditions: +If no matching objects are found `context.choose` returns undefined. +Multiple keys may be prefixed with `!` to create `and` conditions: 'home': function(context) { return context.choose({ @@ -173,9 +232,13 @@ If no matching objects are found `context.choose` returns undefined. Multiple ke }, } -So in this case if both selections evaluate to truthy values within the current page, the home key will be assigned the value of `templateName`, otherwise it remains unassigned. +So in this case if both selections evaluate to truthy values within +the current page, the home key will be assigned the value of +`templateName`, otherwise it remains unassigned. -A common pattern in a konf object is to use `context.choose` to select template specific content and set a key which will be used as the template name: +A common pattern in a konf object is to use `context.choose` to select +template specific content and set a key which will be used as the +template name: 'content': function(context) { return context.choose({ @@ -200,19 +263,23 @@ A common pattern in a konf object is to use `context.choose` to select template **Truthiness Of Required Selections, Keys Prefixed With `!`** -`context.choose()` considers a selection to be truthy if it matches one of the following conditions: +`context.choose()` considers a selection to be truthy if it matches +one of the following conditions: obj.length && obj.length > 0 obj == true -If none of these conditions are true then a value is considered falsey. +If none of these conditions are true then a value is considered +falsey. -**Do not change the DOM in required selections in the konf**: you may adversely affect evaluation further down the konf +**Do not change the DOM in required selections in the konf**: you may +adversely affect evaluation further down the konf ## 6\. Reserved Keys -Your konf object extends a default konf object containing the following reserved keys: +Your konf object extends a default konf object containing the +following reserved keys: `$html`: Reference to the source DOM `` element @@ -258,6 +325,11 @@ Your konf object extends a default konf object containing the following reserved ## 7\. Best Practices -* DO: Prefer the matching of more complete DOM outlines over single selectors when assigning templates to specific pages. +* DO: Prefer the matching of more complete DOM outlines over single + selectors when assigning templates to specific pages. -* DO NOT: alter the source DOM in required selectors, as they are evaluated regardless of whether they are used as a context to evaluate templates. If you need to alter the source DOM before templating, do it with a non-required (un-prefixed) selection key. +* DO NOT: alter the source DOM in required selectors, as they are + evaluated regardless of whether they are used as a context + to evaluate templates. If you need to alter the source DOM + before templating, do it with a non-required (un-prefixed) + selection key. diff --git a/docs/template-reference.md b/docs/template-reference.md index d28e007f..5d86fe56 100644 --- a/docs/template-reference.md +++ b/docs/template-reference.md @@ -28,18 +28,31 @@ title: Template Reference ## 1\. Understanding Context -Templates are HTML documents containing variables to be filled in with data. This data comes from the evaluated konf output, referred to as the _context_ for the template. +Templates are HTML documents containing variables to be filled in with +data. This data comes from the evaluated konf output, referred to as +the _context_ for the template. -The context is a tree of all the keys that your konf has evaluated that apply to this template. +The context is a tree of all the keys that your konf has evaluated +that apply to this template. -When developing with Mobify.js, you can view the full tree within your browser's Javascript console (see our tools guide in the Appendix if you're not familiar with its use). Browse to the page you'd like to inspect, open the console and find 'All extracted data' -- expand it to view all evaluated keys. Any of these are available for use as variables within your template. You'll find many internal keys that Mobify generates during operation, see Reserved Keys for a list of these. +When developing with Mobify.js, you can view the full tree within your +browser's Javascript console (see our tools guide in the Appendix if +you're not familiar with its use). Browse to the page you'd like to +inspect, open the console and find 'All extracted data' -- expand it +to view all evaluated keys. Any of these are available for use as +variables within your template. You'll find many internal keys that +Mobify generates during operation, see Reserved Keys for a list of +these. -Note that when we talk about changing levels of context below, we simply mean traversing the levels of this context tree. +Note that when we talk about changing levels of context below, we +simply mean traversing the levels of this context tree. ## 2\. `{foo}` - Variables: Select & Render A Single Variable -Select elements from your source DOM in the konf file, then reference the selection as a variable from any template using the curly brace syntax: +Select elements from your source DOM in the konf file, then reference +the selection as a variable from any template using the curly brace +syntax: *Source HTML input:* @@ -53,7 +66,8 @@ Select elements from your source DOM in the konf file, then reference the select return $("form#search"); }, -*Render the result of the `search` key selection in the konf as a variable within your template:* +*Render the result of the `search` key selection in the konf as a +*variable within your template:
{search} @@ -69,20 +83,30 @@ Select elements from your source DOM in the konf file, then reference the select **Variable Evaluation** -Zepto collections are evaluated by iterating the objects in the collection, taking the JavaScript `outerHTML` attribute of each of them, then concatenating these together. +Zepto collections are evaluated by iterating the objects in the +collection, taking the JavaScript `outerHTML` attribute of each of +them, then concatenating these together. A single DOM Element will evaluate to its `outerHTML` attribute. -Note that all strings are escaped by default, so use a filter (see filter reference below) if you'd like to output HTML. +Note that all strings are escaped by default, so use a filter (see +filter reference below) if you'd like to output HTML. **Variable Resolution** -Variables are first looked-up in the keys at the current level of the context. If a key matching the variable name is not found at this level, the key will be searched for at the next highest level of the context, and so forth until it is found, or the highest level of the context is reached. +Variables are first looked-up in the keys at the current level of the +context. If a key matching the variable name is not found at this +level, the key will be searched for at the next highest level of the +context, and so forth until it is found, or the highest level of the +context is reached. ## 3\. `{foo|bar}` - Variable Filters: Pass The Value `foo` Through Filter `bar` -If you would like to change how a variables value is rendered, especially values produced from Zepto collections or a DOM element, you can use filters. Add a pipe symbol `|` and filter name inside the template tag: +If you would like to change how a variables value is rendered, +especially values produced from Zepto collections or a DOM element, +you can use filters. Add a pipe symbol `|` and filter name inside the +template tag: *Source HTML input:* @@ -104,23 +128,34 @@ If you would like to change how a variables value is rendered, especially values Warning: your balance is low -You can apply multiple filters in a chain by appending another pipe symbol `|` and filter name inside the template tag. Note that filters are cumulative, and will apply each additional filter to the output of the previous one. +You can apply multiple filters in a chain by appending another pipe +symbol `|` and filter name inside the template tag. Note that filters +are cumulative, and will apply each additional filter to the output of +the previous one. **Available Filters** -* `innerHTML` - render the `innerHTML` of a Zepto collection or DOM element. Note: the output of this filter will be HTML escaped, chain with `s` to safely render as HTML. +* `innerHTML` - render the `innerHTML` of a Zepto collection or DOM + element. Note: the output of this filter will be HTML + escaped, chain with `s` to safely render as HTML. -* `openTag` - output the literal opening tag of a DOM element. Note: the output of this filter will be HTML escaped, chain with `s` to safely render as HTML. +* `openTag` - output the literal opening tag of a DOM element. Note: + the output of this filter will be HTML escaped, chain + with `s` to safely render as HTML. -* `closeTag` - output the literal closing tag of a DOM element. Note: the output of this filter will be HTML escaped, chain with `s` to safely render as HTML. - -* `s` - render HTML safe output, unescapes HTML escaped strings, such as values filtered through the `innerHTML` filter. +* `closeTag` - output the literal closing tag of a DOM element. + Note: the output of this filter will be HTML escaped, + chain with `s` to safely render as HTML. +* `s` - render HTML safe output, unescapes HTML escaped strings, such + as values filtered through the `innerHTML` filter. ## 4\. `{#foo} ... {/foo}` - Accessing Attributes Of, Or Descending Into The Variable `foo` -You are able to access any variable and its attributes. To simply access an attribute, you can use the simpler '{variable.attribute}' syntax: +You are able to access any variable and its attributes. To simply +access an attribute, you can use the simpler '{variable.attribute}' +syntax: *Source HTML input:* @@ -155,7 +190,10 @@ You are able to access any variable and its attributes. To simply access an attr

DemoCorp Inc.

-Note that you can also access the same attribute within your template by descending into the header block, which is valuable when you have attached multiple attributes to the same variable. The output HTML would be identical to the last example: +Note that you can also access the same attribute within your template +by descending into the header block, which is valuable when you have +attached multiple attributes to the same variable. The output HTML +would be identical to the last example:
{#header} @@ -166,7 +204,10 @@ Note that you can also access the same attribute within your template by descend ## 5\. `{#foo} ... {.} ... {/foo}` - Iterate Over The Variable `foo` -When you make a selection within the konf that returns a set with multiple elements, you can easily iterate through those elements in your template using the '.' attribute, which is a reference to the current iteration: +When you make a selection within the konf that returns a set with +multiple elements, you can easily iterate through those elements in +your template using the '.' attribute, which is a reference to the +current iteration: *Source HTML input:* @@ -192,7 +233,8 @@ When you make a selection within the konf that returns a set with multiple eleme } } -*Descend into the `header` variable to access `logo` and `nav` attributes, also iterate `nav`:* +*Descend into the `header` variable to access `logo` and `nav` +attributes, also iterate `nav`:*
{#header} @@ -219,7 +261,8 @@ When you make a selection within the konf that returns a set with multiple eleme ## 6\. `{>foo/}` - Include The Partial `foo` Inside The Current Template -Partials, also known as template includes, allow you to make a template composed of other templates: +Partials, also known as template includes, allow you to make a +template composed of other templates: *Contents of partial `logo`:* @@ -248,9 +291,11 @@ This would insert the template _logo.tmpl_ into _foo.tmpl_. ## 7\. `{+bar} ... {/bar}` - Block Placeholders -Blocks allow you to define snippets of template code that may be overridden by other templates: +Blocks allow you to define snippets of template code that may be +overridden by other templates: *Adding an overridable block `header` to _foo.tmpl_:* + {+header}Plain Old Default Header{/header} See *Block Overrides* below for override usage. @@ -265,20 +310,26 @@ Adding an overridable block `header` to _foo.tmpl_: {/header} {>products/} -Overrides the content of `header` in _foo.tmpl_ from within the included template _products.tmpl_: +Overrides the content of `header` in _foo.tmpl_ from within the +included template _products.tmpl_: {/src/tmpl/home.tmpl ## Use A Base Template -The bulk of your template logic should be inherited from another template using partials and blocks. For example, _base.tmpl_: +The bulk of your template logic should be inherited from another +template using partials and blocks. For example, _base.tmpl_: @@ -371,10 +430,15 @@ And in `home`: ## Prefix Introduced Styling Attributes With `x-` -Mobify.js preserves the attributes and content of elements selected from the source DOM. To differentiate between content from templates and content selected from the source DOM, it can be helpful to prefix attributes you introduce in your templates for the sake of styling. +Mobify.js preserves the attributes and content of elements selected +from the source DOM. To differentiate between content from templates +and content selected from the source DOM, it can be helpful to prefix +attributes you introduce in your templates for the sake of styling.
{banner}
-We recommend you prefix all classes and IDs introduced in templates with `x-` to allow you to easily identify content introduced with the template. +We recommend you prefix all classes and IDs introduced in templates +with `x-` to allow you to easily identify content introduced with the +template. \ No newline at end of file diff --git a/docs/understanding-konf.md b/docs/understanding-konf.md index 8b494afc..114025c4 100644 --- a/docs/understanding-konf.md +++ b/docs/understanding-konf.md @@ -5,9 +5,14 @@ title: Understanding the Konf # Understanding The Konf -The konf file is JavaScript code that makes selections from the source DOM, chooses a template to render and renders that template with those selections as the context. [Learn more about templates](https://support.mobify.com/customer/portal/articles/511698-understanding-templates) +The konf file is JavaScript code that makes selections from the source +DOM, chooses a template to render and renders that template with those +selections as the context. [Learn more about +templates](https://support.mobify.com/customer/portal/articles/511698 +-understanding-templates) -A konf file is required in every Mobify project and lives at _src/mobify.konf_. +A konf file is required in every Mobify project and lives at +_src/mobify.konf_. Here is a very minimal _mobify.konf_: @@ -22,11 +27,17 @@ Here is a very minimal _mobify.konf_: } {/data} -Inside the `{"/base/lib/base_konf.konf"/} {` element. +We use it to make selections from the source DOM, in this case it will +return the source DOM's `` element. -Konf key values _must_ be anonymous functions that explicitly return the selected data: +Konf key values _must_ be anonymous functions that explicitly return +the selected data: // WRONG! Not a function! 'body-element': $('body') @@ -59,7 +74,9 @@ Konf key values _must_ be anonymous functions that explicitly return the selecte return $('body') } -When called, these functions will be passed an argument that is conventionally named `context`. Using this argument is optional, but it enables additional functionality: +When called, these functions will be passed an argument that is +conventionally named `context`. Using this argument is optional, but +it enables additional functionality: 'body-element': function() { return $('body') @@ -68,6 +85,11 @@ When called, these functions will be passed an argument that is conventionally n return context.data('body-element').find('img') } -Here, the function assigned to the key `'images'` uses the `context.data()` function to look up the previously assigned value of the key `'body-element'`, which is a Zepto set containing the source DOM's `` element, and then finds all of its child `` elements using Zepto's `.find()` function. - -`context.choose`, `context.data`, and `context.tmpl` are functions that require `context` to be passed, [learn more about them](https://support.mobify.com/customer/portal/articles/511630-konf-reference) +Here, the function assigned to the key `'images'` uses the +`context.data()` function to look up the previously assigned value of +the key `'body-element'`, which is a Zepto set containing the source +DOM's `` element, and then finds all of its child `` +elements using Zepto's `.find()` function. + +`context.choose`, `context.data`, and `context.tmpl` are functions +that require `context` to be passed, [learn more about them](https://support.mobify.com/customer/portal/articles/511630-konf-reference) diff --git a/docs/understanding-templates.md b/docs/understanding-templates.md index 6a67c8fa..e5e0baf4 100644 --- a/docs/understanding-templates.md +++ b/docs/understanding-templates.md @@ -5,13 +5,15 @@ title: Understanding Templates # Understanding Templates -<<<<<<< HEAD -With Mobify.js, you use templates to place the selections you make from the source DOM into the mobified web page. A template is a text file that contains regular HTML markup, as well as variables that are replaced with the selections from your konf when the template is rendered. [Learn more about konf files](https://support.mobify.com/customer/portal/articles/511656-understanding-the-konf) +With Mobify.js, you use templates to place the selections you make +from the source DOM into the mobified web page. A template is a text +file that contains regular HTML markup, as well as variables that are +replaced with the selections from your konf when the template is +rendered. [Learn more about konf files](https://support.mobify.com/customer/portal/articles/511656-understanding-the-konf) -A common pattern is to create an object in the konf that selects data from the source DOM, then call `context.tmpl(templateName)` to render the template and assign the result to the `OUTPUTHTML` key. -======= -In Mobify.js, templates are used to remix the source DOM and give you control over the output of your page. A template is a text file that contains regular HTML markup, plus variables that are replaced when the template is rendered. Context for the replacement variables comes from your project's konf, a file where you select objects from your original source DOM and match selections to specific templates. [Learn more about konf files](https://support.mobify.com/customer/portal/articles/511656-understanding-the-konf) ->>>>>>> origin/docs +A common pattern is to create an object in the konf that selects data +from the source DOM and then call `context.tmpl(templateName)` to +render the template and assign the result to the `OUTPUTHTML` key. The following konf renders the `home` template to the browser: @@ -31,17 +33,20 @@ The following konf renders the `home` template to the browser: } -<<<<<<< HEAD -In this example, if the `home` object is matched, then the value `home` will be assigned to the key `mobileSite.templateName`. +In this example, if the `home` object is matched, then the value +`home` will be assigned to the key `mobileSite.templateName`. -Mobify.js compiles all files ending in _.tmpl_ in the _/src/tmpl/_ directory and makes them available to the `context.tmpl()` function as the protion fo their filename before _.tmpl_. -======= -In this example, if the `home` object was matched, then the value `home` will be assigned to the key `mobileSite.templateName`. Mobify.js compiles files matching _/src/tmpl/\*.tmpl_ and makes them available to the `context.tmpl` function under their filename. This example would render the template _home_, which is compiled from _src/tmpl/home.tmpl_. This is explained in more detail in the [konf reference](https://support.mobify.com/customer/portal/articles/511630-konf-reference). ->>>>>>> origin/docs +Mobify.js compiles all files ending in _.tmpl_ in the _/src/tmpl/_ +directory and makes them available to the `context.tmpl()` function as +the protion fo their filename before _.tmpl_. -This example would render the template _home_, which is compiled from _src/tmpl/home.tmpl_. This is explained in more detail in the [konf reference](https://support.mobify.com/customer/portal/articles/511630-konf-reference) +This example would render the template _home_, which is compiled from +_src/tmpl/home.tmpl_. This is explained in more detail in the [konf +reference](https://support.mobify.com/customer/portal/articles/511630 +-konf-reference) -Templates are text files that construct an HTML document. Our _home_ template looks like this: +Templates are text files that construct an HTML document. Our _home_ +template looks like this: @@ -55,7 +60,10 @@ Templates are text files that construct an HTML document. Our _home_ template lo -Assuming that the key `content.products` selected a set of `
` elements, calling `context.tmpl('home')` would evaluate the template with the selected data, producing a string containing the following markup: +Assuming that the key `content.products` selected a set of `
` +elements, calling `context.tmpl('home')` would evaluate the template +with the selected data, producing a string containing the following +markup: @@ -67,4 +75,4 @@ Assuming that the key `content.products` selected a set of `
` elements, cal
  • Product 3
    • - + \ No newline at end of file