---- plugin ----
description: Adds a button to the editor toolbar which enables easy insertion of snippets while editing a page.
author     : Myron Turner
email      : turnermm02@shaw.ca
type       : Action, Syntax
lastupdate : 2015-03-15
compatible : 2009-12-25, 2010-11-07, 2011-05-25, angua, Weatherwax,Binky,Ponder Stibbons,Hrun
depends    :
conflicts  : cryptsign
similar    :
tags       : editing, template, toolbar
downloadurl: https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/master.zip
bugtracker : https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/issues
sourcerepo : https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki
----

This is an upgrade to the original snippets plugin. It was created by Michael Klier and later updated by Dominik Eckelmann, who brought the javascript into conformity with jQuery and made some css improvements.

The snippets plugin makes it possible to create a collection of re-usable texts, or snippets, that can be inserted into the current page at the current cursor position. Each snippet is a standard wiki page. A new button is added to the editor toolbar. It opens a pop-up window that lists the snippet pages. The list is defined on a standard Wiki page as a simple unordered list of links to the snippets. From this pop-up the snippets can be previewed and inserted into the editor window.

Updatable Snippets
In the plugin's original form, snippets remained in the page as originally inserted even if the snippet itself was later changed. This upgrade adds a tracking layer to the plugin so that if a snippet is embedded in multiple pages and that snippet is changed, the revised snippet can be automatically updated in any of the pages in which it appears and is marked to be updated.

Note: In this current version, the updatable snippet files must be in the root Dokuwiki directory.

In addition, this upgrade accepts Dokuwiki namespace templates as snippets.

Download and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually. For the original snippets page with comments and download url, see snippets:original.

IMPORTANT: You have to invalidate/delete the cache before the new button appears in the toolbar.

Create your snippets and then add them as an unordered list of links to the snippets_page, which is defined in the configuration manager and defaults to snippets. These are standard Dokuwiki internal links.

   * [[snippet_1|]]
   * [[snippet_2|General Instructions]]
   * [[snippet_3|Valid Users]]

However, if your snippet is derived from a namespace template, then you must use a special form of link which is described below in the section on using namespace templates as snippets. Once you have created the snippets_page, simply click on the snippets toolbar icon: This will open the snippets pop-up window:

In the left-hand pane of the pop-up is the list of links derived from the snippets_page. In the right-hand pane is a preview of one of these. When there are two icons to the left of the link, clicking the left-most icon will insert the snippet into the preview pane. Clicking the right-hand icon will insert the snippet into the editing window at the current cursor location. Those links with only one icon are links to namespace template snippets. These cannot be previewed; therefore they have only the one icon which inserts the template into the editing window.

If you don't want this insertion to be updatable, uncheck the “Updatable” box. The box will remain unchecked for the remainder of the current session, unless manually re-checked.

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 number is the timestamp for when the snippet was embedded in the page. This changes every time the snippet is updated. The footer looks like this: ~~SNIPPET_C~~snippet_1~~.

The plugin keeps a database that records the relations between snippets and the pages where they are embedded; in addition the metafiles for each page containing snippets keeps a record of each snippet and its timestamp.

1. When a page with a revised snippet is accessed, 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 snippet will be pruned from the database and the metafile for the page will be updated, unless the checkbox is un-checked.

You can use the following syntax inside your snippets to provide additional comments which will get stripped out when you insert the snippet into the page you are editing.

<snippet>
Additional comments, i.e. you have to provide the following information:

  * foo
  * bar
</snippet>

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

1. A standard namespace template is in included in a directory. In addition an empty page file beginning with templ_ must be included in this 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. Alternatively, a directory can be created with the word templ as its ending. That means that you can have a directory with the form templ and/or something_templ. Then a namespace template and an empty file can be placed in this directory, and the empty file will be used as described in (1) above. The empty file is used as the link.

The following is a schematic for entering these snippets into the links on the snippets_page:

[[templ_admin|admin data]]
[[templ:policies|]]  
[[distro_templ:start|distro data]]  

These snippets are not updatable. The hidepages option can be used to exclude both pages beginning with templ_ and those using a templ directory by means of the following expression: templ:|templ_.

Any replacement patterns that refer to page names, files and Dokuwiki ID's must have their @ characters changed to # characters, as follows:

The other replacement patterns remain the same, @USER@, @DATE@, etc.

https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/issues