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