docpad-plugin-frontend

v3.0.0

Published

2 years ago

CSS and JS assets manager, based on Frontend Grunt.js task

Downloads

0High
0Medium
0Low

serge.che

docpad docpad-plugin assets frontend font-end css js

A DocPad plugin that manages CSS and JS assets. Combined with Grunt.js’ Frontend task, creates cache-reset links to static files.

The main reasons to use this plugin are:

Get compiled by Grunt.js resources and output links to them with last modified date prefix to effectively reset cache every time resource is re-compiled.
Organize resources into sets that can be selectively redefined in templates and documents.

Installation

Run npm install --save docpad-plugin-frontend command in your DocPad project root.

How it works

This plugin extends template data object with assets(type) method. When called inside layout template, returns sorted list of files for specified type. The type is simply a string identifier of the resource type, for example, css or js.

Whenever you call assets(type) method from template, it will collect resource list of specified type from current document and layout with respect of layout templates inheritance.

Simple example

In your layout template, let’s say default.html.eco, define list of CSS and JS resources in document’s meta data with css and js properties. You can use any name for resources: js, jsFooter, styles etc.

---
css: "/css/style.css"
js:  ["/js/fileA.js", "/js/fileB.js"]
---
<!doctype html>
<html>
<body>
    
</body>
</html>

In the same template, use assets() method to get list of resources (I’m using Eco templates, but you can use any other):

---
css: "/css/style.css"
js:  "/js/fileA.js,/js/fileB.js"
---
<!doctype html>
<html>
<head>
    <% for url in @assets('css'): %><link rel="stylesheet" href="<%= url %>" /><% end %>
    <% for url in @assets('js'): %><script src="<%= url %>"></script><% end %>
</head>
<body>
    
</body>
</html>

If you’re using Grunt.js’ Frontend template task, generated file urls may look like this:

<!doctype html>
<html>
<head>
    <link rel="stylesheet" href="/20121101001423/css/style.css" />
    <script src="/20121101001423/js/fileA.js"></script>
    <script src="/20121001001129/js/fileB.js"></script>
</head>
<body>
    
</body>
</html>

As you can see, generated urls contains numeric prefix which is last compilation date, taken from build catalog generated by Grunt.js Frontend task. Such prefixes can effectively reset cache from static resources every time this resource is recompiled.

Organizing resources

You can organize resources into sets that can be overridden by descendant templates or document. All you need is to add numeric suffix to resource type, like this: css2, js10 and so on.

For example, in default.html.eco template you can define the following resource sets in meta data:

---
js: "fileA.js"
js2: ["fileB.js", "fileC.js"]
js3: "fileD.js"
---

In page.html.eco template, which inherits default.html.eco, you can redefine resource set:

---
layout: default
js2: "foo.js"
---

You can also redefine resource sets in document that uses one of these templates:

---
layout: page
js3: "page.js"
---

The final resource list retrieved by assets('js') call for your document will look like this:

fileA.js
foo.js
page.js

All sets are sorted by numeric suffix.

Debug mode

If you’re using grunt-frontend task to build CSS and JS, you can use a special debug mode. In this mode, assets() method will return a list of source files instead minified ones.

To enable debug mode, you need to set frontendDebug config property to true. It’s best to use different DocPad environment for debugging:

docpadConfig = {
    …
    environments:
        debug:
            frontendDebug: true
}

To view your web-site in debug mode, pass debug environment option to DocPad:

docpad run --env=debug

DocPad configuration

In order to correctly handle cache-busted links with built-in DocPad server, you need to update your docpad.coffee config: add serverAfter event to docpadConfig.

docpadConfig = {
    events:
        # Extend server so it can respond to cache-reset assets
        serverAfter: ({server}) ->
            server.get /^\/\d+\/(c|j)\//, (req, res, next) ->
                req.url = req.url.replace /^\/\d+\//, '/'
                next()
}

module.exports = docpadConfig

A real-world example is available in Emmet Documentation web-site source.

Published

Vulnerabilities

Links

Maintainers

Keywords