1e1d9dcc8SAndreas Gohr<?php 2e1d9dcc8SAndreas Gohr 3e1d9dcc8SAndreas Gohrnamespace dokuwiki\Extension; 4e1d9dcc8SAndreas Gohr 5*1490c177SAndreas Gohruse dokuwiki\Parsing\ParserMode\Plugin; 6903d43feSMichael Großeuse Doku_Handler; 7903d43feSMichael Großeuse Doku_Renderer; 8e1d9dcc8SAndreas Gohr 9e1d9dcc8SAndreas Gohr/** 10e1d9dcc8SAndreas Gohr * Syntax Plugin Prototype 11e1d9dcc8SAndreas Gohr * 12e1d9dcc8SAndreas Gohr * All DokuWiki plugins to extend the parser/rendering mechanism 13e1d9dcc8SAndreas Gohr * need to inherit from this class 14e1d9dcc8SAndreas Gohr * 15e1d9dcc8SAndreas Gohr * @license GPL 2 (http://www.gnu.org/licenses/gpl.html) 16e1d9dcc8SAndreas Gohr * @author Andreas Gohr <andi@splitbrain.org> 17e1d9dcc8SAndreas Gohr */ 18*1490c177SAndreas Gohrabstract class SyntaxPlugin extends Plugin 19e1d9dcc8SAndreas Gohr{ 20e1d9dcc8SAndreas Gohr protected $allowedModesSetup = false; 21e1d9dcc8SAndreas Gohr 22e1d9dcc8SAndreas Gohr /** 23e1d9dcc8SAndreas Gohr * Syntax Type 24e1d9dcc8SAndreas Gohr * 25e1d9dcc8SAndreas Gohr * Needs to return one of the mode types defined in $PARSER_MODES in Parser.php 26e1d9dcc8SAndreas Gohr * 27e1d9dcc8SAndreas Gohr * @return string 28e1d9dcc8SAndreas Gohr */ 29e1d9dcc8SAndreas Gohr abstract public function getType(); 30e1d9dcc8SAndreas Gohr 31e1d9dcc8SAndreas Gohr /** 32e1d9dcc8SAndreas Gohr * Allowed Mode Types 33e1d9dcc8SAndreas Gohr * 34e1d9dcc8SAndreas Gohr * Defines the mode types for other dokuwiki markup that maybe nested within the 35e1d9dcc8SAndreas Gohr * plugin's own markup. Needs to return an array of one or more of the mode types 36e1d9dcc8SAndreas Gohr * defined in $PARSER_MODES in Parser.php 37e1d9dcc8SAndreas Gohr * 38e1d9dcc8SAndreas Gohr * @return array 39e1d9dcc8SAndreas Gohr */ 40e1d9dcc8SAndreas Gohr public function getAllowedTypes() 41e1d9dcc8SAndreas Gohr { 42*1490c177SAndreas Gohr return []; 43e1d9dcc8SAndreas Gohr } 44e1d9dcc8SAndreas Gohr 45e1d9dcc8SAndreas Gohr /** 46e1d9dcc8SAndreas Gohr * Paragraph Type 47e1d9dcc8SAndreas Gohr * 48e1d9dcc8SAndreas Gohr * Defines how this syntax is handled regarding paragraphs. This is important 49e1d9dcc8SAndreas Gohr * for correct XHTML nesting. Should return one of the following: 50e1d9dcc8SAndreas Gohr * 51e1d9dcc8SAndreas Gohr * 'normal' - The plugin can be used inside paragraphs 52e1d9dcc8SAndreas Gohr * 'block' - Open paragraphs need to be closed before plugin output 53e1d9dcc8SAndreas Gohr * 'stack' - Special case. Plugin wraps other paragraphs. 54e1d9dcc8SAndreas Gohr * 55e1d9dcc8SAndreas Gohr * @see Doku_Handler_Block 56e1d9dcc8SAndreas Gohr * 57e1d9dcc8SAndreas Gohr * @return string 58e1d9dcc8SAndreas Gohr */ 59e1d9dcc8SAndreas Gohr public function getPType() 60e1d9dcc8SAndreas Gohr { 61e1d9dcc8SAndreas Gohr return 'normal'; 62e1d9dcc8SAndreas Gohr } 63e1d9dcc8SAndreas Gohr 64e1d9dcc8SAndreas Gohr /** 65e1d9dcc8SAndreas Gohr * Handler to prepare matched data for the rendering process 66e1d9dcc8SAndreas Gohr * 67e1d9dcc8SAndreas Gohr * This function can only pass data to render() via its return value - render() 68e1d9dcc8SAndreas Gohr * may be not be run during the object's current life. 69e1d9dcc8SAndreas Gohr * 70e1d9dcc8SAndreas Gohr * Usually you should only need the $match param. 71e1d9dcc8SAndreas Gohr * 72e1d9dcc8SAndreas Gohr * @param string $match The text matched by the patterns 73e1d9dcc8SAndreas Gohr * @param int $state The lexer state for the match 74e1d9dcc8SAndreas Gohr * @param int $pos The character position of the matched text 75e1d9dcc8SAndreas Gohr * @param Doku_Handler $handler The Doku_Handler object 76e1d9dcc8SAndreas Gohr * @return bool|array Return an array with all data you want to use in render, false don't add an instruction 77e1d9dcc8SAndreas Gohr */ 78e1d9dcc8SAndreas Gohr abstract public function handle($match, $state, $pos, Doku_Handler $handler); 79e1d9dcc8SAndreas Gohr 80e1d9dcc8SAndreas Gohr /** 81e1d9dcc8SAndreas Gohr * Handles the actual output creation. 82e1d9dcc8SAndreas Gohr * 83e1d9dcc8SAndreas Gohr * The function must not assume any other of the classes methods have been run 84e1d9dcc8SAndreas Gohr * during the object's current life. The only reliable data it receives are its 85e1d9dcc8SAndreas Gohr * parameters. 86e1d9dcc8SAndreas Gohr * 87e1d9dcc8SAndreas Gohr * The function should always check for the given output format and return false 88e1d9dcc8SAndreas Gohr * when a format isn't supported. 89e1d9dcc8SAndreas Gohr * 90e1d9dcc8SAndreas Gohr * $renderer contains a reference to the renderer object which is 91e1d9dcc8SAndreas Gohr * currently handling the rendering. You need to use it for writing 92e1d9dcc8SAndreas Gohr * the output. How this is done depends on the renderer used (specified 93e1d9dcc8SAndreas Gohr * by $format 94e1d9dcc8SAndreas Gohr * 95e1d9dcc8SAndreas Gohr * The contents of the $data array depends on what the handler() function above 96e1d9dcc8SAndreas Gohr * created 97e1d9dcc8SAndreas Gohr * 98e1d9dcc8SAndreas Gohr * @param string $format output format being rendered 99e1d9dcc8SAndreas Gohr * @param Doku_Renderer $renderer the current renderer object 100e1d9dcc8SAndreas Gohr * @param array $data data created by handler() 101e1d9dcc8SAndreas Gohr * @return boolean rendered correctly? (however, returned value is not used at the moment) 102e1d9dcc8SAndreas Gohr */ 103e1d9dcc8SAndreas Gohr abstract public function render($format, Doku_Renderer $renderer, $data); 104e1d9dcc8SAndreas Gohr 105e1d9dcc8SAndreas Gohr /** 106e1d9dcc8SAndreas Gohr * There should be no need to override this function 107e1d9dcc8SAndreas Gohr * 108e1d9dcc8SAndreas Gohr * @param string $mode 109e1d9dcc8SAndreas Gohr * @return bool 110e1d9dcc8SAndreas Gohr */ 111e1d9dcc8SAndreas Gohr public function accepts($mode) 112e1d9dcc8SAndreas Gohr { 113e1d9dcc8SAndreas Gohr 114e1d9dcc8SAndreas Gohr if (!$this->allowedModesSetup) { 115e1d9dcc8SAndreas Gohr global $PARSER_MODES; 116e1d9dcc8SAndreas Gohr 117e1d9dcc8SAndreas Gohr $allowedModeTypes = $this->getAllowedTypes(); 118e1d9dcc8SAndreas Gohr foreach ($allowedModeTypes as $mt) { 119e1d9dcc8SAndreas Gohr $this->allowedModes = array_merge($this->allowedModes, $PARSER_MODES[$mt]); 120e1d9dcc8SAndreas Gohr } 121e1d9dcc8SAndreas Gohr 122*1490c177SAndreas Gohr $idx = array_search(substr(get_class($this), 7), (array)$this->allowedModes, true); 123e1d9dcc8SAndreas Gohr if ($idx !== false) { 124e1d9dcc8SAndreas Gohr unset($this->allowedModes[$idx]); 125e1d9dcc8SAndreas Gohr } 126e1d9dcc8SAndreas Gohr $this->allowedModesSetup = true; 127e1d9dcc8SAndreas Gohr } 128e1d9dcc8SAndreas Gohr 129e1d9dcc8SAndreas Gohr return parent::accepts($mode); 130e1d9dcc8SAndreas Gohr } 131e1d9dcc8SAndreas Gohr} 132