diff options
author | Gerrit Uitslag <klapinklapin@gmail.com> | 2014-09-28 13:46:04 +0200 |
---|---|---|
committer | Gerrit Uitslag <klapinklapin@gmail.com> | 2014-09-28 13:46:04 +0200 |
commit | b79379f2e598abaa2febb299cdfcebe0a95d034c (patch) | |
tree | 7098c3a758f606394f4b38d679b5198f8973cffe /inc/parser/renderer.php | |
parent | 73411587cb6d2c54aefebe90c87799c4aa1d31ec (diff) | |
parent | da9572711f54d13ce3c5506971154b0bc359723f (diff) | |
download | rpg-b79379f2e598abaa2febb299cdfcebe0a95d034c.tar.gz rpg-b79379f2e598abaa2febb299cdfcebe0a95d034c.tar.bz2 |
Merge remote-tracking branch 'origin/master' into overridablelangstrings
Conflicts:
inc/plugin.php
Diffstat (limited to 'inc/parser/renderer.php')
-rw-r--r-- | inc/parser/renderer.php | 765 |
1 files changed, 626 insertions, 139 deletions
diff --git a/inc/parser/renderer.php b/inc/parser/renderer.php index e92b81bd7..09294539e 100644 --- a/inc/parser/renderer.php +++ b/inc/parser/renderer.php @@ -11,263 +11,748 @@ if(!defined('DOKU_INC')) die('meh.'); * An empty renderer, produces no output * * Inherits from DokuWiki_Plugin for giving additional functions to render plugins + * + * The renderer transforms the syntax instructions created by the parser and handler into the + * desired output format. For each instruction a corresponding method defined in this class will + * be called. That method needs to produce the desired output for the instruction and add it to the + * $doc field. When all instructions are processed, the $doc field contents will be cached by + * DokuWiki and sent to the user. */ class Doku_Renderer extends DokuWiki_Plugin { - var $info = array( + /** @var array Settings, control the behavior of the renderer */ + public $info = array( 'cache' => true, // may the rendered result cached? 'toc' => true, // render the TOC? ); - var $doc = ''; + /** @var array contains the smiley configuration, set in p_render() */ + public $smileys = array(); + /** @var array contains the entity configuration, set in p_render() */ + public $entities = array(); + /** @var array contains the acronym configuration, set in p_render() */ + public $acronyms = array(); + /** @var array contains the interwiki configuration, set in p_render() */ + public $interwiki = array(); - // keep some config options - var $acronyms = array(); - var $smileys = array(); - var $badwords = array(); - var $entities = array(); - var $interwiki = array(); + /** + * @var string the rendered document, this will be cached after the renderer ran through + */ + public $doc = ''; - // allows renderer to be used again, clean out any per-use values + /** + * clean out any per-use values + * + * This is called before each use of the renderer object and should be used to + * completely reset the state of the renderer to be reused for a new document + */ function reset() { } - function nocache() { - $this->info['cache'] = false; - } - - function notoc() { - $this->info['toc'] = false; + /** + * Allow the plugin to prevent DokuWiki from reusing an instance + * + * Since most renderer plugins fail to implement Doku_Renderer::reset() we default + * to reinstantiating the renderer here + * + * @return bool false if the plugin has to be instantiated + */ + function isSingleton() { + return false; } /** * Returns the format produced by this renderer. * - * Has to be overidden by decendend classes + * Has to be overidden by sub classes + * + * @return string */ - function getFormat(){ + function getFormat() { trigger_error('getFormat() not implemented in '.get_class($this), E_USER_WARNING); + return ''; } /** - * Allow the plugin to prevent DokuWiki from reusing an instance + * Disable caching of this renderer's output + */ + function nocache() { + $this->info['cache'] = false; + } + + /** + * Disable TOC generation for this renderer's output * - * @return bool false if the plugin has to be instantiated + * This might not be used for certain sub renderer */ - function isSingleton() { - return false; + function notoc() { + $this->info['toc'] = false; } /** - * handle plugin rendering + * Handle plugin rendering + * + * Most likely this needs NOT to be overwritten by sub classes * - * @param string $name Plugin name - * @param mixed $data custom data set by handler + * @param string $name Plugin name + * @param mixed $data custom data set by handler * @param string $state matched state if any * @param string $match raw matched syntax */ - function plugin($name,$data,$state='',$match=''){ - $plugin = plugin_load('syntax',$name); - if($plugin != null){ - $plugin->render($this->getFormat(),$this,$data); + function plugin($name, $data, $state = '', $match = '') { + /** @var DokuWiki_Syntax_Plugin $plugin */ + $plugin = plugin_load('syntax', $name); + if($plugin != null) { + $plugin->render($this->getFormat(), $this, $data); } } /** * handle nested render instructions * this method (and nest_close method) should not be overloaded in actual renderer output classes + * + * @param array $instructions */ function nest($instructions) { - - foreach ( $instructions as $instruction ) { + foreach($instructions as $instruction) { // execute the callback against ourself - if (method_exists($this,$instruction[0])) { + if(method_exists($this, $instruction[0])) { call_user_func_array(array($this, $instruction[0]), $instruction[1] ? $instruction[1] : array()); } } } - // dummy closing instruction issued by Doku_Handler_Nest, normally the syntax mode should - // override this instruction when instantiating Doku_Handler_Nest - however plugins will not - // be able to - as their instructions require data. - function nest_close() {} - - function document_start() {} + /** + * dummy closing instruction issued by Doku_Handler_Nest + * + * normally the syntax mode should override this instruction when instantiating Doku_Handler_Nest - + * however plugins will not be able to - as their instructions require data. + */ + function nest_close() { + } - function document_end() {} + #region Syntax modes - sub classes will need to implement them to fill $doc - function render_TOC() { return ''; } + /** + * Initialize the document + */ + function document_start() { + } - function toc_additem($id, $text, $level) {} + /** + * Finalize the document + */ + function document_end() { + } - function header($text, $level, $pos) {} + /** + * Render the Table of Contents + * + * @return string + */ + function render_TOC() { + return ''; + } - function section_open($level) {} + /** + * Add an item to the TOC + * + * @param string $id the hash link + * @param string $text the text to display + * @param int $level the nesting level + */ + function toc_additem($id, $text, $level) { + } - function section_close() {} + /** + * Render a heading + * + * @param string $text the text to display + * @param int $level header level + * @param int $pos byte position in the original source + */ + function header($text, $level, $pos) { + } - function cdata($text) {} + /** + * Open a new section + * + * @param int $level section level (as determined by the previous header) + */ + function section_open($level) { + } - function p_open() {} + /** + * Close the current section + */ + function section_close() { + } - function p_close() {} + /** + * Render plain text data + * + * @param $text + */ + function cdata($text) { + } - function linebreak() {} + /** + * Open a paragraph + */ + function p_open() { + } - function hr() {} + /** + * Close a paragraph + */ + function p_close() { + } - function strong_open() {} + /** + * Create a line break + */ + function linebreak() { + } - function strong_close() {} + /** + * Create a horizontal line + */ + function hr() { + } - function emphasis_open() {} + /** + * Start strong (bold) formatting + */ + function strong_open() { + } - function emphasis_close() {} + /** + * Stop strong (bold) formatting + */ + function strong_close() { + } - function underline_open() {} + /** + * Start emphasis (italics) formatting + */ + function emphasis_open() { + } - function underline_close() {} + /** + * Stop emphasis (italics) formatting + */ + function emphasis_close() { + } - function monospace_open() {} + /** + * Start underline formatting + */ + function underline_open() { + } - function monospace_close() {} + /** + * Stop underline formatting + */ + function underline_close() { + } - function subscript_open() {} + /** + * Start monospace formatting + */ + function monospace_open() { + } - function subscript_close() {} + /** + * Stop monospace formatting + */ + function monospace_close() { + } - function superscript_open() {} + /** + * Start a subscript + */ + function subscript_open() { + } - function superscript_close() {} + /** + * Stop a subscript + */ + function subscript_close() { + } - function deleted_open() {} + /** + * Start a superscript + */ + function superscript_open() { + } - function deleted_close() {} + /** + * Stop a superscript + */ + function superscript_close() { + } - function footnote_open() {} + /** + * Start deleted (strike-through) formatting + */ + function deleted_open() { + } - function footnote_close() {} + /** + * Stop deleted (strike-through) formatting + */ + function deleted_close() { + } - function listu_open() {} + /** + * Start a footnote + */ + function footnote_open() { + } - function listu_close() {} + /** + * Stop a footnote + */ + function footnote_close() { + } - function listo_open() {} + /** + * Open an unordered list + */ + function listu_open() { + } - function listo_close() {} + /** + * Close an unordered list + */ + function listu_close() { + } - function listitem_open($level) {} + /** + * Open an ordered list + */ + function listo_open() { + } - function listitem_close() {} + /** + * Close an ordered list + */ + function listo_close() { + } - function listcontent_open() {} + /** + * Open a list item + * + * @param int $level the nesting level + */ + function listitem_open($level) { + } - function listcontent_close() {} + /** + * Close a list item + */ + function listitem_close() { + } - function unformatted($text) {} + /** + * Start the content of a list item + */ + function listcontent_open() { + } - function php($text) {} + /** + * Stop the content of a list item + */ + function listcontent_close() { + } - function phpblock($text) {} + /** + * Output unformatted $text + * + * Defaults to $this->cdata() + * + * @param string $text + */ + function unformatted($text) { + $this->cdata($text); + } - function html($text) {} + /** + * Output inline PHP code + * + * If $conf['phpok'] is true this should evaluate the given code and append the result + * to $doc + * + * @param string $text The PHP code + */ + function php($text) { + } - function htmlblock($text) {} + /** + * Output block level PHP code + * + * If $conf['phpok'] is true this should evaluate the given code and append the result + * to $doc + * + * @param string $text The PHP code + */ + function phpblock($text) { + } - function preformatted($text) {} + /** + * Output raw inline HTML + * + * If $conf['htmlok'] is true this should add the code as is to $doc + * + * @param string $text The HTML + */ + function html($text) { + } - function quote_open() {} + /** + * Output raw block-level HTML + * + * If $conf['htmlok'] is true this should add the code as is to $doc + * + * @param string $text The HTML + */ + function htmlblock($text) { + } - function quote_close() {} + /** + * Output preformatted text + * + * @param string $text + */ + function preformatted($text) { + } - function file($text, $lang = null, $file = null ) {} + /** + * Start a block quote + */ + function quote_open() { + } - function code($text, $lang = null, $file = null ) {} + /** + * Stop a block quote + */ + function quote_close() { + } - function acronym($acronym) {} + /** + * Display text as file content, optionally syntax highlighted + * + * @param string $text text to show + * @param string $lang programming language to use for syntax highlighting + * @param string $file file path label + */ + function file($text, $lang = null, $file = null) { + } - function smiley($smiley) {} + /** + * Display text as code content, optionally syntax highlighted + * + * @param string $text text to show + * @param string $lang programming language to use for syntax highlighting + * @param string $file file path label + */ + function code($text, $lang = null, $file = null) { + } - function wordblock($word) {} + /** + * Format an acronym + * + * Uses $this->acronyms + * + * @param string $acronym + */ + function acronym($acronym) { + } - function entity($entity) {} + /** + * Format a smiley + * + * Uses $this->smiley + * + * @param string $smiley + */ + function smiley($smiley) { + } - // 640x480 ($x=640, $y=480) - function multiplyentity($x, $y) {} + /** + * Format an entity + * + * Entities are basically small text replacements + * + * Uses $this->entities + * + * @param string $entity + */ + function entity($entity) { + } - function singlequoteopening() {} + /** + * Typographically format a multiply sign + * + * Example: ($x=640, $y=480) should result in "640×480" + * + * @param string|int $x first value + * @param string|int $y second value + */ + function multiplyentity($x, $y) { + } - function singlequoteclosing() {} + /** + * Render an opening single quote char (language specific) + */ + function singlequoteopening() { + } - function apostrophe() {} + /** + * Render a closing single quote char (language specific) + */ + function singlequoteclosing() { + } - function doublequoteopening() {} + /** + * Render an apostrophe char (language specific) + */ + function apostrophe() { + } - function doublequoteclosing() {} + /** + * Render an opening double quote char (language specific) + */ + function doublequoteopening() { + } - // $link like 'SomePage' - function camelcaselink($link) {} + /** + * Render an closinging double quote char (language specific) + */ + function doublequoteclosing() { + } - function locallink($hash, $name = null) {} + /** + * Render a CamelCase link + * + * @param string $link The link name + * @see http://en.wikipedia.org/wiki/CamelCase + */ + function camelcaselink($link) { + } - // $link like 'wiki:syntax', $title could be an array (media) - function internallink($link, $title = null) {} + /** + * Render a page local link + * + * @param string $hash hash link identifier + * @param string $name name for the link + */ + function locallink($hash, $name = null) { + } - // $link is full URL with scheme, $title could be an array (media) - function externallink($link, $title = null) {} + /** + * Render a wiki internal link + * + * @param string $link page ID to link to. eg. 'wiki:syntax' + * @param string|array $title name for the link, array for media file + */ + function internallink($link, $title = null) { + } - function rss ($url,$params) {} + /** + * Render an external link + * + * @param string $link full URL with scheme + * @param string|array $title name for the link, array for media file + */ + function externallink($link, $title = null) { + } - // $link is the original link - probably not much use - // $wikiName is an indentifier for the wiki - // $wikiUri is the URL fragment to append to some known URL - function interwikilink($link, $title = null, $wikiName, $wikiUri) {} + /** + * Render the output of an RSS feed + * + * @param string $url URL of the feed + * @param array $params Finetuning of the output + */ + function rss($url, $params) { + } - // Link to file on users OS, $title could be an array (media) - function filelink($link, $title = null) {} + /** + * Render an interwiki link + * + * You may want to use $this->_resolveInterWiki() here + * + * @param string $link original link - probably not much use + * @param string|array $title name for the link, array for media file + * @param string $wikiName indentifier (shortcut) for the remote wiki + * @param string $wikiUri the fragment parsed from the original link + */ + function interwikilink($link, $title = null, $wikiName, $wikiUri) { + } - // Link to a Windows share, , $title could be an array (media) - function windowssharelink($link, $title = null) {} + /** + * Link to file on users OS + * + * @param string $link the link + * @param string|array $title name for the link, array for media file + */ + function filelink($link, $title = null) { + } -// function email($address, $title = null) {} - function emaillink($address, $name = null) {} + /** + * Link to windows share + * + * @param string $link the link + * @param string|array $title name for the link, array for media file + */ + function windowssharelink($link, $title = null) { + } - function internalmedia ($src, $title=null, $align=null, $width=null, - $height=null, $cache=null, $linking=null) {} + /** + * Render a linked E-Mail Address + * + * Should honor $conf['mailguard'] setting + * + * @param string $address Email-Address + * @param string|array $name name for the link, array for media file + */ + function emaillink($address, $name = null) { + } - function externalmedia ($src, $title=null, $align=null, $width=null, - $height=null, $cache=null, $linking=null) {} + /** + * Render an internal media file + * + * @param string $src media ID + * @param string $title descriptive text + * @param string $align left|center|right + * @param int $width width of media in pixel + * @param int $height height of media in pixel + * @param string $cache cache|recache|nocache + * @param string $linking linkonly|detail|nolink + */ + function internalmedia($src, $title = null, $align = null, $width = null, + $height = null, $cache = null, $linking = null) { + } - function internalmedialink ( - $src,$title=null,$align=null,$width=null,$height=null,$cache=null - ) {} + /** + * Render an external media file + * + * @param string $src full media URL + * @param string $title descriptive text + * @param string $align left|center|right + * @param int $width width of media in pixel + * @param int $height height of media in pixel + * @param string $cache cache|recache|nocache + * @param string $linking linkonly|detail|nolink + */ + function externalmedia($src, $title = null, $align = null, $width = null, + $height = null, $cache = null, $linking = null) { + } - function externalmedialink( - $src,$title=null,$align=null,$width=null,$height=null,$cache=null - ) {} + /** + * Render a link to an internal media file + * + * @param string $src media ID + * @param string $title descriptive text + * @param string $align left|center|right + * @param int $width width of media in pixel + * @param int $height height of media in pixel + * @param string $cache cache|recache|nocache + */ + function internalmedialink($src, $title = null, $align = null, + $width = null, $height = null, $cache = null) { + } - function table_open($maxcols = null, $numrows = null, $pos = null){} + /** + * Render a link to an external media file + * + * @param string $src media ID + * @param string $title descriptive text + * @param string $align left|center|right + * @param int $width width of media in pixel + * @param int $height height of media in pixel + * @param string $cache cache|recache|nocache + */ + function externalmedialink($src, $title = null, $align = null, + $width = null, $height = null, $cache = null) { + } - function table_close($pos = null){} + /** + * Start a table + * + * @param int $maxcols maximum number of columns + * @param int $numrows NOT IMPLEMENTED + * @param int $pos byte position in the original source + */ + function table_open($maxcols = null, $numrows = null, $pos = null) { + } - function tablethead_open(){} + /** + * Close a table + * + * @param int $pos byte position in the original source + */ + function table_close($pos = null) { + } - function tablethead_close(){} + /** + * Open a table header + */ + function tablethead_open() { + } - function tablerow_open(){} + /** + * Close a table header + */ + function tablethead_close() { + } - function tablerow_close(){} + /** + * Open a table row + */ + function tablerow_open() { + } - function tableheader_open($colspan = 1, $align = null, $rowspan = 1){} + /** + * Close a table row + */ + function tablerow_close() { + } - function tableheader_close(){} + /** + * Open a table header cell + * + * @param int $colspan + * @param string $align left|center|right + * @param int $rowspan + */ + function tableheader_open($colspan = 1, $align = null, $rowspan = 1) { + } - function tablecell_open($colspan = 1, $align = null, $rowspan = 1){} + /** + * Close a table header cell + */ + function tableheader_close() { + } - function tablecell_close(){} + /** + * Open a table cell + * + * @param int $colspan + * @param string $align left|center|right + * @param int $rowspan + */ + function tablecell_open($colspan = 1, $align = null, $rowspan = 1) { + } + /** + * Close a table cell + */ + function tablecell_close() { + } - // util functions follow, you probably won't need to reimplement them + #endregion + #region util functions, you probably won't need to reimplement them /** * Removes any Namespace from the given name but keeps @@ -294,13 +779,13 @@ class Doku_Renderer extends DokuWiki_Plugin { /** * Resolve an interwikilink */ - function _resolveInterWiki(&$shortcut, $reference, &$exists=null) { + function _resolveInterWiki(&$shortcut, $reference, &$exists = null) { //get interwiki URL if(isset($this->interwiki[$shortcut])) { $url = $this->interwiki[$shortcut]; } else { // Default to Google I'm feeling lucky - $url = 'http://www.google.com/search?q={URL}&btnI=lucky'; + $url = 'http://www.google.com/search?q={URL}&btnI=lucky'; $shortcut = 'go'; } @@ -310,8 +795,8 @@ class Doku_Renderer extends DokuWiki_Plugin { //replace placeholder if(preg_match('#\{(URL|NAME|SCHEME|HOST|PORT|PATH|QUERY)\}#', $url)) { //use placeholders - $url = str_replace('{URL}', rawurlencode($reference), $url); - $url = str_replace('{NAME}', $reference, $url); + $url = str_replace('{URL}', rawurlencode($reference), $url); + $url = str_replace('{NAME}', $reference, $url); $parsed = parse_url($reference); if(!$parsed['port']) $parsed['port'] = 80; $url = str_replace('{SCHEME}', $parsed['scheme'], $url); @@ -321,18 +806,20 @@ class Doku_Renderer extends DokuWiki_Plugin { $url = str_replace('{QUERY}', $parsed['query'], $url); } else { //default - $url = $url . rawurlencode($reference); + $url = $url.rawurlencode($reference); } //handle as wiki links if($url{0} === ':') { list($id, $urlparam) = explode('?', $url, 2); - $url = wl(cleanID($id), $urlparam); + $url = wl(cleanID($id), $urlparam); $exists = page_exists($id); } - if($hash) $url .= '#' . rawurlencode($hash); + if($hash) $url .= '#'.rawurlencode($hash); return $url; } + + #endregion } |