mturner.org

Snippets Updatable Plugin

This plugin is an update to the snippets plugin by Michael Klier, which was later adopted by Dominik Eckelmann, who upgraded the Javascript to jQuery and made some css style improvements. This current upgrade adds a tracking layer to the plugin so that if a snippet is embedded in multiple pages and that snippet is changed, the user can choose to have the revised snippet automatically embedded in all of the pages in which it appears. It also enables using namespace templates for snippet insertions.

The user decides when inserting the snippet whether or not to track revisions. In addition to the checkbox for keeping the window open, there is now a checkbox to check for updates to the snippet:

By default the box is checked. This can be changed in the Configuration Settings. When the updateable box is checked, the plugin is wrapped in a header and a footer which indicate that this instance of the snippet should be tracked and updated in the current page whenever the snippet is updated.

The header markup looks like this: ~~SNIPPET_O1423002180~~snippet_1~~, where the embedded number is the timestamp for when the snippet was embedded in the page. This changes every time the snippet is updated. The footer looks llike this: ~~SNIPPET_C~~snippet_1~~.

If a snippet is not marked for updating, then it will not change when the snippet is revised but will be a permanent part of the page. This means that the same snippet can be used for both a permanent part of one page and a mutating part of another.

Namespace templates can be used as snippets. There are two ways to do this:

1. First, a standard namespace template must be in included in the namespace directory. In addition an empty page file beginning with templ_ must be included in the directory. When creating the listing of snippets, this empty page must be listed as a snippet. When this empty page is selected, the template data will be inserted in its place.
2. A directory can be created with the name templ. Then a namespace template and an empty file can be placed in this directory which will be used as described in (1) above. This directory can also be hidden using the hidepages option by excluding files with this templ:.

These snippets cannot be updatable. The hidepages option can be used to exclude both pages beginning with templ_ and the templ directory with the following expression templ:|templ_ in the hidepages field.

1. When a page with a revised snippet is opened, it will automatically be updated to the revised snippet. In addition the database ¹⁾ will be updated when the page is saved.
2. When a snippet is revised, a table will appear at the bottom of its page with a listing of the pages that have used the snippet. Each page name is a link that, when clicked, will update the snippet (and any other snippets) in the page named in the link. In addition, unused page ids assigned to the snnippet will be pruned from the database ²⁾ and the metafile for the page will be updated, unless the checkbox is un-checked.

The plugin keeps track of its updatable snippets in a meta file consisting of a serialized multi-dimensional array and in the meta files created by Dokluwiki for each of its pages. The plugin's meta file is found in the meta directory: data/meta/snippets_upd.ser. Its structure is as follows:

• $snip: an array of page ids of updatable snippets which have been inserted into pages. Each snippet id is an array of the pages into which it has been inserted:
  • $page_id[0] . . .$page_id[n]
• $doc: an array of ids of the pages into which updatable snippets have been inserted. Each id is in turn an array of the snippet names which have been inserted into that page:
  • $snippet_id[0] . . .$snippet_id[n]

This scheme is illustrated diagramatically below.

The page metafiles keep lists of inserted snippets and their timestamps. Before inserting a snippet into a page, the timestamp of the snippet is checked against the snippet's timestamp held in the metafile. If they are the same, then the snippet has already been inserted and the plugin knows not to re-insert it.

Array
(
    [snip] => Array (
            [snippet_1] => Array
                (
                    [0] => ns:page_id
                    [1] => ns:page_id
                     .
                     .
                )
            [snippet_2] => Array  ( ) . . .. . .[snippet_<n>] => Array( )
        )
    [doc] => Array (
            [ns:id] => Array
                (
                    [0] => snippet_1
                    [1] => snippet_2
                     .
                     .
                )
            [ns:id] => Array (  ) . . .[ns:id] => Array( )
        )