nick.recoil.org

Introduction

A simple Mephisto plugin to enumerate the contents of a directory that match a shell glob pattern, sort the results, and give you back one or more entries.

This was written to allow me to simplify the release process for new versions of code on the DSVideo website. The code on that site is made available via a directory in public/, with the files named '<package name>-<version>.<archive method>'. ie/ dsvideo-v1.0.zip

The plugin scans that directory according to a shell glob pattern, and gives you the last values from that list in such a way to allow easy link generation. This means that to release a new version, all we have to do is place the new package in the 'public/releases' directory and regenerate the cached pages.

The shell glob pattern can either be contained within the liquid templates, or passed into the plugin using a special tag you can use in your article. This is of the form __dfl:<shell glob expression>. This is much like Flickr’s ‘machine tags’, which aren’t ment to be useful to the end user, but impart some meaning to be processed by a computer.

Arguments

The following arguments are valid:

glob

An explicit shell glob pattern to match files against. e.g. 'releases/*.zip'

tags

The tags you wish the plugin to scan for the machine tag '__dfl:', which is another way of specifying the shell glob expression. e.g. 'article.tags'.

max

Maximum files to return via the block, counted back from the end of the sorted array. ‘0’ for unlimited. (Default is ‘1’)

order

Order in which to report back the files. Can be either ‘asc’ or ‘desc’. (Default is ‘asc’)

Examples

There are two ways to pass in the glob expression to the plugin. Via explicit definition in the liquid template, or by using a special tag in your article.

Dynamic linking with liquid templates

the public/releases/ directory contains:

  dsvideo-player-0.9.zip
  dsvideo-player-1.0.zip
  dsvideo-player-1.1b1.zip
  dsvideo-encoder-1.0.zip

In our download.liquid page template, we could have:

1
2
3
4
5
6
7
8
9
10

  <h3>Latest downloads</h3>

  {% dynamicfilelink glob: releases/dsvideo-player*.zip as file %}
    <a href="{{file.path}}">DSVideo player version {{file.version}}</a>
  {% enddynamicfilelink %}

  {% dynamicfilelink glob: releases/dsvideo-encoder*.zip as file %}
    <a href="{{file.path}}">DSVideo encoder version {{file.version}}</a>
  {% enddynamicfilelink %}

It would give us:

1
2
3
4

  <h3>Latest downloads</h3>
  <a href="/releases/dsvideo-player-1.1b1.zip">DSVideo player version 1.1b1</a>
  <a href="/releases/dsvideo-player-1.0.zip">DSVideo encoder version 1.0</a>

Or for a list of the last 5 versions given in descending order, we could use:

1
2

  {% dynamicfilelink directory: releases, glob: releases/dsvideo-player-*, max: 5, order: desc as file %}

Or to link to the latest beta release:

1
2

  {% dynamicfilelink directory: releases, glob: releases/dsvideo-player-*b* as file %}

Dynamic linking with article tags

If you tagged the page with '__dfl:releases/dsvideo-encoder*.zip', and your download page template contained the following:

1
2
3
4

 {% dynamicfilelink tags: article.tags as file %}
  <a href="{{ file.path }}">Download version {{ file.version }}</a>
 {% enddynamicfilelink %}

You would get the following HTML:

1
2

  <a href="/releases/dsvideo-encoder-1.0.zip">Download version 1.0</a>

You are only limited by what you can express by Dir#glob. This could be changed to a regular expression if more power is needed. If you also need to differentiate between beta and regular releases, and shell globbing can’t help with the differentiation, your files could be in separate directories.