new readme spec

Author: Jeff Escalante

README.md

@@ -1,213 +1,210 @@
 # Expressions for PostHTML
 
-## Install
-```sh
-npm i posthtml-exp
-```
+Local variables, expressions, loops, and conditionals in your html
 
-## Options
-### Style
-Choose one of the following expression syntaxes. If **options.style** is unset, the default syntax (JSX) is used.
+## Installation
 
-##### JSX: **'{'**
+First, install from npm with `npm i posthtml-exp --save`, then add it as a plugin to your posthtml pipeline:
 
-```html
-<div id="{id}" class="{class}">{content}</div>
-```
-##### HBS:  **'{{'**
+```js
+const posthtml = require('posthtml')
+const exp = require('posthtml-exp')
+const {readFileSync} = require('fs')
 
-```html
-<div id="{{id}}" class="{{class}}">{{content}}</div>
+posthtml(exp({ locals: { foo: 'bar' } }))
+  .process(readFileSync('exampleFile.html', 'utf8'))
+  .then(console.log)
 ```
-##### Blaze:  **'@'**
 
-```html
-<div id="@id" class="@name">@content</div>
-```
+## Usage
 
-For example, to change to handlebars-style delimiters:
+This plugin provides a syntax for including local variables and expressions in your templates, and also extends custom tags to act as helpers for conditionals and looping.
 
-```js
-let exps = require('posthtml-exp')({
-  style: '{{'
-})
-```
+You have full control over the delimiters used for injecting locals, as well as the tag names for the conditional and loop helpers, if you need them. All options that can be passed to the `exp` plugin are shown below:
+
+| Option | Description | Default |
+| ------ | ----------- | ------- |
+| **delimiters** | Array containing beginning and ending delimiters for escaped locals. | `['{{', '}}']` |
+| **unescapeDelimiters** | Array containing beginning and ending delimiters for inserting unescaped locals. | `['{{{', '}}}']` |
+| **locals** | Object containing any local variables you want to be available inside your expressions. |
+| **conditionalTags** | Array containing names for tags used for standard `if`/`else if`/`else` logic | `['if', 'elseif', 'else']` |
+| **loopTags** | Array containing names for standard `for` loop logic | `['each']` |
 
 ### Locals
-#### Set locals directly as arguments
-```js
-let exps = require('posthtml-exp')({
-  locals: {/* locals */}
-})
-```
-#### Load locals from an external file
+
+You can inject locals into any piece of content in your html templates, other than overwriting tag names. For example, if you passed the following config to the exp plugin:
+
 ```js
