{{static-hash-url:foo.css}}

The {{static-hash-url:foo.css}} parameter copies the referenced file to a new file, and evaluates to the URL path of the newly-created file. The name of the new file is an MD5 hash of the contents of the file. This ensures that the file name will change whenever the contents of the file change.

When this parameter is used, Uriel verifies that the referenced file actually exists when building the web site, and will exit with an error if the file is not found.

This means that if you use this parameter every time you reference static content on your site (that needs dynamic hashed filenames), all of your links and references within your site are guaranteed to work.

If used consistently, this means you will never have any broken links within your site, because they will become build errors instead of broken links. That way you can detect and fix them immediately.

For most links and references on your site, the {{static-url:foo.jpg}} is a better choice. The {{static-hash-url:/css/main.css}} is primarily useful for referencing CSS and JavaScript content, where you need to force the browser to reload those files when the contents change.

Typical Usage

The {{static-hash-url:foo.css}} parameter is most useful when referencing CSS and JavaScript files, where you need to force the browser to download new versions of those files when the contents change.

For example, here the {{static-hash-url:/css/main.css}} parameter is wrapped inside of a tag that references the /css/main.css CSS file in the rvalue portion of the parameter. The HTML looks like this:

<link rel="stylesheet"
      type="text/css"
      href="{{static-hash-url:/css/main.css}}">

When the site is built, this evaluates to:

<link rel="stylesheet"
      type="text/css"
      href="/css/bce096b30da10f51c90533986e9c1762.css">

If the /css/main.css file is not present, then Uriel will generate an error like this when it tries to build the web site:

copying 'static' to 'public', overwriting previous contents
initializing soju
initializing handlers
reading node files
rendering node content
parameter error:
  nodes/parameters/static-hash-url
    templates/default.html
      nodes/parameters/static-hash-url
        '{{static-hash-url:/css/main.css}}'
uriel: file not found: '/css/main.css'

File Paths

When Uriel builds your web site, it copies files from the static directory into the public directory. Anything that is present in the static directory will wind up on your web site, and can be referenced by the {{static-hash-url:foo.css}} parameter.

File paths in the rvalue portion of the {{static-hash-url:foo.css}} parameter can either be local to where the node will be published, or the paths can start with a slash, relative to the root of the site. Directory traversal with ../ is not allowed.

Absolute Path Example

Here is an example of using the {{static-hash-url:/css/main.css}} parameter with /css/main.css as the rvalue component:

/css/bce096b30da10f51c90533986e9c1762.css

This works because:

• static/css/main.css exists
• Uriel copies static/css/main.css to public/css/main.css
• /css/main.css is found at public/css/main.css
• Uriel copies public/css/main.css to public/css/bce096b30da10f51c90533986e9c1762.css

Relative Path Example

Here is an example of using the {{static-hash-url:local.css}} parameter with local.css as the rvalue component:

67d51b872c106b102703dfb4fae4a3c7.css

This works because:

• static/parameters/static-hash-url/local.css exists
• Uriel copies static/parameters/static-hash-url/local.css to public/parameters/static-hash-url/local.css
• The nodes/parameters/static-hash-url node is published to public/parameters/static-hash-url/index.html
• The published index.html and local.css files are both in the same directory
• Uriel copies public/parameters/static-hash-url/local.css to public/parameters/static-hash-url/67d51b872c106b102703dfb4fae4a3c7.css

{{static-url:foo.jpg}} vs. {{static-hash-url:foo.css}}

The {{static-url:foo.jpg}} parameter evaluates to the URL path of the file referenced in the rvalue portion of the parameter.

The {{static-hash-url:foo.css}} parameter copies the referenced file to a new file name, and then evaluates to the URL path for the newly-created file.

{{static-url:foo.jpg}} is better for things like images and links to downloadable content, where you don't want the file name to change.

{{static-hash-url:foo.css}} is often better for references to things like CSS and JavaScript files, where you need to ensure that the browser loads the newest version of the file whenever it changes.

Tags: parameters, static