Learn about DokuWiki
Learn about DokuWiki
Compatible with DokuWiki
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.
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.
In addition, this upgrade accepts DokuWiki namespace templates as snippets.
IMPORTANT: You have to invalidate/delete the cache before the new button appears in the toolbar.
If you are using a version of PHP prior to 5.3 you will get an error message that looks something like this:
unexpected T_FUNCTION in . . ./lib/plugins/snippets/helper.php on line 148
In this case download an alternative package, which supports earlier versions of PHP:
An issue with IE 11 has been detected where the snippets' buttons do not display, making the plugin unusable. The following version of
snippets appears to address this issue:
|snippets_page||the wiki page which defines the list of snippet pages used in the snippet manager||
|snips_updatable||if true, snippets are automatically updatable, otherwise updatable at the user's discretion||
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.
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_1 is the Dokuwiki
id of the snippet.
The plugin keeps a database that records the associations 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.
There are two ways that snippets are updated:
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:
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.
templas its ending. That means that you can have a directory with the form
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]]
This will result in the following list of links:
admin data policies distro data
admin datawould access the empty page
templ_adminin the root namespace directory using the namespace template found in that directory.
policieswould access the empty page
templdirectory using the namespace template found in that directory
distro datawould access the empty
startpage in the
distro_templdirectory using the namespace template found in that directory
The empty pages themselves are not changed but remain empty. They are just placeholders.
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:
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,