DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:snippets

Snippets Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" unknown
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes

plugin Adds a button to the editor toolbar which enables easy insertion of (updatable) snippets while editing a page

Last updated on
2017-02-19
Provides
Syntax, Action
Repository
Source
Conflicts with
cryptsign, move

Similar to custombuttons, snippeter

Tagged with editing, template, toolbar

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.

Description

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.

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

Installation

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.

PHP versions prior to 5.3

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:
https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/pre_53.zip

Internet Explorer

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:

Configuration Options

There are two options:

OptionDescriptionDefault
snippets_pagethe wiki page which defines the list of snippet pages used in the snippet managersnippets
snips_updatableif true, snippets are automatically updatable, otherwise updatable at the user's discretiontrue

Usage

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~~.

snippet_1 is the Dokuwiki id of the snippet.

How the updates are processed

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:

  1. When a page with a revised snippet is opened for revision, the revised snippet will automatically replace the old version in the editing window. For the change to become permanent, the page must be 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. When clicked, it 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.

Inserting Comments into Snippets

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 as Snippets

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]]  

This will result in the following list of links:

admin data
policies
distro data
  1. admin data would access the empty page templ_admin in the root namespace directory using the namespace template found in that directory.
  2. policies would access the empty page policies in the templ directory using the namespace template found in that directory
  3. distro data would access the empty start page in the distro_templ directory 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: templ:|templ_.

Replacement Patterns

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

@ID@#ID#
@NS@#NS#
@FILE@#FILE#
@!FILE@#!FILE#
@!FILE!@#!FILE!#
@PAGE@#PAGE#
@!PAGE@#!PAGE#
@!!PAGE@#!!PAGE#
@!PAGE!@#!PAGE!#

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

Change Log

Discussion

plugin/snippets.txt · Last modified: 2017-02-19 15:43 by 24.78.92.72