# snippets plugin

---- plugin ----
description: Adds a button to the editor toolbar which allows to easily insert templates while editing a page.
author     : Myron Turner
email      : turnermm02@shaw.ca
type       : Action, Syntax
lastupdate : 2014-05-28
compatible : 2009-12-25, 2010-11-07, 2011-05-25, angua, 2012-09-10,hrun
depends    :
conflicts  : cryptsign
similar    :
tags       : editing, template, toolbar
bugtracker : https://github.com/cosmocode/dokuwiki-plugin-snippets/issues
sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-snippets/
----

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

## Description

The snippets plugin makes it possible to create a collection of re-usable texts that can be inserted into the current page at the current cursor position. These are the snippets. Each snippet is created on its own page and can in fact contain just about anything that the current wiki supports.

As originally described:
This plugin adds a new button to the editor toolbar. When clicked it opens a popup displaying a list of pages which can be previewed and inserted into the editor window. The list of pages is defined using a Wiki page which contains a simple unordered list of links to these pages.

In the plugin's original form, once a snippet was embedded in a page, it 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 user can choose to have the revised snippet automatically embedded in all of the pages in which it appears.

In addition, this upgrade allows the use of Dokuwiki namespace templates to be used as snippet pages.

## Installation

Download and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually. The original snippets plugin can be downloaded here: dokuwiki-plugin-snippets.tgz

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

## 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 pages and then add them as an the 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. 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.

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

<snippet>

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

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