Partials Plugin for DocPad

This plugin provides [DocPad](https://docpad.org) with Partials. Partials are documents which can be inserted into other documents, and are also passed by the docpad rendering engine. ## Usage Create the `src/partials` directory, and place any partials you want to use in there. Then call the new `partial(filename, objs...)` template helper to include the partial. The object arguments are optional, and can be used to send custom data to the partial's template data. Setting the first object argument to `false` will not send over the template data by default. ### Examples Lets say we have the partial `src/partials/hello.html.eco` that includes: ```html Hello <%=@name or 'World'%> Welcome to <%= @site?.name or 'My Site' %> ``` And a [docpad configuration file](http://docpad.org) file that includes: ```coffee templateData: site: name: "Ben's Awesome Site" ``` We could then render via a `src/documents/index.html.eco` document in these different ways: ```html <%- @partial('hello') %> <%- @partial('hello', {name:'Ben'}) %> <%- @partial('hello', false) %> <%- @partial('hello', false, {name:'Ben'}) %> <%- @partial('hello', false, {site:{name:@site.name}}, {name:'Ben'}) %> ``` ### Notes To increase performance it is recommended you only include the exact template data variables that you need - this is because sending over all the template data can be a costly process as we much destroy all references (do a deep clone) to avoid reference conflicts and over-writes between each render - so sending over as little / as specific data as possible means less reference destroying which means faster processing. If your partial only needs to be rendered once per (re)generation then you can specify `cacheable: true` in the partial's meta data, doing so greatly improves performance. Partials actually render asynchronously, when you call `<%- @partial('hello') %>` you'll actually get back something a temporary placeholder like `[partial:0.1290219301293]` while your template is rendering, then once your template has rendered, and once all the partials have rendered, we will then go through and replace these placeholder values with the correct content. We must do this as template rendering is a synchronous process whereas document rendering is an asynchronous process. [More info here.](https://github.com/docpad/docpad-plugin-partials/issues/12) ### Compatibility - Versions 2.8.0 and above DO send the template data by default. You can turn this off by using `false` as the first object argument or by setting `performanceFirst: true` in your plugin's configuration options. - Versions below 2.8.0 DO NOT send the template data by default. You must add it by using `@` or `this` as the first object argument like so: `<%- @partial('my-partial', @) %>`