ja:devel:syntax_plugins
差分
このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン前のリビジョン次のリビジョン | 前のリビジョン次のリビジョン両方とも次のリビジョン | ||
ja:devel:syntax_plugins [2008-08-09 21:25] – fixed link references chi | ja:devel:syntax_plugins [2009-12-23 09:34] – wakuteka | ||
---|---|---|---|
行 1: | 行 1: | ||
+ | ====== Syntax Plugins ====== | ||
+ | 構文プラグインはDokuwikiの構文を拡張する為の[[: | ||
+ | |||
+ | 自作の構文プラグインの為の詳細な情報は[[Syntax Plugins|syntax_tutorial]]を参照してください。 | ||
+ | |||
+ | ===== Synopsis ===== | ||
+ | |||
+ | 例えば構文プラグイン// | ||
+ | |||
+ | 最低でも下記の関数が実装されていなければなりません。: | ||
+ | |||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | \\ | ||
+ | |||
+ | 必要であれば下記のメソッドがオーバーライド可能です: | ||
+ | |||
+ | * **'' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | |||
+ | Additional functions can be defined as needed. It is recommended to prepend an underscore to self defined functions to avoid possible nameclashes with future plugin specification enhancements. | ||
+ | |||
+ | \\ | ||
+ | 継承されるプロパティ | ||
+ | |||
+ | * '' | ||
+ | |||
+ | ===== Syntax Types ===== | ||
+ | |||
+ | DokuWiki uses different syntax types to determine which syntax may be nested. Eg. you can have text formatting inside of tables. To integrate your Plugin into this system it needs to specify which type it is and which types can be nested within it. The following types are currently available: | ||
+ | |||
+ | ^ Type ^ Used in .. ^ Description ^ | ||
+ | | container | listblock, table, quote, hr | containers are complex modes that can contain many other modes hr breaks the principle but they shouldn' | ||
+ | | baseonly | header | some mode are allowed inside the base mode only | | ||
+ | | formatting | strong, emphasis, underline, monospace, subscript, superscript, | ||
+ | | substition((Yes this is spelled wrong, but we won't change it to avoid breaking existing plugins. Sometimes a typo becomes a standard - see the HTTP " | ||
+ | | protected |' | ||
+ | | disabled | unformatted | inside this mode no wiki markup should be applied but lineendings and whitespace isn't preserved | | ||
+ | | paragraphs | eol | used to mark paragraph boundaries | | ||
+ | |||
+ | For a description what each type means and which other formatting classes are registered in them read the comments in '' | ||
+ | |||
+ | ===== Discussion ===== | ||
+ | It's not readily apparent that the folder name needs to match the class declaration in the // | ||
+ | < | ||
+ | Fatal error: Cannot instantiate non-existent class: syntax_plugin_xyz in < | ||
+ | </ | ||
+ | or | ||
+ | < | ||
+ | Fatal error: Cannot redeclare class xyz in < | ||
+ | </ | ||
+ | |||
+ | ====== Tutorial: Syntax Plugins Explained ====== | ||
+ | |||
+ | このチュートリアルの目的は[[: | ||
+ | |||
+ | すぐにでも作成を始めたい方は[[devel: | ||
+ | これはページに"'' | ||
+ | |||
+ | ===== Quick Summary ===== | ||
+ | |||
+ | **modes** | ||
+ | |||
+ | * すべてのdokuwiki syntaxは、あなたの自作プラグインも含めて自分のmodeを持っています。 | ||
+ | * 同じようなmodesは [[#mode types]]にまとめられています. | ||
+ | * modeの" | ||
+ | * modeの" | ||
+ | |||
+ | ** handle ** | ||
+ | * '' | ||
+ | * '' | ||
+ | * なるべく処理や設定はここで終わらせて、'' | ||
+ | |||
+ | ** render ** | ||
+ | * The '' | ||
+ | * 出力文字列を '' | ||
+ | |||
+ | * プラグインから出力されるデータが安全であることを確認してください。- run raw wiki data through an entity conversion function. | ||
+ | * できるだけ短い処理にしてください。 '' | ||
+ | |||
+ | :!: '' | ||
+ | |||
+ | ===== Key Concepts ===== | ||
+ | |||
+ | ==== modes ==== | ||
+ | |||
+ | Modes (or more properly syntax modes) are the foundation on which the dokuwiki parser is based. | ||
+ | |||
+ | parserがパターンを見つけると、syntax modeに入ります。 プロパティとメソッドは、そのmodeの間parserがどのような処理を行うかを決定します。 : | ||
+ | * 他にどのようなsyntax modesが許可されているか | ||
+ | * what instructions to prepare for the renderer | ||
+ | \\ | ||
+ | 自作プラグインはparserに自分のsyntax modeを追加します。これはDokuwikiによって、プラグインのロード時に自動的になされます。名前は '' | ||
+ | |||
+ | ==== mode types ==== | ||
+ | |||
+ | 簡単に言うと、mode typesによってグループ化されたsyntax modesは同じように振る舞います。一覧は[[syntax plugins# | ||
+ | |||
+ | Each mode type corresponds to a key in the '' | ||
+ | |||
+ | When each plugin is loaded into the parser it is queried, via '' | ||
+ | |||
+ | :!: The mode type your plugin reports governs where in a Dokuwiki page the parser will recognise your plugin' | ||
+ | |||
+ | Select the mode type for your plugin by comparing the behaviour of your plugin to that of the standard dokuwiki syntax modes. | ||
+ | |||
+ | ==== allowed modes ==== | ||
+ | |||
+ | ネストされた他のmodeが現在のmode中に出現することがあります。 | ||
+ | |||
+ | |||
+ | Each syntax mode has its own array of allowed modes which tells the parser what other syntax modes will be recognised whilst its processing the mode. | ||
+ | もしあなたのプラグインを " | ||
+ | |||
+ | :!: Your plugin gets in the allowedModes array of other syntax modes through the mode type it reports using the '' | ||
+ | |||
+ | :!: Your plugin tells the parser which other syntax modes it permits by reporting the mode types it allows via the '' | ||
+ | |||
+ | ==== PType ==== | ||
+ | |||
+ | PTypeはparserがあなたのsyntax mode内でhtmlの %%< | ||
+ | |||
+ | parserが何かmarkupを発見した時、そこにはhtml表記での開始タグがあるかもしれません。parserはあなたのsyntax modeに入る前にそれが閉じられるべきか、そして処理後に新たに新しい開始タグを出力すべきか判断する必要があります。これが'' | ||
+ | |||
+ | For those that know CSS, returning '' | ||
+ | |||
+ | < | ||
+ | |||
+ | ==== Sort Number ==== | ||
+ | |||
+ | lexer((parserの一部で生のwiki pageを解析する))によって使われる番号で、生のWikiデータがsyntax modeのパターンに応じて処理される順番をコントロールします。これはパターンが同じデータ中で複数のModeに属している場合のみ重要です。もっとも小さい番号から処理されます。 | ||
+ | |||
+ | You can make use of this behaviour to write a plugin which will replace or extend a native dokuwiki handler for the same syntax. | ||
+ | |||
+ | Details of existing sort numbers are available for both the [[parser]] ([[.: | ||
+ | |||
+ | ==== Patterns ==== | ||
+ | |||
+ | parserはPHPのpreg((perl compatible regular expressions \\ ref: www.php.net/ | ||
+ | |||
+ | The complete preg syntax is not available for use in constructing syntax plugin patterns. Below is a list of the known differences: | ||
+ | |||
+ | * don't surround the pattern with delimiters | ||
+ | * to use a pipe "'' | ||
+ | * be very wary of look behind assertions. The parser only attempts to match patterns on the next piece of "not yet matched" | ||
+ | * option flagsはインラインオプションのみ使用可能です。例 '' | ||
+ | \\ | ||
+ | |||
+ | The parser provides four functions for a plugin to register the patterns it needs. | ||
+ | |||
+ | * **special patterns** --- '' | ||
+ | * **entry patterns** --- '' | ||
+ | * **exit patterns** --- '' | ||
+ | * **internal patterns** --- '' | ||
+ | \\ | ||
+ | |||
+ | One plugin may add several patterns to the parser, including more than one pattern of the same type. | ||
+ | |||
+ | **Tips** | ||
+ | |||
+ | * 最短マッチを使ってください。例 '' | ||
+ | * be wary of using multiple exit patterns. The first exit pattern encountered will most likely trigger the parser to exit your syntax mode - even if that wasn't the pattern the entry pattern looked ahead for. Needing multiple exit patterns probably indicates a need for multiple plugins. | ||
+ | * early versions of the Dokuwiki lexer had a bug which prevented use of "<" | ||
+ | |||
+ | ==== handle() method ==== | ||
+ | |||
+ | ここですべての処理を行ってください。 Before Dokuwiki renders the wiki page it creates a list of instructions for the renderer. | ||
+ | |||
+ | **$state** parameter --- The type of pattern which triggered this call to handle(). | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | * **'' | ||
+ | |||
+ | **$match** parameter --- The text which matched the pattern, or in the case of **'' | ||
+ | |||
+ | ==== render() method ==== | ||
+ | |||
+ | 最終的なWEBページの出力を提供します。プラグインはその出力を、すでにrendererによって作られたものに追加します。それは例えばrendererの'' | ||
+ | |||
+ | < | ||
+ | $renderer-> | ||
+ | </ | ||
+ | |||
+ | :!: すべての'' | ||
+ | |||
+ | **$mode** パラメータ --- rendererによって最終出力されたformat modeの名前です。今のところDokuwikiがサポートしているのは'' | ||
+ | < | ||
+ | if ($mode == ' | ||
+ | // code to generate xhtml output from instruction $data | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | **$data** パラメータ --- instructionsを含む、自プラグインの'' | ||
+ | |||
+ | ==== Safety & Security ==== | ||
+ | |||
+ | Raw wiki page data which reaches your plugin has not been processed at all. No further processing is done on the output after it leaves your plugin. | ||
+ | |||
+ | ==== Localization ==== | ||
+ | |||
+ | FIXME | ||
+ | |||
+ | For now refer to [[common plugin functions# | ||
+ | |||
+ | ==== Configuration ==== | ||
+ | |||
+ | FIXME | ||
+ | |||
+ | Also, refer [[common plugin functions# | ||
+ | |||
+ | The plugin interface provides some basic functions for accessing plugin specific configuration settings. | ||
+ | |||
+ | ^ file in ''< | ||
+ | |'' | ||
+ | |'' | ||
+ | |'' | ||
+ | |||
+ | A plugin can access its own setting values by using the '' | ||
+ | |||
+ | The [[plugin: | ||
+ | |||
+ | |||
+ | ==== Using Styles and Javascript ==== | ||
+ | |||
+ | FIXME | ||
+ | |||
+ | For now refer to [[plugin file structure]] | ||
+ | |||
+ | |||
+ | ==== Adding a Toolbar Button ==== | ||
+ | |||
+ | To make it easy on the users of wikis which install your plugin, you should add a button for its syntax to the editor toolbar. | ||
+ | |||
+ | FIXME | ||
+ | |||
+ | For now refer to [[devel: | ||
+ | |||
+ | ===== プラグインを自作するために ===== | ||
+ | |||
+ | Ok, so you have decided you want to extend Dokuwiki' | ||
+ | |||
+ | - Decide on a name for the plugin. | ||
+ | - In your own Dokuwiki installation create a new sub directory in the '' | ||
+ | - Create the file '' | ||
+ | - Edit that file to make it yours. | ||
+ | * change the class name to be '' | ||
+ | * change the '' | ||
+ | * change the '' | ||
+ | * add a '' | ||
+ | * change the '' | ||
+ | * change the '' | ||
+ | * alter the '' | ||
+ | * add a '' | ||
+ | - Thats the easy part done, you now have a plugin that will say "Hello World!" | ||
+ | - Write your '' | ||
+ | * if you have entry and exit patterns remember to handle the unmatched data. | ||
+ | * treat raw wiki data with suspicion and remember to ensure all special characters go to an entity converter. | ||
+ | - Test and post your completed plugin on the Dokuwiki [[: | ||
+ | |||
+ | ===== Sample Plugin 1 - Now ===== | ||
+ | |||
+ | When its syntax, '' | ||
+ | |||
+ | * type is '' | ||
+ | * allowedTypes are not required, no other dokuwiki syntax can occur within our '' | ||
+ | * PType is '' | ||
+ | * there is no need for an entry and exit pattern, just a special pattern to detect '' | ||
+ | * in this case the '' | ||
+ | * all the '' | ||
+ | |||
+ | And that's our plugin finished. | ||
+ | |||
+ | <code php syntax.php> | ||
+ | <?php | ||
+ | /** | ||
+ | * Plugin Now: Inserts a timestamp. | ||
+ | | ||
+ | * @license | ||
+ | * @author | ||
+ | */ | ||
+ | |||
+ | // must be run within Dokuwiki | ||
+ | if(!defined(' | ||
+ | |||
+ | if(!defined(' | ||
+ | require_once(DOKU_PLUGIN.' | ||
+ | |||
+ | /** | ||
+ | * All DokuWiki plugins to extend the parser/ | ||
+ | * need to inherit from this class | ||
+ | */ | ||
+ | class syntax_plugin_now extends DokuWiki_Syntax_Plugin { | ||
+ | |||
+ | function getInfo(){ | ||
+ | return array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | } | ||
+ | |||
+ | function getType() { return ' | ||
+ | function getSort() { return 32; } | ||
+ | function connectTo($mode) { $this-> | ||
+ | function handle($match, | ||
+ | function render($mode, | ||
+ | | ||
+ | if($mode == ' | ||
+ | $renderer-> | ||
+ | return true; | ||
+ | } | ||
+ | return false; | ||
+ | } | ||
+ | } | ||
+ | ?></ | ||
+ | |||
+ | Note: due to the way Dokuwiki caches pages this plugin will report the date/time at which the cached version was created. | ||
+ | |||
+ | ===== Sample Plugin 2 - Color ===== | ||
+ | |||
+ | When its syntax, '' | ||
+ | |||
+ | * what we are doing is similar to the strong mode, its type is ' | ||
+ | * allowedTypes should be the inline modes - '' | ||
+ | * PType is '' | ||
+ | * we need to use an entry and exit pattern. | ||
+ | * the '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * the '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | Again, all fairly straightforward - and here it is. | ||
+ | |||
+ | <code php syntax.php> | ||
+ | <?php | ||
+ | /** | ||
+ | * Plugin Color: Sets new colors for text and background. | ||
+ | | ||
+ | * @license | ||
+ | * @author | ||
+ | */ | ||
+ | |||
+ | // must be run within Dokuwiki | ||
+ | if(!defined(' | ||
+ | |||
+ | if(!defined(' | ||
+ | require_once(DOKU_PLUGIN.' | ||
+ | |||
+ | /** | ||
+ | * All DokuWiki plugins to extend the parser/ | ||
+ | * need to inherit from this class | ||
+ | */ | ||
+ | class syntax_plugin_color extends DokuWiki_Syntax_Plugin { | ||
+ | |||
+ | /** | ||
+ | * return some info | ||
+ | */ | ||
+ | function getInfo(){ | ||
+ | return array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | } | ||
+ | |||
+ | function getType(){ return ' | ||
+ | function getAllowedTypes() { return array(' | ||
+ | function getSort(){ return 158; } | ||
+ | function connectTo($mode) { $this-> | ||
+ | function postConnect() { $this-> | ||
+ | |||
+ | |||
+ | /** | ||
+ | * Handle the match | ||
+ | */ | ||
+ | function handle($match, | ||
+ | switch ($state) { | ||
+ | case DOKU_LEXER_ENTER : | ||
+ | list($color, | ||
+ | if ($color = $this-> | ||
+ | if ($background = $this-> | ||
+ | return array($state, | ||
+ | |||
+ | case DOKU_LEXER_UNMATCHED : return array($state, | ||
+ | case DOKU_LEXER_EXIT : | ||
+ | } | ||
+ | return array(); | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Create output | ||
+ | */ | ||
+ | function render($mode, | ||
+ | if($mode == ' | ||
+ | list($state, | ||
+ | switch ($state) { | ||
+ | case DOKU_LEXER_ENTER : | ||
+ | list($color, | ||
+ | $renderer-> | ||
+ | break; | ||
+ | | ||
+ | case DOKU_LEXER_UNMATCHED : $renderer-> | ||
+ | case DOKU_LEXER_EXIT : | ||
+ | } | ||
+ | return true; | ||
+ | } | ||
+ | return false; | ||
+ | } | ||
+ | | ||
+ | // validate color value $c | ||
+ | // this is cut price validation - only to ensure the basic format is correct and there is nothing harmful | ||
+ | // three basic formats | ||
+ | function _isValid($c) { | ||
+ | $c = trim($c); | ||
+ | | ||
+ | $pattern = "/ | ||
+ | ([a-zA-z]+)| | ||
+ | (\# | ||
+ | (rgb\(([0-9]{1, | ||
+ | )\s*$/ | ||
+ | | ||
+ | if (preg_match($pattern, | ||
+ | | ||
+ | return ""; | ||
+ | } | ||
+ | } | ||
+ | ?> | ||
+ | </ | ||
+ | |||
+ | Note: No checking is done to ensure colour names are valid or rgb values are within correct ranges. | ||
+ | |||
+ | ==== Discussion ==== | ||
+ | |||
+ | I try to create a plugin witch contains 2 block syntax in one plugin. I would like to put all my syntax codes in one plugin instead to split them in to many. | ||
+ | |||
+ | for example: | ||
+ | < | ||
+ | <color green> | ||
+ | <box note> | ||
+ | </ | ||
+ | |||
+ | The problem, one should create a " | ||
+ | |||
+ | Result example: | ||
+ | < | ||
+ | <span green> | ||
+ | <div note> | ||
+ | </ | ||
+ | |||
+ | So I need to detect the head tag "< | ||
+ | How I find out in " |
ja/devel/syntax_plugins.txt · 最終更新: 2023-08-17 19:29 by Klap-in