Plugin opts filter

docs/plugin-locals.md

@@ -0,0 +1,124 @@
+EJS Snippet (plug-in) Reference
+==============================
+
+The Locals plug-in is based on the functionality of 
+https://github.com/RandomEtc/ejs-locals
+
+Locals are not available if opts.client is used.
+
+Table of contents
+-----------------
+
+- Activating the plug-in
+- layout
+- block
+  - script
+  - stylesheet
+- partial
+
+
+Activating the plug-in
+---------------------
+
+The plug-in is activated by requiring it.
+
+`require('ejs/plug-ins/ejs-locals');`
+
+This modifies the global instance of ejs. So any code using `require('ejs');`
+will have an ejs with the plug-in activated.
+
+layout
+------
+
+A layout is a wrapper around the current template. 
+
+Example:
+
+Template "page":
+`Hello world <% layout("layout-bold") %>`
+
+Template "layout-bold"
+`<b><%- body %></b>`
+
+Rendering the template "page" will:
+
+- Get the rendered result of "page"
+- render "layout-bold", passing the result of "page" as the locals value "body"
+- return the result of "layout-bold" to the app.
+
+
+block
+-----
+
+`<% block("foo", "data" %>`: stores "data" as "foo".
+
+`<% block("foo", "more data" %>`: appends "more data" to "foo" (with a newline)
+
+`<%- block("foo" %>`: inserts the content of foo
+
+
+### script
+
+`<% script("SOURCE" %>`: adds a script tag `<script src="SOURCE"></script>`
+
+`<% script("SOURCE", "TYPE" %>`: adds a script tag `<script src="SOURCE" type="TYPE"></script>`
+
+script tags are joined with newlines.
+
+`<%- script() %>': insert the script tags
+
+### stylesheet
+
+`<% stylesheet("SOURCE" %>`:  adds a script tag `<link rel="stylesheet" href="SOURCE" />`
+
+`<% stylesheet("SOURCE", "MEDIA" %>`: adds a script tag `<link rel="stylesheet" href="SOURCE" media="MEDIA" />`
+
+stylesheet tags are joined with newlines.
+
+`<%- stylesheet() %>': insert the stylesheet tags
+
+
+partial
+-------
+
+An extended version of include.
+
+Partials are searched as follows
+
+- relative file names resolve according to the directory of the current template
+- absolute file names resolve in opts.root (or / if opts.root is not set)
+
+The following file names are looked up (example `<%- partial("foo/bar") %>`:
+
+- foo/_bar.ejs
+- foo/bar.ejs
+- foo/bar/index.ejs
+
+Partials can be called as `<%- partial("foo/bar") %>` or `<%- partial("foo/bar", data) %>`
+
+Partials will see the locals, as is at the time they are called.
+
+If data is given, it can be:
+
+- An object (plain object)
+
+The plain object is merged to locals.
+
+
+- An object (plain object) with a "object" key.
+- An object with a custom constructor
+
+This object is passed on a special key in the locals (see collection below)
+
+
+- An object (plain object) with a "collection" key.
+- An array of object (or a collection).
+
+The partial is called for each entry.
+
+The entry is put an a special key in the locals.
+
+The key can be given in the plain object under "as" (unless an array is passed).
+Otherwise it derived from the file name of the partial.
+(foo/bar_some.ejs will become barSome)
+

docs/plugin-opts-filter.md

@@ -0,0 +1,57 @@
+EJS Snippet (plug-in) Reference
+==============================
+
+The OptsFilter plug-in lets you set defaults for all ejs options.
+
+It also offers filters to prevent your app or framework from passing
+certain options to ejs.
+
+The filters can also be used if your framework uses an older calling
+convention and some keys from your locals data are mistaken as options.
+
+
+
+Activating the plug-in
+---------------------
+
+The plug-in is activated by requiring it.
+
+`require('ejs/plug-ins/ejs-opts-filter');`
+
+This modifies the global instance of ejs. So any code using `require('ejs');`
+will have an ejs with the plug-in activated.
+
+
+Configuration
+-------------
+
+`var filter = require('ejs/plug-ins/ejs-opts-filter');`
+
+
+`filter.keepOnlyOpts = ['cache', 'root'];`
+
+Only the options cache and root are kept.
+All other options are blocked.
+
+Use this with caution. You may block important keys, like filename.
+You may also block future options, without knowing the consequences.
+
+
+`filter.removeOpts = ['client'];`
+
+The client option will be blocked.
+All other options will be let through.
+
+
+```
+filter.optsDefaults = {
+  client: false,
+  root: '/tmp'
+};
+```
+
+Will set the client and root option, if they are not specified.
+That is, if there key is not present on the opts object.
+
+The defaults are applied after the filters. 
+So a default can be set to an option that was blocked.

docs/plugin-snippet.md

@@ -0,0 +1,154 @@
+EJS Snippet (plug-in) Reference
+==============================
+
+The Snippet plug-in lets you define snippets (aka Blocks) and use them
+anywhere in your template. This works across include boundaries.
+
+Snippets are not available if opts.client is used.
+
+Table of contents
+-----------------
+
+- Activating the plug-in
+- Defining Snippets
+- Calling Snippets
+- Snippets and included templates
+  - Calling Snippets in included templates
+  - Defining Snippets in included templates
+  - Including templates inside a Snippet
+
+
+Activating the plug-in
+---------------------
+
+The plug-in is activated by requiring it.
+
+`require('ejs/plug-ins/ejs-snippet');`
+
+This modifies the global instance of ejs. So any code using `require('ejs');`
+will have an ejs with the plug-in activated.
+
+Defining Snippets
+-----------------
+
+### Definition
+
+To define a snippet use:
+
+`<%* snippet name %> content <%* /snippet %>`
+
+"content" can be anything, including any ejs code.
+
+If content contains ejs code, then this will not be executed until the snippet
+is called.
+That is any `<%= val %>` or `<% if(val) { %>` will be kept as they are, and
+only be executed when they snippet is called. They therefore see the values
+the snippet is called with, not the values at definition time.
+
+### Hoisting
+
+Snippets are hoisted.
+
+A snippet defined anywhere in a template, can be used anywhere in this 
+template. Even before its definition.
+
+This is useful if snippets call each other in a recursion.
+
+Snippets capture a shallow copy of the "locals". Locals are captured as they
+are at the start of the template. That is any changes made to locals by
+scriptlets in the template will not be seen by the snippet. (Except where 
+a shallow copy does not preserve the data).
+
+```
+<% foo = 'replacement' %>
+<%* snippet name %> <%=foo%> <%* /snippet %>
+```
+
+The snippet captures the locals *before* foo gets changed.
+
+### Nesting
+
+Snippets can *not* be nested.
+
+Calling Snippets
+----------------
+
+Snippets are called using the `snippet()` function (similar to "include" templates).
+The function takes one or two arguments.
+
+```
+<%- snippet("name") %>
+<%- snippet("name", { foo: 5 }) %>
+```
+
+The "snippet" function is available in any javascript part of the ejs template.
+
+Calling the snippet() function is running the snippet, treating the snippet as
+a template of its own.
+The snippet will see the values for locals captured as described in 
+"Defining Snippets".
+If the 2nd argument is given, the values from the 2nd argument are merged to
+the captured locals.
+
+Snippets can call other snippets including them self.
+
+Snippets and included templates
+-------------------------------
+
+Defining and calling snippets in templates called by `include()`
+
+### Calling Snippets in included templates
+
+Included templates can access any snippet that is available in the outer
+template at the time the `include()` is executed.
+
+A snippet is "available" if:
+
+- it is defined anywhere in the outer template.
+- if the outer template is an include itself and the snippet is available to
+  it, from the outer's outer template.
+- if the outer template got the snippet from another `include()` (see below)
+
+
+### Defining Snippets in included templates
+
+If a template is included, then all snippets defined in this template will 
+become available in the outer template.
+
+Such snippets become available at the time the `include()` is executed.
+Once the `include()` was executed they are available anywhere in the outer
+template.
+
+If the template "include-me" defines a snippet called "foo"
+
+```
+<% for(a=1; i<9; i++) { %>
+  <% if(i > 0) { %>
+    <% snippet('foo') %>
+  <% } %>
+  <% include('include-me') %>
+<% } %>
+```
+
+In the first run of the loop, the snippet "foo" would not be defined. But in
+the 2nd run it is defined.
+
+#### Replacing Snippets by included templates
+
+If an included template defines a snippet with the same name as a snippet
+available in the outer template, then the snippet from the included template
+replaces the snippet from the outer template.
+
+In the included template only the new snippet will be used, as it is hoisted.
+
+In the outer template the snippet will be replaced at the time the `include()`
+is executed.
+
+
+### Including templates inside a Snippet
+
+Snippets can contain `include()` calls. And in the include templates
+new snippets can be defined, or existing ones be replaced.
+All the rules above apply.
+
+An include can replace the snippet from which it is called.