DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:instructions

instructions Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Provides highly customizable, standardized instructions

Last updated on
2022-04-20
Provides
Syntax
Repository
Source

Similar to textinsert, wrap

Tagged with formatting, macro, replace

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Examples/Usage

In combination with a special template, this code generates a print preview button:

~~INSTR~~cms_preview~~|-mynamespace:mypage_for_preview~~END~~

Or with this code:

~~INSTR~~warning~~
|- Warning
|- Title of the warning
|- Description of the warning
|- Therefore:
|- • make this
|+ • and perhaps this
|+ • and some more things
~~END~~

… the result with a certain template could be like this simple hint:

Syntax

Wiki-Syntax

First the syntax within the wiki page: 1)

~~INSTR~~[template]~~
|- [parameter 1]
|- [parameter 2a]
|+ [parameter 2b]
|- [parameter n]
~~END~~

or the same in one line:

~~INSTR~~[template]~~|-[parameter 1]|- ... |-[parameter n]~~END~~

a) The leading syntax tag is INSTR.

b) After this you have to reference to a specific template (see later)

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 only work for whole words):

  • Marking text with wiki syntax as bold, italic or code is accepted. 2)
  • 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 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. 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).

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
@ID@ ID of the page
@NS@ namespace of the page
@CURNS@ current sub-namespace
@NSMAIN@ namespace of main page when using in a sidebar
@URL_DOKU@ base URL of the wiki installation
@URL_PAGE@ complete URL of the current page

Example:

~~INSTR~~my_template~~
|- @ID@
|- @PAGE@
|- @NS@
|- @CURNS@
|- @URL_DOKU@
|- @URL_PAGE@
~~END~~

Examples

Example "Warning"

Here is an example with 5 parameters (screenshot see above):

Code:

~~INSTR~~warning~~
|- Warning
|- Title of the warning
|- Description of the warning
|- Therefore:
|- • make this
|+ • and perhaps this
|+ • and some more things
~~END~~

Template:

<html> WARNING
<table style="width:100%;"> <tbody> <tr> <td style="width:130px; text-align:center; padding:0px; border-left:none; border-bottom:none; border-top:none;"> <img src="lib/plugins/instructions/tpl/warning/symbol.png" alt="" width="35"> </td> <td style="background-color:#E6E6FA; font-size:16pt; text-transform:uppercase; color:black; vertical-align:middle; padding:0px 5px;"> 
<strong>
param-1
</strong> </td> </tr> 
<tr> <td rowspan="5" style="border-left:none; border-top:none;"> </td> <td> <span style="font-size: large;"> 07 <strong>
param-2
</strong> </span> 
<br>
param-3
</td> </tr> 
<tr> <td style="border-bottom:3px inset lightgrey;"> <em>
param-4
</em> 
<br> 
param-5
</td> </tr> 
</tbody> </table>
</html>

This code is placed here: “lib/plugins/instructions/tpl/warning/html.txt”, and in addition there is an image in the same folder: “lib/plugins/instructions/tpl/warning/symbol.png”.

Example "Immediate print"

The next example shows a code without parameters to print out a page in the moment it is opened:

Syntax:

{{INSTR<immediate_print>}}

Template:

<html> immediate_print
<script type="text/javascript">
<!--
window.onload = function() {
  window.print()
}
-->
</script>
</html>

Development

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
  • 2019-10-19: Initial release

Known Bugs and Issues

ToDo/Wish List

FAQ

Discussion

1)
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.
2)
Underline is often used in “normal” text so the wiki syntax would unexpectedly change this if supported by this plugin.
plugin/instructions.txt · Last modified: 2022-04-20 17:29 by juergen-aus-zuendorf

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki