none
[openafs-wiki.git] / TWiki / RenderListPlugin.mdwn
1 # <a name="Render List Plugin"></a> Render List Plugin
2
3 Render bullet lists in a variety of formats
4
5 ## <a name="Syntax Rules"></a> Syntax Rules
6
7 - Place a `%RENDERLIST{ <parameters> }%` before any bullet list
8   - The lists can be handcrafted, generated by another Plugin, a `%TOC%`, or the result of a [[FormattedSearch]]
9 - Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
10   <tr>
11     <td><code>"name"</code> or%BR% <code>theme="name"</code></td>
12     <td> Select a rendering theme </td>
13   </tr>
14   <tr>
15     <td><code>focus="any text"</code></td>
16     <td> Focus list on a bullet with specified text </td>
17   </tr>
18   <tr>
19     <td><code>depth="2"</code></td>
20     <td> Remove bullets with an indent greater then the depth. The depth is relative to the highlighted bullet in case <code>focus</code> is specified </td>
21   </tr>
22 </table>
23 - Rendering themes can be defined by `<name>_THEME` Plugin settings
24   - Each theme is defined by a comma separated list containing the render type and parameters required by that render type
25   - There are different render types; this initial Plugin version has **tree** and **icon** render types
26 - Format of the **tree** render type:
27   - `Set <name>_THEME = tree, <0/1 flag to suppress/show lines of first level>`
28 - Format of the **icon** render type:
29   - `Set <name>_THEME = icon, <0/1 flag to suppress/show lines of first level>, <icon width>, <icon height>, <spacer graph>, <T-line graph>, <I-line graph>, <L-line graph>, <icon image>`
30   - To define new Icon themes, attach images to this Plugin topic and set the parameters accordingly
31 - Focus bullet list:
32   - Search bullet list for text. If a bullet is found:
33     1. Highlight text and remove `[[][]]` links on bullet where text is found
34     2. Reduce bullet list to show only its parents and children
35   - This is useful to maintain one large bullet list with links to team pages, representing the organization of a company. Each team page can INCLUDE the bullet list with focus set to itself.
36
37 ## <a name="Examples"></a> Examples
38
39 <table border="0" cellpadding="3" cellspacing="5">
40   <tr>
41     <th bgcolor="#CCCCC" valign="top"><strong><em>You type:</em></strong></th>
42     <th bgcolor="#CCCCC" valign="top"><strong><em>You get: (simulated)</em></strong></th>
43     <th bgcolor="#CCCCC" valign="top"><strong><em>You get: (if installed)</em></strong></th>
44   </tr>
45   <tr>
46     <td bgcolor="#EEEEEE" valign="top"><pre>
47 %RENDERLIST{"thread"}%
48         * one
49                 * one.a
50                         * one.a.x
51                 * one.b
52                         * one.b.x
53                           continue
54                         * one.b.y
55                           continue
56         * two
57         * three
58 </pre></td>
59     <td bgcolor="#EEEEEE" valign="top">
60       <p>
61       </p>
62       <table border="0" cellpadding="0" cellspacing="0">
63         <tr>
64           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
65           <td valign="top"><nobr> one </nobr></td>
66         </tr>
67       </table>
68       <table border="0" cellpadding="0" cellspacing="0">
69         <tr>
70           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
71           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
72           <td valign="top"><nobr> one.a </nobr></td>
73         </tr>
74       </table>
75       <table border="0" cellpadding="0" cellspacing="0">
76         <tr>
77           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
78           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
79           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
80           <td valign="top"><nobr> one.a.x </nobr></td>
81         </tr>
82       </table>
83       <table border="0" cellpadding="0" cellspacing="0">
84         <tr>
85           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
86           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
87           <td valign="top"><nobr> one.b </nobr></td>
88         </tr>
89       </table>
90       <table border="0" cellpadding="0" cellspacing="0">
91         <tr>
92           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
93           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
94           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
95           <td valign="top"><nobr> one.b.x </nobr></td>
96         </tr>
97       </table>
98       <table border="0" cellpadding="0" cellspacing="0">
99         <tr>
100           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
101           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
102           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
103           <td valign="top"><nobr> continue </nobr></td>
104         </tr>
105       </table>
106       <table border="0" cellpadding="0" cellspacing="0">
107         <tr>
108           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
109           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
110           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
111           <td valign="top"><nobr> one.b.y </nobr></td>
112         </tr>
113       </table>
114       <table border="0" cellpadding="0" cellspacing="0">
115         <tr>
116           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
117           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
118           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
119           <td valign="top"><nobr> continue </nobr></td>
120         </tr>
121       </table>
122       <table border="0" cellpadding="0" cellspacing="0">
123         <tr>
124           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
125           <td valign="top"><nobr> two </nobr></td>
126         </tr>
127       </table>
128       <table border="0" cellpadding="0" cellspacing="0">
129         <tr>
130           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
131           <td valign="top"><nobr> three </nobr></td>
132         </tr>
133       </table>
134       <p>
135       </p>
136     </td>
137     <td bgcolor="#EEEEEE" valign="top">
138       <p> %RENDERLIST{"thread"}% </p>
139       <ul>
140         <li> one <ul>
141             <li> one.a <ul>
142                 <li> one.a.x </li>
143               </ul>
144             </li>
145             <li> one.b <ul>
146                 <li> one.b.x continue </li>
147                 <li> one.b.y continue </li>
148               </ul>
149             </li>
150           </ul>
151         </li>
152         <li> two </li>
153         <li> three </li>
154       </ul>
155       <p>
156       </p>
157     </td>
158   </tr>
159   <tr>
160     <td bgcolor="#EEEEEE" valign="top"><pre>
161 %RENDERLIST{"org"}%
162         * one
163                 * one.a
164                         * one.a.x
165                 * one.b
166                         * one.b.x
167                           continue
168                         * one.b.y
169                           continue
170         * two
171         * three
172 </pre></td>
173     <td bgcolor="#EEEEEE" valign="top">
174       <p>
175       </p>
176       <table border="0" cellpadding="0" cellspacing="0">
177         <tr>
178           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
179           <td valign="top"><nobr>  one </nobr></td>
180         </tr>
181       </table>
182       <table border="0" cellpadding="0" cellspacing="0">
183         <tr>
184           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
185           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
186           <td valign="top"><nobr>  one.a </nobr></td>
187         </tr>
188       </table>
189       <table border="0" cellpadding="0" cellspacing="0">
190         <tr>
191           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
192           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
193           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
194           <td valign="top"><nobr>  one.a.x </nobr></td>
195         </tr>
196       </table>
197       <table border="0" cellpadding="0" cellspacing="0">
198         <tr>
199           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
200           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
201           <td valign="top"><nobr>  one.b </nobr></td>
202         </tr>
203       </table>
204       <table border="0" cellpadding="0" cellspacing="0">
205         <tr>
206           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
207           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
208           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
209           <td valign="top"><nobr>  one.b.x </nobr></td>
210         </tr>
211       </table>
212       <table border="0" cellpadding="0" cellspacing="0">
213         <tr>
214           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
215           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
216           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
217           <td valign="top"><nobr>  continue </nobr></td>
218         </tr>
219       </table>
220       <table border="0" cellpadding="0" cellspacing="0">
221         <tr>
222           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
223           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
224           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
225           <td valign="top"><nobr>  one.b.y </nobr></td>
226         </tr>
227       </table>
228       <table border="0" cellpadding="0" cellspacing="0">
229         <tr>
230           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
231           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
232           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
233           <td valign="top"><nobr>  continue </nobr></td>
234         </tr>
235       </table>
236       <table border="0" cellpadding="0" cellspacing="0">
237         <tr>
238           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
239           <td valign="top"><nobr>  two </nobr></td>
240         </tr>
241       </table>
242       <table border="0" cellpadding="0" cellspacing="0">
243         <tr>
244           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
245           <td valign="top"><nobr>  three </nobr></td>
246         </tr>
247       </table>
248       <p>
249       </p>
250     </td>
251     <td bgcolor="#EEEEEE" valign="top">
252       <p> %RENDERLIST{"org"}% </p>
253       <ul>
254         <li> one <ul>
255             <li> one.a <ul>
256                 <li> one.a.x </li>
257               </ul>
258             </li>
259             <li> one.b <ul>
260                 <li> one.b.x continue </li>
261                 <li> one.b.y continue </li>
262               </ul>
263             </li>
264           </ul>
265         </li>
266         <li> two </li>
267         <li> three </li>
268       </ul>
269       <p>
270       </p>
271     </td>
272   </tr>
273   <tr>
274     <td bgcolor="#EEEEEE" valign="top"><pre>
275 %RENDERLIST{ "org" focus="one.b" }%
276         * one
277                 * one.a
278                         * one.a.x
279                 * one.b
280                         * one.b.x
281                           continue
282                         * one.b.y
283                           continue
284         * two
285         * three
286 </pre></td>
287     <td bgcolor="#EEEEEE" valign="top">
288       <p>
289       </p>
290       <table border="0" cellpadding="0" cellspacing="0">
291         <tr>
292           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
293           <td valign="top"><nobr>  one </nobr></td>
294         </tr>
295       </table>
296       <table border="0" cellpadding="0" cellspacing="0">
297         <tr>
298           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
299           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
300           <td valign="top"><nobr>  <b> one.b </b> </nobr></td>
301         </tr>
302       </table>
303       <table border="0" cellpadding="0" cellspacing="0">
304         <tr>
305           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
306           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_udr.gif" width="16" /></td>
307           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
308           <td valign="top"><nobr>  one.b.x </nobr></td>
309         </tr>
310       </table>
311       <table border="0" cellpadding="0" cellspacing="0">
312         <tr>
313           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
314           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ud.gif" width="16" /></td>
315           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
316           <td valign="top"><nobr>  continue </nobr></td>
317         </tr>
318       </table>
319       <table border="0" cellpadding="0" cellspacing="0">
320         <tr>
321           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
322           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/dot_ur.gif" width="16" /></td>
323           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/home.gif" width="16" /></td>
324           <td valign="top"><nobr>  one.b.y </nobr></td>
325         </tr>
326       </table>
327       <table border="0" cellpadding="0" cellspacing="0">
328         <tr>
329           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
330           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
331           <td valign="top"><img alt="" border="0" height="16" src="http://www.dementia.org/twiki//view/empty.gif" width="16" /></td>
332           <td valign="top"><nobr>  continue </nobr></td>
333         </tr>
334       </table>
335       <p>
336       </p>
337     </td>
338     <td bgcolor="#EEEEEE" valign="top">
339       <p> %RENDERLIST{ "org" focus="one.b" }% </p>
340       <ul>
341         <li> one <ul>
342             <li> one.a <ul>
343                 <li> one.a.x </li>
344               </ul>
345             </li>
346             <li> one.b <ul>
347                 <li> one.b.x continue </li>
348                 <li> one.b.y continue </li>
349               </ul>
350             </li>
351           </ul>
352         </li>
353         <li> two </li>
354         <li> three </li>
355       </ul>
356       <p>
357       </p>
358     </td>
359   </tr>
360 </table>
361
362 ## <a name="%TOPIC% Settings"></a> %TOPIC% Settings
363
364 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, i.e. <code>**%RENDERPLUGIN\_SHORTDESCRIPTION%**</code>
365
366 - One line description, is shown in the [[TextFormattingRules]] topic:
367   - Set SHORTDESCRIPTION = Render bullet lists in a variety of formats
368
369 - Debug plugin: (See output in `data/debug.txt`)
370   - Set DEBUG = 0
371
372 - Themes are named `<SOMETHING>_THEME` and contain a comma delimited list of render type with parameters:
373   - Set THREAD\_THEME = tree, 1
374   - Set HOME\_THEME = icon, 1, 16, 16, ![empty.gif](http://www.dementia.org/twiki//view/empty.gif), ![dot\_udr.gif](http://www.dementia.org/twiki//view/dot_udr.gif), ![dot\_ud.gif](http://www.dementia.org/twiki//view/dot_ud.gif), ![dot\_ur.gif](http://www.dementia.org/twiki//view/dot_ur.gif), ![home.gif](http://www.dementia.org/twiki//view/home.gif)
375   - Set ORG\_THEME = icon, 0, 16, 16, ![empty.gif](http://www.dementia.org/twiki//view/empty.gif), ![dot\_udr.gif](http://www.dementia.org/twiki//view/dot_udr.gif), ![dot\_ud.gif](http://www.dementia.org/twiki//view/dot_ud.gif), ![dot\_ur.gif](http://www.dementia.org/twiki//view/dot_ur.gif), ![home.gif](http://www.dementia.org/twiki//view/home.gif)
376   - Set GROUP\_THEME = icon, 0, 16, 16, ![empty.gif](http://www.dementia.org/twiki//view/empty.gif), ![dot\_udr.gif](http://www.dementia.org/twiki//view/dot_udr.gif), ![dot\_ud.gif](http://www.dementia.org/twiki//view/dot_ud.gif), ![dot\_ur.gif](http://www.dementia.org/twiki//view/dot_ur.gif), ![group.gif](http://www.dementia.org/twiki//view/group.gif)
377   - Set EMAIL\_THEME = icon, 0, 16, 16, ![empty.gif](http://www.dementia.org/twiki//view/empty.gif), ![dot\_udr.gif](http://www.dementia.org/twiki//view/dot_udr.gif), ![dot\_ud.gif](http://www.dementia.org/twiki//view/dot_ud.gif), ![dot\_ur.gif](http://www.dementia.org/twiki//view/dot_ur.gif), ![email.gif](http://www.dementia.org/twiki//view/email.gif)
378
379 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
380
381 **_Note:_** You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
382
383 - Download the ZIP file from the Plugin web (see below)
384 - Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
385   <tr>
386     <th bgcolor="#99CCCC"><strong> File: </strong></th>
387     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
388   </tr>
389   <tr>
390     <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
391     <td> Plugin topic </td>
392   </tr>
393   <tr>
394     <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
395     <td> Plugin topic repository </td>
396   </tr>
397   <tr>
398     <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
399     <td> Plugin Perl module </td>
400   </tr>
401   <tr>
402     <td><code><b>pub/TWiki/%TOPIC%/*.gif</b></code></td>
403     <td> Image files for themes </td>
404   </tr>
405 </table>
406 - Test if the installation was successful:
407   - See if the above example works
408
409 ## <a name="Plugin Info"></a> Plugin Info
410
411 <table border="1" cellpadding="0" cellspacing="0">
412   <tr>
413     <td align="right"> Plugin Author: </td>
414     <td> TWiki:Main/PeterThoeny </td>
415   </tr>
416   <tr>
417     <td align="right"> Plugin Version: </td>
418     <td> 11 Dec 2003 (V1.020) </td>
419   </tr>
420   <tr>
421     <td align="right"> Change History: </td>
422     <td>  </td>
423   </tr>
424   <tr>
425     <td align="right"> 11 Dec 2003: </td>
426     <td> Added <code>focus</code> and <code>depth</code> parameters </td>
427   </tr>
428   <tr>
429     <td align="right"> 05 Dec 2003: </td>
430     <td> Fixed rendering issue with IE, added EMAIL_THEME </td>
431   </tr>
432   <tr>
433     <td align="right"> 02 Dec 2003: </td>
434     <td> Initial version </td>
435   </tr>
436   <tr>
437     <td align="right"> CPAN Dependencies: </td>
438     <td> none </td>
439   </tr>
440   <tr>
441     <td align="right"> Other Dependencies: </td>
442     <td> none </td>
443   </tr>
444   <tr>
445     <td align="right"> Perl Version: </td>
446     <td> 5.005 </td>
447   </tr>
448   <tr>
449     <td align="right"> Plugin Home: </td>
450     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
451   </tr>
452   <tr>
453     <td align="right"> Feedback: </td>
454     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
455   </tr>
456 </table>
457
458 **_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]], TWiki:Plugins/TreePlugin
459
460 -- TWiki:Main/PeterThoeny - 11 Dec 2003