Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Docs: Clarify Understanding the Konf by talking more about templates and... #73

Merged
merged 3 commits into from

2 participants

@johnboxall
Owner

... less about selections.

  • Fix a spelling mistake in the Navigation.
  • Add a serve command to the Makefile.
johnboxall and others added some commits
@johnboxall johnboxall Docs: Clarify Understanding the Konf by talking more about templates …
…and less about selections.

- Fix a spelling mistake in the Navigation.
- Add a `serve` command to the Makefile.
f612422
@noahadams noahadams remove an extra "is" e115273
@noahadams noahadams Merge remote-tracking branch 'origin/master' into docs-fixes
Conflicts:
	www/_includes/nav-docs.md
fcf4819
@noahadams
Owner

:+1: changes are good and new "make serve" command is useful, also did a quick grammar fix on something I spotted.

@noahadams noahadams merged commit 18fce8e into master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Aug 27, 2012
  1. @johnboxall

    Docs: Clarify Understanding the Konf by talking more about templates …

    johnboxall authored
    …and less about selections.
    
    - Fix a spelling mistake in the Navigation.
    - Add a `serve` command to the Makefile.
Commits on Jan 7, 2013
  1. @noahadams

    remove an extra "is"

    noahadams authored
  2. @noahadams

    Merge remote-tracking branch 'origin/master' into docs-fixes

    noahadams authored
    Conflicts:
    	www/_includes/nav-docs.md
This page is out of date. Refresh to see the latest.
Showing with 40 additions and 29 deletions.
  1. +4 −0 Makefile
  2. +36 −29 www/docs/understanding-konf.md
View
4 Makefile
@@ -23,4 +23,8 @@ buildstatic: modules ; \
jekyll ; \
rm static/downloads/*
+serve:
+ cd www ; \
+ jekyll --server --auto
+
.PHONY: modules
View
65 www/docs/understanding-konf.md
@@ -24,8 +24,8 @@ Here is a minimal _mobify.konf_:
} {/konf}
-Inside the `{<konf} ... {/konf}` block, we declare an object
-called the konf object. We give the konf object a key _[OUTPUTHTML]({{ site.baseurl }}/docs/konf-reference/#outputhtml)_
+Inside the `{<konf} ... {/konf}` block, we declare the konf object.
+We give the konf object a key _[OUTPUTHTML]({{ site.baseurl }}/docs/konf-reference/#outputhtml)_
and assign that to a function that returns an HTML string. When the konf
object is evaluated, the function assigned to _OUTPUTHTML_ is called.
The value assigned to _OUTPUTHTML_ is immediately rendered to the browser.
@@ -67,8 +67,8 @@ Konf key values _must_ be functions that return their selections:
return $('body');
}
-All konf key values are passed an argument called [`context`]({{ site.baseurl }}/docs/konf-reference/).
-The argument is optional, but it enables additional functionality:
+All konf key functions are passed an argument called [`context`]({{ site.baseurl }}/docs/konf-reference/).
+The argument is optional, and enables additional functionality:
'body-element': function() {
return $('body');
@@ -85,10 +85,8 @@ It then finds all of its child _<img>_ elements using Zepto's
## Konf in Practice
-Inside the konf, it is common to have a number of selections that are
-made on every page. For example, elements in the header may appear on
-every page of the adapted site. These global selections can be made by
-adding additional keys to konf.
+Often you will want elements like the header to appear on every page
+of your site. Global selections can be made by adding more keys to konf:
// Keys on the konf object are added to the context
'header': function() {
@@ -104,39 +102,48 @@ adding additional keys to konf.
}
}
-Often the konf will contain selections that should only be used on certain
-pages. For example, an image carousel may only appear on the homepage.
-To manage selections that should only be made on certain pages we use
-[`context.choose`]({{ site.baseurl }}/docs/konf-reference/#context-choose):
+Often you will want to use different templates to adapt different pages
+of you site. For example, you may use the template _home_ to adapt the
+homepage of your site while using the template _products_ on the product
+listing page.
+
+Inside the konf, this can be handled by using `context.choose` to select
+a template and then passing that template name to `context.tmpl`:
'content': function(context) {
- // `context.choose` is used to conditionally
- // add keys to the context
return context.choose({
- 'templateName': 'home'
- , '!carousel': function() {
- return $('#main .pics')
+ 'templateName': 'home',
+ '!home': function() {
+ return $('#home');
}
}, {
- 'templateName': 'products'
- , '!products': function() {
- return $('#products')
+ 'template': 'item',
+ '!item': function() {
+ return $('#item');
}
- })
+ });
+ },
+ 'OUTPUTHTML': function(context) {
+ var template = context.data('content.templateName');
+ if (template) {
+ return context.tmpl(template);
+ }
}
`context.choose` accepts a variable number of objects as arguments and
evaluates the first one that matches. An argument is said to match if
-its keys starting with `!` all evaluate to truthy values.
+all keys starting with `!` evaluate to truthy values.
+
+In the example above, when _content_ is evaluted, `context.choose` is
+called. It checks the first argument and finds one required key, _home_. If
+`$('#home')` is found in the source DOM then the first argument will match.
+`context.choose` will then add the keys _templateName_ and _home_ under the
+group _content_. If `$('#home')` is not found, it would move to the next
+argument and repeat the process.
-In the example above, when _content_ is evaluted, `context.choose` will
-be called. It inspects the first argument and finds one required key
-_carousel_. If `$('#main .pics')` is found on the page then the first
-argument will match. `context.choose` will then add the keys
-_templateName_ and _carousel_ under the group _content_.
+Later, when _OUTPUTHTML_ is evaluted, the value of _content.templateName_
+will be used to decide which template to render.
-If `$('#main .pics')` was not found, it would move to the next argument
-and repeat the process.
---
Something went wrong with that request. Please try again.