plugin:command
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
plugin:command [2007-10-20 12:42] – provided an alternative download of the command plugin ach | plugin:command [2023-12-10 01:27] (current) – [Command Plugin] nerun | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Command Plugin ====== | ||
+ | |||
+ | ---- plugin ---- | ||
+ | description: | ||
+ | author | ||
+ | email : martyn.eggleton@gmail.com | ||
+ | type : syntax | ||
+ | lastupdate : 2012-02-13 | ||
+ | compatible : !Hogfather, !Igor, !Jack Jackrum | ||
+ | depends | ||
+ | conflicts | ||
+ | similar | ||
+ | tags : extension, command, !broken, !discontinued | ||
+ | downloadurl: | ||
+ | bugtracker : https:// | ||
+ | sourcerepo : https:// | ||
+ | donationurl: | ||
+ | ---- | ||
+ | |||
+ | :!: WARNING: This plugin hasn't been updated since 2012 and is not compatible with the current version of Dokuwiki. | ||
+ | |||
+ | ===== Overview ===== | ||
+ | |||
+ | The **Command Syntax Plugin** implements an extensible syntax. | ||
+ | |||
+ | An extension of the plugin is called a **command**. | ||
+ | |||
+ | Here are examples of some (mostly) hypothetical commands: | ||
+ | |||
+ | < | ||
+ | %dt()% | ||
+ | %dt(8/23/05 12: | ||
+ | %DT(8/23/05 12: | ||
+ | %dt& | ||
+ | %scramble? | ||
+ | %icon? | ||
+ | %include(http:// | ||
+ | %CALC? | ||
+ | %hits()% | ||
+ | %count_days? | ||
+ | %notebox? | ||
+ | |||
+ | # | ||
+ | # | ||
+ | # | ||
+ | # | ||
+ | # | ||
+ | </ | ||
+ | |||
+ | The [[Date/ | ||
+ | |||
+ | The Command Plugin also provides a way to add endless new features to the DokuWiki syntax without overcrowding the syntax space. This helps reduce both user confusion and conflicts among syntaxes. People familiar with the syntax for any one command will understand the general syntax of all the other commands. | ||
+ | |||
+ | ===== Modification History ===== | ||
+ | |||
+ | This is essentially the work of [[http:// | ||
+ | |||
+ | * 2005/8/25 --- Created. [[http:// | ||
+ | * 2005/8/26 --- Reverted back to ' | ||
+ | * 2005/8/29 --- Added $renderer parameter to runCommand(). [[http:// | ||
+ | * 2005/8/29 --- Fixed failure to load extension for pre-cached data. [[http:// | ||
+ | * 2005/9/3 --- Fixed RSS feed by changing hsc() to htmlspecialchars(). [[http:// | ||
+ | * 2012/2/13 --- Moved hosting to github [[https:// | ||
+ | |||
+ | ===== Installation ===== | ||
+ | Search and install the plugin using the [[plugin: | ||
+ | |||
+ | When you install the plugin you get only one demo command. This command is the [[Date/ | ||
+ | |||
+ | To install other commands, follow the installation instructions given for the command. Every command consists of at least one file place in the extensions directory ''/ | ||
+ | |||
+ | ===== Syntax ===== | ||
+ | |||
+ | Every command occurs somewhere on the page. When the command is executed, it is replaced with the result of the command. | ||
+ | |||
+ | However, when you insert the command, you have to decide what is to happen around the command. | ||
+ | |||
+ | < | ||
+ | Inline command (inside paragraph): | ||
+ | Block command (outside paragraphs): | ||
+ | </ | ||
+ | |||
+ | If you use an //inline command// somewhere in a paragraph containing other text, the result of the command will replace the command within the same paragraph. | ||
+ | |||
+ | If you use a //block command// somewhere in a paragraph containing other text, the paragraph will split into two paragraphs, and the result of the command will be placed between the two paragraphs, not itself within a paragraph. | ||
+ | |||
+ | Each command is informed of how you chose to embed it on the page, so it may produce whatever HTML code is appropriate. | ||
+ | |||
+ | Here is the complete W3C-style BNF for the general command syntax: | ||
+ | |||
+ | < | ||
+ | command | ||
+ | inline_command ::= ' | ||
+ | block_command | ||
+ | call_string | ||
+ | command_name | ||
+ | params | ||
+ | param ::= value | name ' | ||
+ | name ::= [a-zA-Z] [a-zA-Z0-9_]* | ||
+ | value ::= [a-zA-Z0-9_\-.]+ | ||
+ | inline_content ::= {any string not containing ' | ||
+ | block_content | ||
+ | </ | ||
+ | |||
+ | Syntax notes: | ||
+ | |||
+ | - Names are constrained to allow them to appear in PHP identifiers and to minimize user confusion over issues such as whether ' | ||
+ | - Command names are not case-sensitive, | ||
+ | - Parameter values are strongly constrained to minimize parsing interference with other plugin syntaxes. | ||
+ | - [[: | ||
+ | |||
+ | If the BNF is too confusing, you can learn the syntax by looking at the examples in the [[# | ||
+ | |||
+ | The resulting syntax looks much like a hybrid between a URL query and a function call. This is for consistency with other DokuWiki syntaxes that use URL queries to provide parameters, such as the [[: | ||
+ | |||
+ | Command syntax is intentionally similar to the syntax of the [[Div/Span Shorthand]] plugin. Div/Span shorthand is useful for creating renderings of parsed text, provided you can use CSS to do it. | ||
+ | |||
+ | ===== Extensions ===== | ||
+ | |||
+ | The Command Plugin is designed to make it easy to implement custom commands. | ||
+ | |||
+ | - Choose a command name. You should pick a name that is not already taken -- or at least one you don't know to be taken. | ||
+ | - Determine the parameter set that your command will take, if it takes any parameters. | ||
+ | - Determine the form of the content that command accepts, if it uses content. | ||
+ | - Decide how the command should behave in inline embeddings and block embeddings. | ||
+ | - Create a file whose name is ''< | ||
+ | - In ''< | ||
+ | - In your new class, implement the function '' | ||
+ | - If your function needs to do something every time the page is generated, you can override function '' | ||
+ | - Test your class separately from DokuWiki by calling it directly. When your command is run from within a DokuWiki page, syntax and runtime errors occurring in your class may not make it to the screen or to any log file. | ||
+ | |||
+ | That's it, you're done. You don't need to worry about the syntax at all. All you have to do is implement behavior according to the indicated embedding mode (if it differs between the modes), examine the parameters and content as necessary, and perform the action and/or return replacement text. | ||
+ | |||
+ | You may prefer to simply copy ''/ | ||
+ | |||
+ | The base class '' | ||
+ | |||
+ | ===== extension.php ===== | ||
+ | |||
+ | **NOTICE:** This is not the source for this plugin. This is just the file containing the class that programmers subclass to create a new command. | ||
+ | |||
+ | <code php><? | ||
+ | / | ||
+ | CommandPluginExtension - Base class for a command of the Command Plugin. | ||
+ | |||
+ | Each command is a subclass of CommandPluginExtension. | ||
+ | must be of the form CommandPluginExtension_< | ||
+ | name of the command as it occurs in the syntax, in lowercase letters. | ||
+ | subclass must go in its own file, a file with name < | ||
+ | |||
+ | The behavior of a command may vary according to how the command was embedded | ||
+ | in the text. The Commmand Plugin provides two embedding modes: inline and | ||
+ | block. | ||
+ | will always appear within an HTML paragraph. | ||
+ | replacement text is guaranteed to occur outside of a paragraph. | ||
+ | that are sensibly placed in either an HTML div or span, the command may | ||
+ | output a div or a span according to the embedding mode chosen. | ||
+ | |||
+ | The class provides two methods. | ||
+ | must override with its own implementation. | ||
+ | the command to be replaced with the string returned by getCachedData() and | ||
+ | only needs to be overridden if this isn't the desired behavior. | ||
+ | |||
+ | The Command Plugin never instantiates this class. | ||
+ | methods and the $this variable is not available for use. | ||
+ | |||
+ | NOTICE: COMMANDS THAT OUTPUT USER-PROVIDED CONTENT SHOULD BE CAREFUL TO ESCAPE | ||
+ | SPECIAL HTML CHARACTERS FOUND IN THAT CONTENT, unless of course, the purpose | ||
+ | of the command is to allow the user to embed HTML of his/her choosing. | ||
+ | |||
+ | See http:// | ||
+ | |||
+ | @license | ||
+ | @author | ||
+ | |||
+ | Modification history: | ||
+ | |||
+ | 8/29/05 - Added $renderer parameter to runCommand(). JTL | ||
+ | ******************************************************************************/ | ||
+ | |||
+ | class CommandPluginExtension | ||
+ | { | ||
+ | /** | ||
+ | * getCachedData() pre-processes a command to produce data that can be | ||
+ | * cached. | ||
+ | * that does not change each time the page is generated. | ||
+ | * provides that information. | ||
+ | * replacement text can produce all of that replacement text in its | ||
+ | * final form during this method and then return it for caching. | ||
+ | * | ||
+ | * This method is also the only means by which parameters and content are | ||
+ | * handed to the command, so if these values cannot be processed until | ||
+ | * the page is actually generated, the method will be responsible for | ||
+ | * returning them (or some aspect of them) to be cached. | ||
+ | | ||
+ | * The $params and $paramHash arguments of this method contain the | ||
+ | * parameters that the user provided to the command. | ||
+ | * that describes all of the parameters, fully characterizing exactly what | ||
+ | * the user provided. | ||
+ | * easy to get to certain parameter values, but which which loses some | ||
+ | * information that is only available in $params. | ||
+ | * | ||
+ | * This method does nothing by default and must be overridden to | ||
+ | * implement the command, or at least to cache any needed arguments. | ||
+ | * | ||
+ | * This method is the Command Plugin analogue of the DokuWiki syntax | ||
+ | * plugin' | ||
+ | * | ||
+ | * @param string $embedding ' | ||
+ | * @param array $params An array of the command' | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | * @param array $paramHash An associative array indexed by parameter name | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | * @param string $content The content that the user provided to the | ||
+ | | ||
+ | * @param reference $errorMessage The method may set this variable to a | ||
+ | | ||
+ | | ||
+ | | ||
+ | * @return object The method may return any object that it would like | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | |||
+ | function getCachedData($embedding, | ||
+ | & | ||
+ | { | ||
+ | return null; | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * runCommand() implements the behavior that must occur each time the page | ||
+ | * is generated and to return the replacement text for the command. | ||
+ | * | ||
+ | * The default behavior is to return the string that getCachedData() | ||
+ | * returned, thus relegating the responsibility for producing the | ||
+ | * replacement text to getCachedData(). | ||
+ | * when the command produces static text that can be cached in its | ||
+ | * entirety. | ||
+ | * if some aspect of the command is dynamic. | ||
+ | * | ||
+ | * This method is the Command Plugin analogue of the DokuWiki syntax | ||
+ | * plugin' | ||
+ | * | ||
+ | * @param string $embedding ' | ||
+ | * @param object $cachedData This is the value that getCachedData() | ||
+ | | ||
+ | * @param reference $errorMessage The method may set this variable to a | ||
+ | | ||
+ | | ||
+ | | ||
+ | * @param reference $renderer This is the renderer object passed by the | ||
+ | | ||
+ | | ||
+ | | ||
+ | * @return string Replacement text for the command. | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | | ||
+ | function runCommand($embedding, | ||
+ | & | ||
+ | { | ||
+ | return $cachedData; | ||
+ | } | ||
+ | } | ||
+ | ?> | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Discussion ===== | ||
+ | |||
+ | I originally implemented this plugin using " | ||
+ | |||
+ | To fix this I changed the plugin to be a " | ||
+ | |||
+ | Any idea how I make substition un-greedy, given that I can't include parentheses? | ||
+ | |||
+ | > You should be able to add the ''"/ | ||
+ | |||
+ | Thank you!!!! | ||
+ | |||
+ | ---- | ||
+ | |||
+ | For consistency with the DokuWiki syntax that seems to be assuming dominance, should I instead use the following syntax? | ||
+ | |||
+ | < | ||
+ | {{command? | ||
+ | </ | ||
+ | |||
+ | I'd make it priority 1000 or so. But then how do I distinguish inline from block? | ||
+ | |||
+ | < | ||
+ | {{# | ||
+ | </ | ||
+ | |||
+ | ... for block embedding, perhaps? | ||
+ | |||
+ | < | ||
+ | {{command> | ||
+ | {{command> | ||
+ | {{command? | ||
+ | </ | ||
+ | |||
+ | It doesn' | ||
+ | > priority 1000 (I guess you mean '' | ||
+ | |||
+ | >> | ||
+ | |||
+ | > I would suppose you switch to '' | ||
+ | |||
+ | ---- | ||
+ | |||
+ | Removing a command (or renaming it) corrupts all wikipages which use it (and all the history files too). The following error is displayed: | ||
+ | < | ||
+ | Can you catch this error and print out some readable error message instead? | ||
+ | --- // | ||