DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:snippets

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Both sides next revision
plugin:snippets [2017-11-26 14:23]
Aleksandr old revision restored (2017-11-10 07:14)
plugin:snippets [2020-11-17 18:42] (current)
turnermm [Snippets Plugin]
Line 6: Line 6:
 email      : turnermm02@shaw.ca email      : turnermm02@shaw.ca
 type       : Action, Syntax type       : Action, Syntax
-lastupdate : 2017-10-20 +lastupdate : 2020-03-07 
-compatible : 2009-12-25, 2010-11-07, 2011-05-25, Angua, Weatherwax, Binky, Ponder Stibbons, Hrun,detritus"Elenor Of Tsort","Frusterick Manners"+compatible : 2009-12-25, 2010-11-07, 2011-05-25, Angua, Weatherwax, Binky, Ponder Stibbons, Hrun, Detritus, Elenor Of Tsort, Frusterick Manners, Greebo,hogfather
 depends    : depends    :
 conflicts  : cryptsign, move conflicts  : cryptsign, move
-similar    : custombuttons, snippeter +similar    : custombuttons, snippeter, scrapbook 
-tags       : editing, toolbar, shortcut+tags       : editing, toolbar, shortcut, snippets 
 downloadurl: https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/master.zip downloadurl: https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/master.zip
 bugtracker : https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/issues bugtracker : https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/issues
Line 24: Line 25:
 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 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 plugin adds a new button to the editor toolbar.
-{{  http://mturner.org/userfiles/doku/icon_zpsykhjbol2.png  }}+{{ https://i.imgur.com/gJoyby4.png?recache }}
 The button opens a pop-up window that lists the snippet pages. The list is defined on a standard [[#there_are_two_options|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. The button opens a pop-up window that lists the snippet pages. The list is defined on a standard [[#there_are_two_options|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 ** \\+**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 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. In addition, this upgrade accepts DokuWiki namespace templates as snippets.
Line 36: Line 35:
 ===== Installation ===== ===== Installation =====
  
-Download and install the plugin using the [[:plugin:plugin|Extension Manager]]. Refer to [[:plugins|Plugins]] on how to install plugins manually.  For the original snippets page with comments and download url, see [[plugin:snippets:original|snippets:original]].+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
  
-**IMPORTANT:**  You have to invalidate/delete the cache before the new button appears in the toolbar (see [[https://www.dokuwiki.org/caching|caching]]). You will also have to reset your browser cache.+For the original snippets page with comments and download url, see [[plugin:snippets:original|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 ==== ==== PHP versions prior to 5.3 ====
Line 44: Line 45:
 If you are  using a version of PHP prior to 5.3 you will get an error message that looks something like this: 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     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:\\ +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  \\ +\\ https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/pre_53.zip 
-This version is not kept up-to-date.+\\ This version is not kept up-to-date.
  
 ==== Internet Explorer ==== ==== 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:  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   * https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/archive/jq-fix.zip
- 
  
 ===== Usage ===== ===== Usage =====
 +
 Create your snippets and then add them as an unordered list of links to the ''snippets_page'', which is defined in [[#configuration_options|the configuration manager]] and defaults to ''snippets''  These are standard Dokuwiki internal links.  Create your snippets and then add them as an unordered list of links to the ''snippets_page'', which is defined in [[#configuration_options|the configuration manager]] and defaults to ''snippets''  These are standard Dokuwiki internal links. 
 <code> <code>
-   * [[snippet_1|]] +  * [[snippet_1|]] 
-   * [[snippet_2|General Instructions]] +  * [[snippet_2|General Instructions]] 
-   * [[snippet_3|Valid Users]]+  * [[snippet_3|Valid Users]]
 </code> </code>
 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|namespace templates as snippets]]. 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|namespace templates as snippets]].
Line 64: Line 66:
 Clicking on the snippets' icon will open the snippets pop-up window: Clicking on the snippets' icon will open the snippets pop-up window:
  
-{{ http://mturner.org/userfiles/doku/snippets_manager_zpsixqil7lw.png?640 }}+{{ https://i.imgur.com/WBr7rY4.png?640&recache }}
  
 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. 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.
Line 72: Line 74:
 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. 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.+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 ===== ===== 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. 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: 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 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. \\   {{  http://mturner.org/userfiles/doku/update_table3_zps4qzf2gsi.png?450  }} \\  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.  +  - 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. \\  {{ https://i.imgur.com/fcIrhog.png?450&recache }}\\  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 [[plugin:snippets:snippets_backend]]. For more details about the snippets plugin internals, see [[plugin:snippets:snippets_backend]].
  
 ==== Admin: Metadata Clean-Up Tool ==== ==== 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. 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 ===== ===== Inserting Comments into Snippets =====
Line 100: Line 102:
 </snippet> </snippet>
 </code> </code>
- 
  
 ===== Namespace Templates as Snippets ===== ===== Namespace Templates as Snippets =====
Line 107: Line 108:
  
 Namespace templates can be used as snippets.  There are two ways to do this: 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. +  - 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. +  - 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 [[:config: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. 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 [[:config: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 [[#there_are_two_options|snippets_page]]: +The following is a schematic for entering these snippets into the links on the [[#there_are_two_options|snippets_page]]:
 <code> <code>
 [[templ_admin|admin data]] [[templ_admin|admin data]]
Line 130: Line 131:
   - ''policies'' would access the dummy page ''policies'' in the ''templ'' 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   - ''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.+  - ''personal data'' would access the dummy ''templ_page'' in the ''personal'' directory.
  
 The dummy pages themselves are not changed.  They are just placeholders. The dummy pages themselves are not changed.  They are just placeholders.
Line 137: Line 138:
  
 ==== Replacement Patterns ==== ==== Replacement Patterns ====
 +
 Any replacement patterns that refer to page names, files and Dokuwiki ID's must have their ''@'' characters changed to ''#'' characters, as follows: Any replacement patterns that refer to page names, files and Dokuwiki ID's must have their ''@'' characters changed to ''#'' characters, as follows:
  
Line 150: Line 152:
  
 The other replacement patterns remain the same, ''@USER@'','' @DATE@'', etc. The other replacement patterns remain the same, ''@USER@'','' @DATE@'', etc.
- 
  
 ===== Configuration Options ===== ===== Configuration Options =====
- 
  
 ^ Option                ^ Description                                                                            ^ Default    ^ ^ Option                ^ Description                                                                            ^ Default    ^
Line 168: Line 168:
    
 **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: **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. . .+  @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: 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;. . .+  @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. **skip_unset_macros**:  If this option is set to true, any macros left on the page after processing will be removed.
Line 178: Line 178:
   Replace outdated snippets in this Old Revision? Yes No   Replace outdated snippets in this Old Revision? Yes No
  
-     +   
-    +
 ===== Change Log ===== ===== Change Log =====
 +
 {{rss>https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/commits/master.atom date count=12}} {{rss>https://github.com/turnermm/Updatable-Snippets-for-Dokuwiki/commits/master.atom date count=12}}
  
plugin/snippets.1511702612.txt.gz · Last modified: 2017-11-26 14:23 by Aleksandr