-let exps = require('posthtml-exp')({
-  locals: {/* 'path/to/file.(js|json) '*/}
+exp({
+  locals: { myClassName: 'introduction', myName: 'Jeff' }
 })
 ```
-```js
-exports = module.exports = {/* locals */}
-```
-```json
-{
-  "name": "PostHTML Exps",
-  "repo": {
-    "name": "posthtml-exp",
-    "url": "https://github.com/michael-ciniawsky/posthtml-exp"
-  }
-}
-```
 
-## Paths
-Expression and Helper arguments can be expressed with dot notation syntax. The current limit for nesting is set to 3.
-```js
-{
-  local: {
-    key1: {
-      key2: {
-        key3: 'PostHtML Expressions'
-      }
-    }
-  }
-}
-```
+And compiled with the following template:
+
 ```html
-<div>
-  <h2>{local.one.two.tree}</h2>
+<div class="{{ myClassName }}">
+  My name is {{ myName }}
 </div>
 ```
+
+You would get this as your output:
+
 ```html
-<div>
-  <h2>PostHTML Expressions</h2>
+<div class="introduction">
+  My name is Jeff
 </div>
 ```
 
-## Helpers
-### Each **{...}**
+### Unescaped Locals
+
+By default, special characters will be escaped so that they show up as text, rather than html code. For example, if you had a local containing valid html as such:
+
 ```js
-{
-  locals: {
-    fruits: ['Apple', 'Orange', 'Mango']
-  }
-}
+exp({
+  locals: { strongStatement: '<strong>wow!</strong>' }
+})
 ```
+
+And you rendered it into a tag like this:
+
 ```html
-<ul>
-  <li>{...fruits}</li>
-</ul>
+<p>The fox said, {{ strongStatement }}</p>
 ```
+
+You would see the following output:
+
 ```html
-<ul>
-  <li>Apple</li>
-  <li>Orange</li>
-  <li>Mango</li>
-</ul>
+<p>The fox said, &lt;strong&gt;wow!&lt;strong&gt;</p>
 ```
 
-### Pipe **{ | }**
-```js
-{
-  locals: {
-    firstname: 'PostHTML',
-    lastname: 'Expressions'
-  }
-}
+In your browser, you would see the angle brackets, and it would appear as intended. However, if you wanted it instead to be parsed as html, you would need to use the `unescapeDelimiters`, which by default are three curly brackets, like this:
+
+```html
+<p>The fox said, {{{ strongStatement }}}</p>
 ```
+
+In this case, your code would render as html:
+
 ```html
-<h1>{locals|firstname|lastname}</h1>
+<p>The fox said, <strong>wow!<strong></p>
 ```
+
+### Expressions
+
+You are not limited to just directly rendering local variables either, you can include any type of javascript expression and it will be evaluated, with the result rendered. For example:
+
 ```html
-<h1>PostHTML Expressions</h1>
+<p class="{{ env === 'production' ? 'active' : 'hidden' }}">in production!</p>
 ```
 
-### Partial **{> }**
+With this in mind, it is strongly recommended to limit the number and complexity of expressions that are run directly in your template. You can always move the logic back to your config file and provide a function to the locals object for a smoother and easier result. For example:
+
 ```js
-{
+exp({
   locals: {
-    button: './includes/button.html'
+    isProduction: (env) => {
+      return env === 'production' ? 'active' : 'hidden'
+    }
   }
-}
-```
-```html
-<div>{> button}</div>
+})
 ```
+
 ```html
-<div>
-  <button>Click Me!</button>
-</div>
+<p class="{{ isProduction(env) }}">in production!</p>
 ```
 
-## Usage
-For general usage and build process integration see [PostHTML Docs](https://github.com/posthtml/posthtml#usage)
-
-### Example using Node API
-#### Default
-```js
-'use strict'
+### Conditional Logic
 
-const fs = require('fs')
+Conditional logic uses normal html tags, and modifies/replaces them with the results of the logic. If there is any chance of a conflict with other custom tag names, you are welcome to change the tag names this plugin looks for in the options. For example, given the following config:
 
-const posthtml = require('posthtml')
-
-const exp = require('posthtml-exp')({
-  locals: {
-    id: 'title',
-    class: 'header',
-    content: 'PostHTML Exps Default'
-  }
+```js
+exp({
+  locals: { foo: 'foo' }
 })
+```
 
-let file = fs.readFileSync('./index.html', 'utf-8')
+And the following html:
 
-posthtml([ exp ])
-  .process(file)
-  .then(result => console.log(result.html))
-```
-##### Input
 ```html
-<div class={class}>
-  <h1 id={id}>{content}</h1>
-</div>
+<if condition="foo === 'bar'">
+  <p>Foo really is bar! Revolutionary!</p>
+</if>
+<elseif condition="foo === 'wow'">
+  <p>Foo is wow, oh man.</p>
+</elseif>
+<else>
+  <p>Foo is probably just foo in the end.</p>
+</else>
 ```
-##### Output
+
+Your result would be only this:
+
 ```html
-<div class="header">
-   <h1 id="title">PostHTML Exps</h1>
-</div>
+<p>Foo is probably just foo in the end.</p>
 ```
-#### Custom
-```js
-'use strict'
 
-const fs = require('fs')
+Anything in the `condition` attribute is evaluated directly as an expression.
 
-const posthtml = require('posthtml')
+It should be noted that this is slightly cleaner-looking if you are using the [SugarML parser](https://github.com/posthtml/sugarml). But then again so is every other part of html.
+
+```sml
+if(condition="'foo' === 'bar'")
+  p Foo really is bar! Revolutionary!
+elseif(condition="'foo' === 'wow'")
+  p Foo is wow, oh man.
+else
+  p Foo is probably just foo in the end.
+```
 
-const exp = require('posthtml-exp')({
-  style: '{{',
+#### Loops
+
+You can use the `each` tag to build loops. It works with both arrays and objects. For example:
+
+```js
+exp({
   locals: {
-    id: 'title',
-    class: 'header',
-    content: 'PostHTML Exps Default'
+    anArray: ['foo', 'bar'],
+    anObject: { foo: 'bar' }
   }
 })
+```
+
+```html
+<each loop="item, index in anArray">
+  <p>{{ index }}: {{ item }}</p>
+</each>
+```
 
-let file = fs.readFileSync('./index.html', 'utf-8')
+Output:
 
-posthtml([ exp ])
-  .process(file)
-  .then(result => console.log(result.html))
+```html
+<p>1: foo</p>
+<p>2: bar</p>
 ```
-##### Input
+
+And an example using an object:
+
 ```html
-<div class={{class}}>
-  <h1 id={{id}}>{{content}}</h1>
-</div>
+<each loop="key, value in anObject">
+  <p>{{ key }}: {{ value }}</p>
+</each>
 ```
-##### Output
+
+Output:
+
 ```html
-<div class="header">
-   <h1 id="title">PostHTML Exps Custom</h1>
-</div>
+<p>foo: bar</p>
 ```
+
+The value of the `loop` attribute is not a pure expression evaluation, and it does have a tiny and simple custom parser. Essentially, it starts with one or more variable declarations, comma-separated, followed by the word `in`, followed by an expression.
+
+So this would also be fine:
+
+```html
+<each loop="item in [1,2,3]">
+  <p>{{ item }}</p>
+</each>
+```
+
+So you don't need to declare all the available variables (in this case, the index is skipped), and the expression after `in` doesn't need to be a local variable, it can be any expression.

package.json

@@ -3,7 +3,7 @@
   "version": "0.8.1",
   "description": "Template Expressions for PostHTML",
   "engines": {
-    "node": ">=4"
+    "node": ">=6"
   },
   "main": "index.js",
   "dependencies": {},