[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/inc/parser/ -> renderer.php (source)

   1  <?php
   2  /**
   3   * Renderer output base class
   4   *
   5   * @author Harry Fuecks <hfuecks@gmail.com>
   6   * @author Andreas Gohr <andi@splitbrain.org>
   7   */
   8  
   9  use dokuwiki\Extension\Plugin;
  10  use dokuwiki\Extension\SyntaxPlugin;
  11  
  12  /**
  13   * Allowed chars in $language for code highlighting
  14   * @see GeSHi::set_language()
  15   */
  16  define('PREG_PATTERN_VALID_LANGUAGE', '#[^a-zA-Z0-9\-_]#');
  17  
  18  /**
  19   * An empty renderer, produces no output
  20   *
  21   * Inherits from dokuwiki\Plugin\DokuWiki_Plugin for giving additional functions to render plugins
  22   *
  23   * The renderer transforms the syntax instructions created by the parser and handler into the
  24   * desired output format. For each instruction a corresponding method defined in this class will
  25   * be called. That method needs to produce the desired output for the instruction and add it to the
  26   * $doc field. When all instructions are processed, the $doc field contents will be cached by
  27   * DokuWiki and sent to the user.
  28   */
  29  abstract class Doku_Renderer extends Plugin {
  30      /** @var array Settings, control the behavior of the renderer */
  31      public $info = array(
  32          'cache' => true, // may the rendered result cached?
  33          'toc'   => true, // render the TOC?
  34      );
  35  
  36      /** @var array contains the smiley configuration, set in p_render() */
  37      public $smileys = array();
  38      /** @var array contains the entity configuration, set in p_render() */
  39      public $entities = array();
  40      /** @var array contains the acronym configuration, set in p_render() */
  41      public $acronyms = array();
  42      /** @var array contains the interwiki configuration, set in p_render() */
  43      public $interwiki = array();
  44      /** @var string|int link pages and media against this revision */
  45      public $date_at = '';
  46  
  47      /** @var array the list of headers used to create unique link ids */
  48      protected $headers = array();
  49  
  50      /**
  51       * @var string the rendered document, this will be cached after the renderer ran through
  52       */
  53      public $doc = '';
  54  
  55      /**
  56       * clean out any per-use values
  57       *
  58       * This is called before each use of the renderer object and should be used to
  59       * completely reset the state of the renderer to be reused for a new document
  60       */
  61      public function reset(){
  62          $this->headers = array();
  63          $this->doc           = '';
  64          $this->info['cache'] = true;
  65          $this->info['toc']   = true;
  66      }
  67  
  68      /**
  69       * Allow the plugin to prevent DokuWiki from reusing an instance
  70       *
  71       * Since most renderer plugins fail to implement Doku_Renderer::reset() we default
  72       * to reinstantiating the renderer here
  73       *
  74       * @return bool   false if the plugin has to be instantiated
  75       */
  76      public function isSingleton() {
  77          return false;
  78      }
  79  
  80      /**
  81       * Returns the format produced by this renderer.
  82       *
  83       * Has to be overidden by sub classes
  84       *
  85       * @return string
  86       */
  87      abstract public function getFormat();
  88  
  89      /**
  90       * Disable caching of this renderer's output
  91       */
  92      public function nocache() {
  93          $this->info['cache'] = false;
  94      }
  95  
  96      /**
  97       * Disable TOC generation for this renderer's output
  98       *
  99       * This might not be used for certain sub renderer
 100       */
 101      public function notoc() {
 102          $this->info['toc'] = false;
 103      }
 104  
 105      /**
 106       * Handle plugin rendering
 107       *
 108       * Most likely this needs NOT to be overwritten by sub classes
 109       *
 110       * @param string $name  Plugin name
 111       * @param mixed  $data  custom data set by handler
 112       * @param string $state matched state if any
 113       * @param string $match raw matched syntax
 114       */
 115      public function plugin($name, $data, $state = '', $match = '') {
 116          /** @var SyntaxPlugin $plugin */
 117          $plugin = plugin_load('syntax', $name);
 118          if($plugin != null) {
 119              $plugin->render($this->getFormat(), $this, $data);
 120          }
 121      }
 122  
 123      /**
 124       * handle nested render instructions
 125       * this method (and nest_close method) should not be overloaded in actual renderer output classes
 126       *
 127       * @param array $instructions
 128       */
 129      public function nest($instructions) {
 130          foreach($instructions as $instruction) {
 131              // execute the callback against ourself
 132              if(method_exists($this, $instruction[0])) {
 133                  call_user_func_array(array($this, $instruction[0]), $instruction[1] ? $instruction[1] : array());
 134              }
 135          }
 136      }
 137  
 138      /**
 139       * dummy closing instruction issued by Doku_Handler_Nest
 140       *
 141       * normally the syntax mode should override this instruction when instantiating Doku_Handler_Nest -
 142       * however plugins will not be able to - as their instructions require data.
 143       */
 144      public function nest_close() {
 145      }
 146  
 147      #region Syntax modes - sub classes will need to implement them to fill $doc
 148  
 149      /**
 150       * Initialize the document
 151       */
 152      public function document_start() {
 153      }
 154  
 155      /**
 156       * Finalize the document
 157       */
 158      public function document_end() {
 159      }
 160  
 161      /**
 162       * Render the Table of Contents
 163       *
 164       * @return string
 165       */
 166      public function render_TOC() {
 167          return '';
 168      }
 169  
 170      /**
 171       * Add an item to the TOC
 172       *
 173       * @param string $id       the hash link
 174       * @param string $text     the text to display
 175       * @param int    $level    the nesting level
 176       */
 177      public function toc_additem($id, $text, $level) {
 178      }
 179  
 180      /**
 181       * Render a heading
 182       *
 183       * @param string $text  the text to display
 184       * @param int    $level header level
 185       * @param int    $pos   byte position in the original source
 186       */
 187      public function header($text, $level, $pos) {
 188      }
 189  
 190      /**
 191       * Open a new section
 192       *
 193       * @param int $level section level (as determined by the previous header)
 194       */
 195      public function section_open($level) {
 196      }
 197  
 198      /**
 199       * Close the current section
 200       */
 201      public function section_close() {
 202      }
 203  
 204      /**
 205       * Render plain text data
 206       *
 207       * @param string $text
 208       */
 209      public function cdata($text) {
 210      }
 211  
 212      /**
 213       * Open a paragraph
 214       */
 215      public function p_open() {
 216      }
 217  
 218      /**
 219       * Close a paragraph
 220       */
 221      public function p_close() {
 222      }
 223  
 224      /**
 225       * Create a line break
 226       */
 227      public function linebreak() {
 228      }
 229  
 230      /**
 231       * Create a horizontal line
 232       */
 233      public function hr() {
 234      }
 235  
 236      /**
 237       * Start strong (bold) formatting
 238       */
 239      public function strong_open() {
 240      }
 241  
 242      /**
 243       * Stop strong (bold) formatting
 244       */
 245      public function strong_close() {
 246      }
 247  
 248      /**
 249       * Start emphasis (italics) formatting
 250       */
 251      public function emphasis_open() {
 252      }
 253  
 254      /**
 255       * Stop emphasis (italics) formatting
 256       */
 257      public function emphasis_close() {
 258      }
 259  
 260      /**
 261       * Start underline formatting
 262       */
 263      public function underline_open() {
 264      }
 265  
 266      /**
 267       * Stop underline formatting
 268       */
 269      public function underline_close() {
 270      }
 271  
 272      /**
 273       * Start monospace formatting
 274       */
 275      public function monospace_open() {
 276      }
 277  
 278      /**
 279       * Stop monospace formatting
 280       */
 281      public function monospace_close() {
 282      }
 283  
 284      /**
 285       * Start a subscript
 286       */
 287      public function subscript_open() {
 288      }
 289  
 290      /**
 291       * Stop a subscript
 292       */
 293      public function subscript_close() {
 294      }
 295  
 296      /**
 297       * Start a superscript
 298       */
 299      public function superscript_open() {
 300      }
 301  
 302      /**
 303       * Stop a superscript
 304       */
 305      public function superscript_close() {
 306      }
 307  
 308      /**
 309       * Start deleted (strike-through) formatting
 310       */
 311      public function deleted_open() {
 312      }
 313  
 314      /**
 315       * Stop deleted (strike-through) formatting
 316       */
 317      public function deleted_close() {
 318      }
 319  
 320      /**
 321       * Start a footnote
 322       */
 323      public function footnote_open() {
 324      }
 325  
 326      /**
 327       * Stop a footnote
 328       */
 329      public function footnote_close() {
 330      }
 331  
 332      /**
 333       * Open an unordered list
 334       */
 335      public function listu_open() {
 336      }
 337  
 338      /**
 339       * Close an unordered list
 340       */
 341      public function listu_close() {
 342      }
 343  
 344      /**
 345       * Open an ordered list
 346       */
 347      public function listo_open() {
 348      }
 349  
 350      /**
 351       * Close an ordered list
 352       */
 353      public function listo_close() {
 354      }
 355  
 356      /**
 357       * Open a list item
 358       *
 359       * @param int $level the nesting level
 360       * @param bool $node true when a node; false when a leaf
 361       */
 362      public function listitem_open($level,$node=false) {
 363      }
 364  
 365      /**
 366       * Close a list item
 367       */
 368      public function listitem_close() {
 369      }
 370  
 371      /**
 372       * Start the content of a list item
 373       */
 374      public function listcontent_open() {
 375      }
 376  
 377      /**
 378       * Stop the content of a list item
 379       */
 380      public function listcontent_close() {
 381      }
 382  
 383      /**
 384       * Output unformatted $text
 385       *
 386       * Defaults to $this->cdata()
 387       *
 388       * @param string $text
 389       */
 390      public function unformatted($text) {
 391          $this->cdata($text);
 392      }
 393  
 394      /**
 395       * Output preformatted text
 396       *
 397       * @param string $text
 398       */
 399      public function preformatted($text) {
 400      }
 401  
 402      /**
 403       * Start a block quote
 404       */
 405      public function quote_open() {
 406      }
 407  
 408      /**
 409       * Stop a block quote
 410       */
 411      public function quote_close() {
 412      }
 413  
 414      /**
 415       * Display text as file content, optionally syntax highlighted
 416       *
 417       * @param string $text text to show
 418       * @param string $lang programming language to use for syntax highlighting
 419       * @param string $file file path label
 420       */
 421      public function file($text, $lang = null, $file = null) {
 422      }
 423  
 424      /**
 425       * Display text as code content, optionally syntax highlighted
 426       *
 427       * @param string $text text to show
 428       * @param string $lang programming language to use for syntax highlighting
 429       * @param string $file file path label
 430       */
 431      public function code($text, $lang = null, $file = null) {
 432      }
 433  
 434      /**
 435       * Format an acronym
 436       *
 437       * Uses $this->acronyms
 438       *
 439       * @param string $acronym
 440       */
 441      public function acronym($acronym) {
 442      }
 443  
 444      /**
 445       * Format a smiley
 446       *
 447       * Uses $this->smiley
 448       *
 449       * @param string $smiley
 450       */
 451      public function smiley($smiley) {
 452      }
 453  
 454      /**
 455       * Format an entity
 456       *
 457       * Entities are basically small text replacements
 458       *
 459       * Uses $this->entities
 460       *
 461       * @param string $entity
 462       */
 463      public function entity($entity) {
 464      }
 465  
 466      /**
 467       * Typographically format a multiply sign
 468       *
 469       * Example: ($x=640, $y=480) should result in "640×480"
 470       *
 471       * @param string|int $x first value
 472       * @param string|int $y second value
 473       */
 474      public function multiplyentity($x, $y) {
 475      }
 476  
 477      /**
 478       * Render an opening single quote char (language specific)
 479       */
 480      public function singlequoteopening() {
 481      }
 482  
 483      /**
 484       * Render a closing single quote char (language specific)
 485       */
 486      public function singlequoteclosing() {
 487      }
 488  
 489      /**
 490       * Render an apostrophe char (language specific)
 491       */
 492      public function apostrophe() {
 493      }
 494  
 495      /**
 496       * Render an opening double quote char (language specific)
 497       */
 498      public function doublequoteopening() {
 499      }
 500  
 501      /**
 502       * Render an closinging double quote char (language specific)
 503       */
 504      public function doublequoteclosing() {
 505      }
 506  
 507      /**
 508       * Render a CamelCase link
 509       *
 510       * @param string $link The link name
 511       * @see http://en.wikipedia.org/wiki/CamelCase
 512       */
 513      public function camelcaselink($link) {
 514      }
 515  
 516      /**
 517       * Render a page local link
 518       *
 519       * @param string $hash hash link identifier
 520       * @param string $name name for the link
 521       */
 522      public function locallink($hash, $name = null) {
 523      }
 524  
 525      /**
 526       * Render a wiki internal link
 527       *
 528       * @param string       $link  page ID to link to. eg. 'wiki:syntax'
 529       * @param string|array $title name for the link, array for media file
 530       */
 531      public function internallink($link, $title = null) {
 532      }
 533  
 534      /**
 535       * Render an external link
 536       *
 537       * @param string       $link  full URL with scheme
 538       * @param string|array $title name for the link, array for media file
 539       */
 540      public function externallink($link, $title = null) {
 541      }
 542  
 543      /**
 544       * Render the output of an RSS feed
 545       *
 546       * @param string $url    URL of the feed
 547       * @param array  $params Finetuning of the output
 548       */
 549      public function rss($url, $params) {
 550      }
 551  
 552      /**
 553       * Render an interwiki link
 554       *
 555       * You may want to use $this->_resolveInterWiki() here
 556       *
 557       * @param string       $link     original link - probably not much use
 558       * @param string|array $title    name for the link, array for media file
 559       * @param string       $wikiName indentifier (shortcut) for the remote wiki
 560       * @param string       $wikiUri  the fragment parsed from the original link
 561       */
 562      public function interwikilink($link, $title, $wikiName, $wikiUri) {
 563      }
 564  
 565      /**
 566       * Link to file on users OS
 567       *
 568       * @param string       $link  the link
 569       * @param string|array $title name for the link, array for media file
 570       */
 571      public function filelink($link, $title = null) {
 572      }
 573  
 574      /**
 575       * Link to windows share
 576       *
 577       * @param string       $link  the link
 578       * @param string|array $title name for the link, array for media file
 579       */
 580      public function windowssharelink($link, $title = null) {
 581      }
 582  
 583      /**
 584       * Render a linked E-Mail Address
 585       *
 586       * Should honor $conf['mailguard'] setting
 587       *
 588       * @param string $address Email-Address
 589       * @param string|array $name name for the link, array for media file
 590       */
 591      public function emaillink($address, $name = null) {
 592      }
 593  
 594      /**
 595       * Render an internal media file
 596       *
 597       * @param string $src     media ID
 598       * @param string $title   descriptive text
 599       * @param string $align   left|center|right
 600       * @param int    $width   width of media in pixel
 601       * @param int    $height  height of media in pixel
 602       * @param string $cache   cache|recache|nocache
 603       * @param string $linking linkonly|detail|nolink
 604       */
 605      public function internalmedia($src, $title = null, $align = null, $width = null,
 606                             $height = null, $cache = null, $linking = null) {
 607      }
 608  
 609      /**
 610       * Render an external media file
 611       *
 612       * @param string $src     full media URL
 613       * @param string $title   descriptive text
 614       * @param string $align   left|center|right
 615       * @param int    $width   width of media in pixel
 616       * @param int    $height  height of media in pixel
 617       * @param string $cache   cache|recache|nocache
 618       * @param string $linking linkonly|detail|nolink
 619       */
 620      public function externalmedia($src, $title = null, $align = null, $width = null,
 621                             $height = null, $cache = null, $linking = null) {
 622      }
 623  
 624      /**
 625       * Render a link to an internal media file
 626       *
 627       * @param string $src     media ID
 628       * @param string $title   descriptive text
 629       * @param string $align   left|center|right
 630       * @param int    $width   width of media in pixel
 631       * @param int    $height  height of media in pixel
 632       * @param string $cache   cache|recache|nocache
 633       */
 634      public function internalmedialink($src, $title = null, $align = null,
 635                                 $width = null, $height = null, $cache = null) {
 636      }
 637  
 638      /**
 639       * Render a link to an external media file
 640       *
 641       * @param string $src     media ID
 642       * @param string $title   descriptive text
 643       * @param string $align   left|center|right
 644       * @param int    $width   width of media in pixel
 645       * @param int    $height  height of media in pixel
 646       * @param string $cache   cache|recache|nocache
 647       */
 648      public function externalmedialink($src, $title = null, $align = null,
 649                                 $width = null, $height = null, $cache = null) {
 650      }
 651  
 652      /**
 653       * Start a table
 654       *
 655       * @param int $maxcols maximum number of columns
 656       * @param int $numrows NOT IMPLEMENTED
 657       * @param int $pos     byte position in the original source
 658       */
 659      public function table_open($maxcols = null, $numrows = null, $pos = null) {
 660      }
 661  
 662      /**
 663       * Close a table
 664       *
 665       * @param int $pos byte position in the original source
 666       */
 667      public function table_close($pos = null) {
 668      }
 669  
 670      /**
 671       * Open a table header
 672       */
 673      public function tablethead_open() {
 674      }
 675  
 676      /**
 677       * Close a table header
 678       */
 679      public function tablethead_close() {
 680      }
 681  
 682      /**
 683       * Open a table body
 684       */
 685      public function tabletbody_open() {
 686      }
 687  
 688      /**
 689       * Close a table body
 690       */
 691      public function tabletbody_close() {
 692      }
 693  
 694      /**
 695       * Open a table footer
 696       */
 697      public function tabletfoot_open() {
 698      }
 699  
 700      /**
 701       * Close a table footer
 702       */
 703      public function tabletfoot_close() {
 704      }
 705  
 706      /**
 707       * Open a table row
 708       */
 709      public function tablerow_open() {
 710      }
 711  
 712      /**
 713       * Close a table row
 714       */
 715      public function tablerow_close() {
 716      }
 717  
 718      /**
 719       * Open a table header cell
 720       *
 721       * @param int    $colspan
 722       * @param string $align left|center|right
 723       * @param int    $rowspan
 724       */
 725      public function tableheader_open($colspan = 1, $align = null, $rowspan = 1) {
 726      }
 727  
 728      /**
 729       * Close a table header cell
 730       */
 731      public function tableheader_close() {
 732      }
 733  
 734      /**
 735       * Open a table cell
 736       *
 737       * @param int    $colspan
 738       * @param string $align left|center|right
 739       * @param int    $rowspan
 740       */
 741      public function tablecell_open($colspan = 1, $align = null, $rowspan = 1) {
 742      }
 743  
 744      /**
 745       * Close a table cell
 746       */
 747      public function tablecell_close() {
 748      }
 749  
 750      #endregion
 751  
 752      #region util functions, you probably won't need to reimplement them
 753  
 754      /**
 755       * Creates a linkid from a headline
 756       *
 757       * @author Andreas Gohr <andi@splitbrain.org>
 758       * @param string  $title   The headline title
 759       * @param boolean $create  Create a new unique ID?
 760       * @return string
 761       */
 762      public function _headerToLink($title, $create = false) {
 763          if($create) {
 764              return sectionID($title, $this->headers);
 765          } else {
 766              $check = false;
 767              return sectionID($title, $check);
 768          }
 769      }
 770  
 771      /**
 772       * Removes any Namespace from the given name but keeps
 773       * casing and special chars
 774       *
 775       * @author Andreas Gohr <andi@splitbrain.org>
 776       *
 777       * @param string $name
 778       * @return string
 779       */
 780      public function _simpleTitle($name) {
 781          global $conf;
 782  
 783          //if there is a hash we use the ancor name only
 784          list($name, $hash) = sexplode('#', $name, 2);
 785          if($hash) return $hash;
 786  
 787          if($conf['useslash']) {
 788              $name = strtr($name, ';/', ';:');
 789          } else {
 790              $name = strtr($name, ';', ':');
 791          }
 792  
 793          return noNSorNS($name);
 794      }
 795  
 796      /**
 797       * Resolve an interwikilink
 798       *
 799       * @param string    $shortcut  identifier for the interwiki link
 800       * @param string    $reference fragment that refers the content
 801       * @param null|bool $exists    reference which returns if an internal page exists
 802       * @return string interwikilink
 803       */
 804      public function _resolveInterWiki(&$shortcut, $reference, &$exists = null) {
 805          //get interwiki URL
 806          if(isset($this->interwiki[$shortcut])) {
 807              $url = $this->interwiki[$shortcut];
 808          }elseif(isset($this->interwiki['default'])) {
 809              $shortcut = 'default';
 810              $url = $this->interwiki[$shortcut];
 811          }else{
 812              // not parsable interwiki outputs '' to make sure string manipluation works
 813              $shortcut = '';
 814              $url      = '';
 815          }
 816  
 817          //split into hash and url part
 818          $hash = strrchr($reference, '#');
 819          if($hash) {
 820              $reference = substr($reference, 0, -strlen($hash));
 821              $hash = substr($hash, 1);
 822          }
 823  
 824          //replace placeholder
 825          if(preg_match('#\{(URL|NAME|SCHEME|HOST|PORT|PATH|QUERY)\}#', $url)) {
 826              //use placeholders
 827              $url    = str_replace('{URL}', rawurlencode($reference), $url);
 828              //wiki names will be cleaned next, otherwise urlencode unsafe chars
 829              $url    = str_replace('{NAME}', ($url[0] === ':') ? $reference :
 830                                    preg_replace_callback('/[[\\\\\]^`{|}#%]/', function($match) {
 831                                      return rawurlencode($match[0]);
 832                                    }, $reference), $url);
 833              $parsed = parse_url($reference);
 834              if (empty($parsed['scheme'])) $parsed['scheme'] = '';
 835              if (empty($parsed['host'])) $parsed['host'] = '';
 836              if (empty($parsed['port'])) $parsed['port'] = 80;
 837              if (empty($parsed['path'])) $parsed['path'] = '';
 838              if (empty($parsed['query'])) $parsed['query'] = '';
 839              $url = strtr($url,[
 840                  '{SCHEME}' => $parsed['scheme'],
 841                  '{HOST}' => $parsed['host'],
 842                  '{PORT}' => $parsed['port'],
 843                  '{PATH}' => $parsed['path'],
 844                  '{QUERY}' => $parsed['query'] ,
 845              ]);
 846          } else if($url != '') {
 847              // make sure when no url is defined, we keep it null
 848              // default
 849              $url = $url.rawurlencode($reference);
 850          }
 851          //handle as wiki links
 852          if($url && $url[0] === ':') {
 853              $urlparam = '';
 854              $id = $url;
 855              if (strpos($url, '?') !== false) {
 856                  list($id, $urlparam) = sexplode('?', $url, 2, '');
 857              }
 858              $url    = wl(cleanID($id), $urlparam);
 859              $exists = page_exists($id);
 860          }
 861          if($hash) $url .= '#'.rawurlencode($hash);
 862  
 863          return $url;
 864      }
 865  
 866      #endregion
 867  }
 868  
 869  
 870  //Setup VIM: ex: et ts=4 :