Differences

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

--- plugin:instructions [2020-01-23 14:58] – [Wiki-Syntax] juergen_aus_zuendorf
+++ plugin:instructions [2022-04-20 17:29] (current) – [Wiki-Syntax] juergen-aus-zuendorf
@@ Line 2: / Line 2: @@
 ---- plugin ----
-description: Provides a highly customizable, standardised instruction
+description: Provides highly customizable, standardized instructions
 author     : Juergen_aus_Zuendorf
 email      : H-J-Schuemmer@Web.de
 type       : syntax
-lastupdate : 2020-01-16
+lastupdate : 2022-04-20
-compatible : Frusterick Manners, Greebo
+compatible : Hogfather, Greebo, Frusterick Manners
 depends    :
 conflicts  :
-similar    : textinsert
+similar    : textinsert, wrap
 tags       : formatting, macro, replace
 downloadurl: https://github.com/Juergen-aus-Koeln/dokuwiki-plugin-instructions/archive/master.zip
 bugtracker : https://github.com/Juergen-aus-Koeln/dokuwiki-plugin-instructions/issues
-sourcerepo : # eg. http://github.com/juergen_aus_zuendorf/dokuwiki-plugin-instructions/
+sourcerepo : https://github.com/Juergen-aus-Koeln/dokuwiki-plugin-instructions/
 donationurl:
@@ Line 30: / Line 30: @@
 In combination with a special template, this code generates a print preview button:
-  ~~INSTR~~cms_preview~~|-mynamespace:mypage_for_preview~~
+  ~~INSTR~~cms_preview~~|-mynamespace:mypage_for_preview~~END~~
 {{https://raw.githubusercontent.com/Juergen-aus-Koeln/dokuwiki-plugin-instructions/master/plugin_instructions_05.png}}
@@ Line 57: / Line 57: @@
 ==== Wiki-Syntax ====
-First the syntax within the wiki page:\\
+First the syntax within the wiki page: ((There is an alternative, old syntax:\\
+''%%{{INSTR<[template]>|-[parameter 1]|-[parameter n]}}%%''\\
+But this might be deleted in future releases because there are problems using this syntax in combination with the ckgedit plugin.))\\
 <code>
@@ Line 68: / Line 70: @@
 </code>
-//or the same in one line://((This syntax has some problems when using the plugin ckgedit. Therefore you can also use the syntax \\
+//or the same in one line://
-''%%~~INSTR~~[template]~~|-[parameter 1]|-[parameter n]~~END~~%%''))
-  {{INSTR<[template]>|-[parameter 1]|- ... |-[parameter n]}}
+  ~~INSTR~~[template]~~|-[parameter 1]|- ... |-[parameter n]~~END~~
@@ Line 80: / Line 81: @@
 c) The listed parameters can be normal text. Each parameter is defined in one line that is prefixed by ''|-''.
-In addition there are some special markups (does not work within words):
+In addition there are some special markups (does only work for whole words):
-  * Marking text with wiki syntax as **bold**, //italic//, __underline__ or ''code'' is accepted.
+  * Marking text with wiki syntax as **bold**, //italic// or ''code'' is accepted. ((Underline is often used in "normal" text so the wiki syntax would unexpectedly change this if supported by this plugin.))
   * Two spaces are interpreted as indentation or gap.
   * Wiki-Links are understood with this syntax: ''%%[[namespace:page#section|description]]%%'' (description is necessary).
-  * If you want to have a line break within one parameter you can achieve this by inserting a new line prefixed by ''|+''.
+  * If you want to have a line break within one parameter, you can achieve this by inserting a new line prefixed by ''|+''.
+If the template (see below) supports more parameter as from the requesting page shall be passed, the supernumerary parameters will remain empty in the output.
 ==== Template ====
-To work correctly you have to define a template. This is built as html-text and defines the look of the instruction.
+To work correctly, you have to define a template. This is built as HTML-text and defines the look of the instruction. If necessary, the HTML-text may contain JavaScript code.
 a) The first line in the template file has to be the code "%%<html>%%", followed by an optional short description (not more than one line).
-b) After this the file contains all parameters that should be processed within the wiki page. When a parameter shall be inserted in the html content just insert a new line and write "param-1" (or "param-2" and so on).
+b) After this, the file contains all parameters that should be processed within the wiki page. When a parameter shall be inserted in the HTML content, just insert a new line and write "param-1" (or "param-2" and so on).
-c) At the end of the html file you have to append a line with the code "</%%html%%>". With the tags <%%html%%> and </%%html%%> at the beginning and the end you can test the content in a normal wiki testing page.
-The template has to be placed in a subfolder to ".../lib/plugins/instructions/tpl". The subfolder name will be the name of the template. The html file name in that folder is "html.txt". Besides this you can provide images in this folder which can be adressed by your html code with "lib/plugins/instructions/tpl/your_template/image_file"
+c) At the end of the HTML file, you have to append a line with the code "</%%html%%>". With the tags <%%html%%> and </%%html%%> at the beginning and the end, you can test the content in a normal wiki testing page.
+The template has to be placed in a subfolder to ".../lib/plugins/instructions/tpl". The subfolder name will be the name of the template. The HTML file name in that folder is "html.txt". Besides this you can provide images in this folder which can be addressed by your HTML code with "lib/plugins/instructions/tpl/your_template/image_file"
+//Note://\\
+If a parameter is passed empty, a subsequent line feed defined in the template (marked with "<br>") will be suppressed.
 ==== Placeholders ====
 In addition you can use some placeholders in the wiki page:
-| ''@PAGE@''          | page name                          |
+| ''@PAGE@''          | page name                                       |
-| ''@ID@''            | ID of the page                     |
+| ''@ID@''            | ID of the page                                  |
-| ''@NS@''            | namespace of the page              |
+| ''@NS@''            | namespace of the page                           |
-| ''@CURNS@''         | current sub-namespace              |
+| ''@CURNS@''         | current sub-namespace                           |
-| ''%%@URL_DOKU@%%''  | base URL of the wiki installation  |
+| ''@NSMAIN@''        | namespace of main page when using in a sidebar  |
-| ''%%@URL_PAGE@%%''  | complete URL of the current page   |
+| ''%%@URL_DOKU@%%''  | base URL of the wiki installation               |
+| ''%%@URL_PAGE@%%''  | complete URL of the current page                |
 //Example://
@@ Line 196: / Line 199: @@
 === Change Log ===
+  * **2022-04-20**: Better support for empty parameters
+  * **2022-03-25**: New parameter @NSMAIN@
   * **2020-01-16**: Support for plugin CKGEdit with a new syntax
   * **2019-11-15**: Syntax for placeholders added