1<?php
2
3/******************************************************************************
4CommandPluginExtension - Base class for a command of the Command Plugin.
5
6Each command is a subclass of CommandPluginExtension.  The name of a subclass
7must be of the form CommandPluginExtension_<command>, where <command> is the
8name of the command as it occurs in the syntax, in lowercase letters.  Each
9subclass must go in its own file, a file with name <command>.php.
10
11The behavior of a command may vary according to how the command was embedded
12in the text.  The Commmand Plugin provides two embedding modes: inline and
13block.  When embedding inline, any replacement text that the command produces
14will always appear within an HTML paragraph.  When block-embedding, the
15replacement text is guaranteed to occur outside of a paragraph.  In commands
16that are sensibly placed in either an HTML div or span, the commmand may
17output a div or a span according to the embedding mode chosen.
18
19The class provides two methods.  getCachedData() is a stub that each command
20must override with its own implementation.  runCommand() by default causes
21the command to be replaced with the string returned by getCachedData() and
22only needs to be overridden if this isn't the desired behavior.
23
24The Command Plugin never instantiates this class.  Both methods are static
25methods and the $this variable is not available for use.
26
27NOTICE: COMMANDS THAT OUTPUT USER-PROVIDED CONTENT SHOULD BE CAREFUL TO ESCAPE
28SPECIAL HTML CHARACTERS FOUND IN THAT CONTENT, unless of course, the purpose
29of the command is to allow the user to embed HTML of his/her choosing.
30
31See http://www.splitbrain.org/plugin:command for more information.
32
33@license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
34@author     Joe Lapp <http://www.spiderjoe.com>
35
36Modification history:
37
388/29/05 - Added $renderer parameter to runCommand(). JTL
39******************************************************************************/
40
41class CommandPluginExtension
42{
43    /**
44     * getCachedData() pre-processes a command to produce data that can be
45     * cached.  DokuWiki pre-compiles its pages to extract the information
46     * that does not change each time the page is generated.  This method
47     * provides that information.  Usually a command that only produces
48     * replacement text can produce all of that replacement text in its
49     * final form during this method and then return it for caching.
50     *
51     * This method is also the only means by which parameters and content are
52     * handed to the commmand, so if these values cannot be processed until
53     * the page is actually generated, the method will be responsible for
54     * returning them (or some aspect of them) to be cached.
55     *
56     * The $params and $paramHash arguments of this method contain the
57     * parameters that the user provided to the command.  $params is an array
58     * that describes all of the parameters, fully characterizing exactly what
59     * the user provided.  $paramHash is a convenience argument that makes it
60     * easy to get to certain parameter values, but which which loses some
61     * information that is only avaiable in $params.
62     *
63     * This method does nothing by default and must be overridden to
64     * implement the command, or at least to cache any needed arguments.
65     *
66     * This method is the Command Plugin analogue of the DokuWiki syntax
67     * plugin's handle() method.
68     *
69     * @param string $embedding 'inline' or 'block'
70     * @param array $params An array of the command's parameters, indexed by
71     *      their order of occurrence in the parameter list.  If the parameter
72     *      was an assignment (using '='), its element will be an array of the
73     *      form array(name, value).  If the parameter was a simple value (no
74     *      '='), its element will be a string containing that value.  If
75     *      there are no parameters, $params will be an empty array.
76     * @param array $paramHash An associative array indexed by parameter name
77     *      (for assignment parameters) and by parameter value (for simple
78     *      value parameters).  If no value was assigned to a parameter, or if
79     *      the parameter is itself just a value, the value for the index key
80     *      is an empty string.  For example, "?1&1&2&a&b=&c=3&d=4&d=5"
81     *      produces array('1'=>'', '2'=>'', 'a'=>'', 'b'=>'', 'c'=>'3',
82     *      'd'=>'5').
83     * @param string $content The content that the user provided to the
84     *      command.  Empty string if there was no content.
85     * @param reference $errorMessage The method may set this variable to a
86     *      non-empty string to report an error and provide an error message.
87     *      If the method does this, this error message will be output into
88     *      the text, replacing the commmand, and runCommand() is not called.
89     * @return object The method may return any object that it would like
90     *      cached for later use by runCommand().  The method may even return
91     *      null.  If the command is using the default implementation of
92     *      runCommand(), getCachedData() must return a string containing the
93     *      replacement text for the command, unless the method reports an
94     *      error by setting $errorMessage.  If the returned value is the
95     *      replacement text, THIS METHOD SHOULD FIRST ESCAPE ANY SPECIAL
96     *      HTML CHARACTERS THAT THE USER MAY HAVE PROVIDED.
97     */
98
99    function getCachedData($embedding, $params, $paramHash, $content,
100                             &$errorMessage) // STATIC
101    {
102        return null;
103    }
104
105    /**
106     * runCommand() implements the behavior that must occur each time the page
107     * is generated and to return the replacement text for the command.
108     *
109     * The default behavior is to return the string that getCachedData()
110     * returned, thus relegating the responsibility for producing the
111     * replacement text to getCachedData().  This behavior is appropriate
112     * when the command produces static text that can be cached in its
113     * entirety.  A command should only override the default implementation
114     * if some aspect of the command is dynamic.
115     *
116     * This method is the Command Plugin analogue of the DokuWiki syntax
117     * plugin's render() method.
118     *
119     * @param string $embedding 'inline' or 'block'
120     * @param object $cachedData This is the value that getCachedData()
121     *      returned for the command, which may be null.
122     * @param reference $errorMessage The method may set this variable to a
123     *      non-empty string to report an error and provide an error message.
124     *      If the method does this, this error message will be output into
125     *      the text, serving as the replacement text for the command.
126     * @param reference $renderer This is the renderer object passed by the
127     *      parser to the plugin's render() method.  Some commands may need
128     *      to access this object.  It is possible to output text via the
129     *      renderer, but the function should return text instead.
130     * @return string Replacement text for the command.  The replacement text
131     *      may be either null or the empty string, which are equivalent.
132     *      The return value is ignored if the method reported an error by
133     *      setting $errorMessage.  If the method returns replacement text
134     *      and getCachedData() has not already escaped special HTML
135     *      characters, THIS METHOD SHOULD FIRST ESCAPE ANY SPECIAL HTML
136     *      CHARACTERS THAT THE USER MAY HAVE PROVIDED.
137     */
138
139    function runCommand($embedding, $cachedData, &$renderer,
140                          &$errorMessage) // STATIC
141    {
142        return $cachedData;
143    }
144}
145?>