1MyTemplate - DokuWiki Plugin for creating complex page templates
3The plugin allows you to seperate the structure of a wiki page and the data contained within. This
4allows you to have multiple data pages referencing the same structure page. Technically, you can
5also combine several structure pages.
6I will continue to use the term "structure page" for the pages that contain dokuwiki code and
7placeholders for data and "data page" for those that contain the actual data that will be inserted
8into those placeholders. Both types of pages can be viewed when browsing the wiki.
9The structure page will be displayed as is, whereas the data page is displayed as the final
10compiled page, structure and all.
12Please note that I wrote this plugin to solve a very specific problem so some of the functionality
13may not be generally useful.
14This is also my first dokuwiki plugin and I'm not very experienced with php, so this plugin very
15possibly contains security issues and bugs. I really appreciate any feedback.
171. Declaring the structure page:
19All replacement commands look like the following:
22- The available commands are listed below.
23- "var" is optional. If set, the result of this replacement will be stored in a variable by that
24 name and can later be used again.
25- "x" is the "pass" during which the placeholder should be replaced. This will be 0 most of the
26 time, but on some occasions, you may need more control over the order in which things get
27 replaced. If you don't get the point, the list-command is a common case where using different
28 passes makes sense and it should become obvious why.
29- depending on the command specified, up to three parameters are required, separated by colons.
30 Please note that a parameter could also be another replacement command, they will be interpreted
31 inner-to-outer automatically.
32- finally, you may place a ! between the final two ~ to have MyTemplate not output anything. This
33 makes sense if you want to calculate an intermediate result to be used later.
36VAR - This is your basic placeholder replacement. Takes one parameter that will be replaced by the
37 value of the variable. (sample: ~~VAR(0):key~~)
38LOOK - This is a map lookup. You can define an array in the structure page and use a variable
39 defined in the data page as the index. see "2. Declaring data" for how to declare the map.
40 (sample: ~~LOOK(0):MAP:3~~)
41LOOKRANGE - This is similar to look, but with this command, the map doesn't have to contain the
42 exact index. The map-indices is allowed to have gaps and the index specified in
43 LOOKRANGE is rounded down to the nearest valid key.
44CALC - This allows you to do mathematical calculations based on variables or results from
45 previous commands. All math operators and most php functions should work.
46 (sample: ~~CALC(0):round(~~VAR(0):FOO~~ * ~~VAR(0):BAR~~)~~
47COUNT - counts the occurences of param1 within param2 (sample: ~~COUNT(0):,:~~VAR(0):FOO ~~ ~~)
48IF - If param1 evaluates to "true" as far as php is concerned, param2 will be printed,
49 otherwise param3 is. Please note that in this case only param2 or param3 will even be
50 evaluated, the other also doesn't get its result assigned to a variable.
51 (sample: ~~IF(0):~~VAR(0):SAYWHAT~~:what:huh~~)
52REPLACE - replaces all occurences of param2 in param1 with param3.
53 (sample: ~~REPLACE:Hello NAME:NAME:~~VAR(0):NAME~~ ~~)
54LIST - this creates a dokuwiki table from values supplied on the data page. On the data
55 page you supply a list of rows, each of which consisting of comma separated values
56 (csv). In the structure page, you can refer to each column as @1, @2, ...
57 A sample for a list would be:
59 WIKISOFTWARE = ( 'DokuWiki', '2009-12-25', 'GPL 2' ),
60 ( 'MediaWiki', '2010-04-07', 'GPL' )
61 Use in the template would then look like this:
62 ^ Name ^ Last Release ^ License ^
63 ~~LIST(0):WIKISOFTWARE:[| @0 | @1 | @2 | ]:5~~
65 As you can see, the first parameter (WIKISOFTWARE) names the list to display, the second
66 one ([ @0 | @1 | @2 | ] specifies the structure of each row. The final parameter (5) is
67 optional. If set, the table will contain at least that many rows.
68 In the above case, 3 empty lines will be appended (5 minus the 2 lines of content).
69 Of course the cells can contain further replacement commands:
70 ~~LIST(0):SOMELIST:[| @0 | ~~IF(1):@1:YES:NO~~ | ]:5~~
71 Note that if the pass of these commands is less or equal to the pass of the list-command
72 itself, they will be evaluated BEFORE the list is expanded, otherwise (like in the sample)
73 they are expanded afterwards and will thus refer to the content of the row.
74NOINCLUDE - the content of this command is completely ignored and will not show up in the final page.
75 this can be used to add comments to your template page or temporarily disable part of it.
772. Declaring data:
79data is declared with simple key-value pairs, one per line:
80VARIABLENAME = VALUE
82When declaring a variable for a LIST command, VALUE is a list of rows,
83where is row a is enclosed in regular brakets:
84LIST = (5, true, "foo"),
85 (3, false, "bar")
86Please note that rows after the first need to be indented for parsing to work.
88All variable declarations need to be enclosed within the following tags
92Maps are declared either in the structure page or a seperate data page. In
93the simple case they are defined like this:
94NAME = a, b, c, d, e,
95 f, g, h, i, j
97In this case, this is a simple array, the index 0 will map to a, the index
982 to c and so on.
99Again, don't forget to indent rows after the first.
101Alternatively, you can manually specify indices:
102NAME = 1 = a, 3 = b, 8 = c
104This mainly makes sense if you intend to use LOOKRANGE for the lookup.
105There, 1 and 2 will map to "a", 3,4,5,6 and 7 to "b" and everything else
108maps are declars within the tags
1133. Putting everything together
115finally, you must put together the data.
116Simply put this at the end of your data page:
119When the data page is displayed, everything between [VARIABLES] and
120[ENDVARIABLES] is evaluated but not printed.
121The INCLUDE will be replaced with the content of the interpreted
122template page and only that will be displayed.
123Of course you can have multiple includes and thus construct a page
124from multiple templates or you can include variable definitions from
125a separate page.