‚̧Nine Pounds of Mayonnaise
    Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    docpad-plugin-partials

    2.14.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    Partials Plugin for DocPad

    Travis CI Build Status NPM version NPM downloads Dependency Status Dev Dependency Status
    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    This plugin provides DocPad 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:

    Hello <%=@name or 'World'%> Welcome to <%= @site?.name or 'My Site' %>

    And a docpad configuration file file that includes:

    templateData:
        site:
            name: "Ben's Awesome Site"

    We could then render via a src/documents/index.html.eco document in these different ways:

    <!-- Include the rendered contents of `src/partials/my-partial` file -->
    <!-- and send over the template data -->
    <%- @partial('hello') %>
    <!-- gives us:
    Hello World
    Welcome to Ben's Awesome Site
    -->
     
    <!-- Include the rendered contents of `src/partials/my-partial` file -->
    <!-- and send over the template data -->
    <!-- and send over our own custom template data -->
    <%- @partial('hello', {name:'Ben'}) %>
    <!-- gives us:
    Hello Ben
    Welcome to Ben's Awesome Site
    -->
     
    <!-- Include the rendered contents of `src/partials/my-partial` file -->
    <!-- and DO NOT send over the template data -->
    <%- @partial('hello', false) %>
    <!-- gives us:
    Hello World
    Welcome to My Site
    -->
     
    <!-- Include the rendered contents of `src/partials/my-partial` file -->
    <!-- and DO NOT send over the template data -->
    <!-- and send over ONLY our own custom template data -->
    <%- @partial('hello', false, {name:'Ben'}) %>
    <!-- gives us:
    Hello Ben
    Welcome to My Site
    -->
     
    <!-- Include the rendered contents of `src/partials/my-partial` file -->
    <!-- and DO NOT send over the template data -->
    <!-- and send over our own custom template data with the template data site property -->
    <%- @partial('hello', false, {site:{name:@site.name}}, {name:'Ben'}) %>
    <!-- gives us:
    Hello Ben
    Welcome to Ben's Awesome Site
    -->

    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.

    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', @) %>

    Install

    Install this DocPad plugin by entering docpad install partials into your terminal.

    History

    Discover the release history by heading on over to the HISTORY.md file.

    Contribute

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    Backers

    Maintainers

    These amazing people are maintaining this project:

    Sponsors

    No sponsors yet! Will you be the first?

    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    Contributors

    These amazing people have contributed code to this project:

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    License

    Unless stated otherwise all works are:

    and licensed under:

    Install

    npm i docpad-plugin-partials

    DownloadsWeekly Downloads

    117

    Version

    2.14.0

    License

    MIT

    Unpacked Size

    33.7 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar