DokuWiki

This is an old revision of the document!

====== Snippets Plugin ====== —- plugin —- description: Adds a button to the editor toolbar which enables easy insertion of (updatable) snippets while editing a page author : Myron Turner email : turnermm02@shaw.ca type : Action, Syntax lastupdate : 2017-10-20 compatible : 2009-12-25, 2010-11-07, 2011-05-25, Angua, Weatherwax, Binky, Ponder Stibbons, Hrun,detritus, “Elenor Of Tsort”,“Frusterick Manners” depends : conflicts : cryptsign, move similar : custombuttons, snippeter tags : editing, toolbar, shortcut 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 donationurl: http://mturner.org/userfiles/donate.php —- 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.
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. 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 (see caching). You will also have to reset your browser cache. ==== 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
This version is not kept up-to-date. ==== 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: * https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/jq-fix.zip ===== 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. 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. 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 meta file for each page containing snippets keeps a record of each snippet and its timestamp. There are two ways that snippets are updated: - 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. - 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. For more details about the snippets plugin internals, see snippets_backend. ==== Admin: Metadata Clean-Up Tool ==== 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. ===== 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 ===== ==== Creating Links to Namespace Templates ==== Namespace templates can be used as snippets. There are two ways to do this: - A standard namespace template is in included in a directory. In addition a dummy page beginning with 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. - 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 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]] 

For [[: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 data would access the dummy page templ_admin in the root namespace directory using the namespace template found in that directory. - policies would access the dummy page policies in the templ directory using the namespace template found in that directory - distro data would access the dummy start page in the distro_templ directory using the namespace template found in that directory - persona datal would access the dummy templ_page in the personal directory. 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: 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. ===== Configuration Options ===== ^ Option ^ Description ^ Default ^ |snippets_page|the wiki page which defines the list of snippet pages used in the snippet manager|snippets| |snips_updatable|if true, snippets are automatically updatable, otherwise updatable at the user's discretion|true| |old_revisions| Insert current version of snippet into Old Revisions|true| ^ Template Options ^|| | prettytitles | Replace underscores with spaces in replacements for PAGE macros | false | | userreplace | Replace user defined macros | true | | skip_unset_macros | Delete macros from output when they have no values | false | | default_macro_string | A user-defined default macro string for the User Macros & replacements textbox. |@macro1@,val1;@macro2@,val2;. . . | ===== Notes on Options ===== 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. ¹⁾. 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 ===== Change Log =====

• Updates version (2022-10-07 17:16)
• Merge pull request #46 from turnermm/php8.0 (2022-10-07 17:11)
• Updates action.php, replacing create_function with function() at l. 100 (2022-03-27 18:58)
• Merge pull request #39 from dokuwiki-translate/lang_update_105_159569… (2020-07-25 23:10)
• translation update (2020-07-25 17:20)
• converted php assignment to string in en/lang.php at l. 35 (2020-04-24 15:21)
• synched version with dokuwiki.org (2020-03-07 15:18)
• added title to snippets icon (2019-11-30 18:11)
• updates info.txt (2019-11-28 23:05)
• Merge pull request #38 from turnermm/toolbar_rev (2019-11-27 21:10)
• updates lang/en (2019-11-27 21:01)
• moved toolbar to script.js (2019-11-27 19:42)

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