Permalink
Browse files

Merge pull request #27 from mobify/docs-formatting

Docs formatting
  • Loading branch information...
Ryan Daw
Ryan Daw committed Jul 5, 2012
2 parents cc32331 + 1b7869d commit e7dcfdd4f77bd13a5a2d95a54f8865d293538e29
Showing with 391 additions and 232 deletions.
  1. +0 −12 doc/combo.md
  2. +10 −12 docs/appendix.md
  3. +100 −98 docs/getting-started.md
  4. +19 −8 docs/glossary.md
  5. +103 −31 docs/konf-reference.md
  6. +97 −33 docs/template-reference.md
  7. +38 −22 docs/understanding-konf.md
  8. +24 −16 docs/understanding-templates.md
View
@@ -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).
View
@@ -48,19 +48,19 @@ In development mode, the result of the evaluated konf, the context, is logged to
the JavaScript console. Look for a the item _'All Extracted Data'_, which can be
expanded to show what values were assigned to what keys.
-**Note**: Extracted
-Data is only available in development mode, which can be activated by browsing to
-your site through <https://preview.mobify.com/>.
+**Note**: Extracted Data is only available in development mode, which can be
+activated by browsing to your site through <https://preview.mobify.com/>.
If you are stumped, try adding a `debugger;` statement into your konf. This will
cause the inspector's debugger to pause as the konf is evaluated:
-{% highlight javascript %}
-'content': function() {
- debugger;
- // The debugger will pause here.
- return $('.content');
-}
-{% endhighlight %}
+
+
+ 'content': function() {
+ debugger;
+ // The debugger will pause here.
+ return $('.content');
+ }
+
You can then use the inspector to step through the execution of your konf.
## Debugging Templates (Viewing source, inspecting rendered DOM)
@@ -85,14 +85,12 @@ Usually this will be accompanied by the error message:
**Solution:** Ensure that you have a comma after every key within your konf, ie.
-{% highlight javascript %}
'header': {
...
}, // Commas between each key are required
'content': {
},
-{% endhighlight %}
## "{some-key}" displayed on the page
View
@@ -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 <http://cloud.mobify.com>, 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 <http://cloud.mobify.com>, 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/}
{<content}
<h1>About page</h1>
<h3>My phone number: "{content.phonenumber}"</h3>
<p>{content.blurb}</p>
{/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!
View
@@ -13,36 +13,47 @@ 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
> The mobile site's post-adaptation DOM, the output of Mobify.js.
### 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.
Oops, something went wrong.

0 comments on commit e7dcfdd

Please sign in to comment.