Learn about DokuWiki
Learn about DokuWiki
This is an old revision of the document!
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.
The plugin adds a new button to the editor toolbar. The button 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.
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 (see caching). You will also have to reset your browser cache.
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:
This version is not kept up-to-date.
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:
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.
Clicking on the snippets' icon 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 meta file for each page containing snippets keeps a record of each snippet and its timestamp.
There are two ways that snippets are updated:
For more details about the snippets plugin internals, see snippets_backend.
On the Administration Page, there is a tool which enables you to reconcile any differences between the information in the database and the content on the wiki pages. You will find it listed under “AdditionalPlugins”. This will be particularly useful if you remove snippets from your pages.
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, the dummy page must be listed as a snippet. When this page is selected, the template data will be inserted in its place and any content on it will be ignored.
templas its ending. That means that you can have a directory with the form
something_templ. Then a namespace template and a dummy file can be placed in this directory, and the dummy file will be used as described in (1) above.
In both cases the dummy file is used as the link in the snippets listing and when the link is clicked, the snippet is inserted into your page. There is one circumstance in which the contents of a dummy page is not ignored. This is where you activate the useheadings option, in which case the first heading will be used as the name of the link, if no other name is set in the link markup.
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]] [[:personal:templ_page]]
[[:personal:templ_page]], we will assume that useheadings is active and its first heading is
personal data. This will result in the following list of links:
admin data policies distro data personal data
admin datawould access the dummy page
templ_adminin the root namespace directory using the namespace template found in that directory.
policieswould access the dummy page
templdirectory using the namespace template found in that directory
distro datawould access the dummy
startpage in the
distro_templdirectory using the namespace template found in that directory
persona datalwould access the dummy
The dummy pages themselves are not changed. 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,
|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||
|old_revisions||Insert current version of snippet into Old Revisions||
|prettytitles||Replace underscores with spaces in replacements for PAGE macros||
|userreplace||Replace user defined macros||
|skip_unset_macros||Delete macros from output when they have no values||
|default_macro_string||A user-defined default macro string for the User Macros & replacements textbox.||@macro1@,val1;@macro2@,val2;. . .|
userreplace: When this is set to
true there will be an additional textbox with the following label: User Macros & replacements . In this textbox the user can define one or more macros and their replacements. The format for this is:
@macro_1,value_1;macro_2, value_2;macro_3. . .
When these macros are found in the template, they will be replaced by their replacement values. If a user-defined
default_macro_string is not set, then the following placeholder string will appear in the textbox:
@macro1@,val1;@macro2@,val2;. . .
skip_unset_macros: If this option is set to true, any macros left on the page after processing will be removed.
old_revisions: This is the default value for determining how to handle snippets when you load an
Old Revision into the editor. If true, any snippets found in an old revision will be replaced by the current versions; if false, the older snippets will remain in place. But this is modifiable from the Old Revisions/Snippets interface that appears upon loading an old Revision into the browser. This interface makes it possible to decide on a case by case basis whether to recover a previous version of the page in its entirety, including the old version of the snippet, or else to update the page with the current snippets. 1). This is the interface message:
This is an old revision of the document. It contains one or more snippets which may be outdated. Replace outdated snippets in this Old Revision? Yes No
old_revisionssetting determined the outcome for all instances, that is, either in all cases the newer snippet was installed, or the old one was left.