1 <?php

     2 /**

     3  * Zend Framework

     4  *

     5  * LICENSE

     6  *

     7  * This source file is subject to the new BSD license that is bundled

     8  * with this package in the file LICENSE.txt.

     9  * It is also available through the world-wide-web at this URL:

    10  * http://framework.zend.com/license/new-bsd

    11  * If you did not receive a copy of the license and are unable to

    12  * obtain it through the world-wide-web, please send an email

    13  * to license@zend.com so we can send you a copy immediately.

    14  *

    15  * @category   Zend

    16  * @package    Zend_Markup

    17  * @subpackage Renderer

    18  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    19  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    20  * @version    $Id: RendererAbstract.php 22197 2010-05-19 13:32:25Z kokx $

    21  */

    22 

    23 /**

    24  * @see Zend_config

    25  */

    26 require_once 'Zend/Config.php';

    27 /**

    28  * @see Zend_Filter

    29  */

    30 require_once 'Zend/Filter.php';

    31 /**

    32  * @see Zend_Markup_Renderer_TokenConverterInterface

    33  */

    34 require_once 'Zend/Markup/Renderer/TokenConverterInterface.php';

    35 

    36 /**

    37  * Defines the basic rendering functionality

    38  *

    39  * @category   Zend

    40  * @package    Zend_Markup

    41  * @subpackage Renderer

    42  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    43  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    44  */

    45 abstract class Zend_Markup_Renderer_RendererAbstract

    46 {

    47     const TYPE_CALLBACK = 4;

    48     const TYPE_REPLACE  = 8;

    49     const TYPE_ALIAS    = 16;

    50 

    51     /**

    52      * Tag info

    53      *

    54      * @var array

    55      */

    56     protected $_markups = array();

    57 

    58     /**

    59      * Parser

    60      *

    61      * @var Zend_Markup_Parser_ParserInterface

    62      */

    63     protected $_parser;

    64 

    65     /**

    66      * What filter to use

    67      *

    68      * @var bool

    69      */

    70     protected $_filter;

    71 

    72     /**

    73      * Filter chain

    74      *

    75      * @var Zend_Filter

    76      */

    77     protected $_defaultFilter;

    78 

    79     /**

    80      * The current group

    81      *

    82      * @var string

    83      */

    84     protected $_group;

    85 

    86     /**

    87      * Groups definition

    88      *

    89      * @var array

    90      */

    91     protected $_groups = array();

    92 

    93     /**

    94      * Plugin loader for tags

    95      *

    96      * @var Zend_Loader_PluginLoader

    97      */

    98     protected $_pluginLoader;

    99 

   100     /**

   101      * The current token

   102      *

   103      * @var Zend_Markup_Token

   104      */

   105     protected $_token;

   106 

   107     /**

   108      * Encoding

   109      *

   110      * @var string

   111      */

   112     protected static $_encoding = 'UTF-8';

   113 

   114 

   115     /**

   116      * Constructor

   117      *

   118      * @param array|Zend_Config $options

   119      *

   120      * @return void

   121      */

   122     public function __construct($options = array())

   123     {

   124         if ($options instanceof Zend_Config) {

   125             $options = $options->toArray();

   126         }

   127 

   128         if (isset($options['encoding'])) {

   129             $this->setEncoding($options['encoding']);

   130         }

   131         if (isset($options['parser'])) {

   132             $this->setParser($options['parser']);

   133         }

   134         if (!isset($options['useDefaultFilters']) || ($options['useDefaultFilters'] === true)) {

   135             $this->addDefaultFilters();

   136         }

   137         if (isset($options['defaultFilter'])) {

   138             $this->addDefaultFilter($options['defaultFilter']);

   139         }

   140     }

   141 

   142     /**

   143      * Set the parser

   144      *

   145      * @param  Zend_Markup_Parser_ParserInterface $parser

   146      * @return Zend_Markup_Renderer_RendererAbstract

   147      */

   148     public function setParser(Zend_Markup_Parser_ParserInterface $parser)

   149     {

   150         $this->_parser = $parser;

   151         return $this;

   152     }

   153 

   154     /**

   155      * Get the parser

   156      *

   157      * @return Zend_Markup_Parser_ParserInterface

   158      */

   159     public function getParser()

   160     {

   161         return $this->_parser;

   162     }

   163 

   164     /**

   165      * Get the plugin loader

   166      *

   167      * @return Zend_Loader_PluginLoader

   168      */

   169     public function getPluginLoader()

   170     {

   171         return $this->_pluginLoader;

   172     }

   173 

   174     /**

   175      * Set the renderer's encoding

   176      *

   177      * @param string $encoding

   178      *

   179      * @return void

   180      */

   181     public static function setEncoding($encoding)

   182     {

   183         self::$_encoding = $encoding;

   184     }

   185 

   186     /**

   187      * Get the renderer's encoding

   188      *

   189      * @return string

   190      */

   191     public static function getEncoding()

   192     {

   193         return self::$_encoding;

   194     }

   195 

   196     /**

   197      * Add a new markup

   198      *

   199      * @param string $name

   200      * @param string $type

   201      * @param array $options

   202      *

   203      * @return Zend_Markup_Renderer_RendererAbstract

   204      */

   205     public function addMarkup($name, $type, array $options)

   206     {

   207         if (!isset($options['group']) && ($type ^ self::TYPE_ALIAS)) {

   208             require_once 'Zend/Markup/Renderer/Exception.php';

   209             throw new Zend_Markup_Renderer_Exception("There is no render group defined.");

   210         }

   211 

   212         // add the filter

   213         if (isset($options['filter'])) {

   214             if ($options['filter'] instanceof Zend_Filter_Interface) {

   215                 $filter = $options['filter'];

   216             } elseif ($options['filter'] === true) {

   217                 $filter = $this->getDefaultFilter();

   218             } else {

   219                 $filter = false;

   220             }

   221         } else {

   222             $filter = $this->getDefaultFilter();

   223         }

   224 

   225         // check the type

   226         if ($type & self::TYPE_CALLBACK) {

   227             // add a callback tag

   228             if (isset($options['callback'])) {

   229                 if (!($options['callback'] instanceof Zend_Markup_Renderer_TokenConverterInterface)) {

   230                     require_once 'Zend/Markup/Renderer/Exception.php';

   231                     throw new Zend_Markup_Renderer_Exception("Not a valid tag callback.");

   232                 }

   233                 if (method_exists($options['callback'], 'setRenderer')) {

   234                     $options['callback']->setRenderer($this);

   235                 }

   236             } else {

   237                 $options['callback'] = null;

   238             }

   239 

   240             $options['type'] = $type;

   241             $options['filter'] = $filter;

   242 

   243             $this->_markups[$name] = $options;

   244         } elseif ($type & self::TYPE_ALIAS) {

   245             // add an alias

   246             if (empty($options['name'])) {

   247                 require_once 'Zend/Markup/Renderer/Exception.php';

   248                 throw new Zend_Markup_Renderer_Exception(

   249                         'No alias was provided but tag was defined as such');

   250             }

   251 

   252             $this->_markups[$name] = array(

   253                 'type' => self::TYPE_ALIAS,

   254                 'name' => $options['name']

   255             );

   256         } else {

   257             if ($type && array_key_exists('empty', $options) && $options['empty']) {

   258                 // add a single replace markup

   259                 $options['type']   = $type;

   260                 $options['filter'] = $filter;

   261 

   262                 $this->_markups[$name] = $options;

   263             } else {

   264                 // add a replace markup

   265                 $options['type']   = $type;

   266                 $options['filter'] = $filter;

   267 

   268                 $this->_markups[$name] = $options;

   269             }

   270         }

   271         return $this;

   272     }

   273 

   274     /**

   275      * Remove a markup

   276      *

   277      * @param string $name

   278      *

   279      * @return void

   280      */

   281     public function removeMarkup($name)

   282     {

   283         unset($this->_markups[$name]);

   284     }

   285 

   286     /**

   287      * Remove the default tags

   288      *

   289      * @return void

   290      */

   291     public function clearMarkups()

   292     {

   293         $this->_markups = array();

   294     }

   295 

   296     /**

   297      * Render function

   298      *

   299      * @param  Zend_Markup_TokenList|string $tokenList

   300      * @return string

   301      */

   302     public function render($value)

   303     {

   304         if ($value instanceof Zend_Markup_TokenList) {

   305             $tokenList = $value;

   306         } else {

   307             $tokenList = $this->getParser()->parse($value);

   308         }

   309 

   310         $root = $tokenList->current();

   311 

   312         $this->_filter = $this->getDefaultFilter();

   313 

   314         return $this->_render($root);

   315     }

   316 

   317     /**

   318      * Render a single token

   319      *

   320      * @param  Zend_Markup_Token $token

   321      * @return string

   322      */

   323     protected function _render(Zend_Markup_Token $token)

   324     {

   325         $return    = '';

   326 

   327         $this->_token = $token;

   328 

   329         // if this tag has children, execute them

   330         if ($token->hasChildren()) {

   331             foreach ($token->getChildren() as $child) {

   332                 $return .= $this->_execute($child);

   333             }

   334         }

   335 

   336         return $return;

   337     }

   338 

   339     /**

   340      * Get the group of a token

   341      *

   342      * @param  Zend_Markup_Token $token

   343      * @return string|bool

   344      */

   345     protected function _getGroup(Zend_Markup_Token $token)

   346     {

   347         if (!isset($this->_markups[$token->getName()])) {

   348             return false;

   349         }

   350 

   351         $tag = $this->_markups[$token->getName()];

   352 

   353         // alias processing

   354         while ($tag['type'] & self::TYPE_ALIAS) {

   355             $tag = $this->_markups[$tag['name']];

   356         }

   357 

   358         return isset($tag['group']) ? $tag['group'] : false;

   359     }

   360 

   361     /**

   362      * Execute the token

   363      *

   364      * @param  Zend_Markup_Token $token

   365      * @return string

   366      */

   367     protected function _execute(Zend_Markup_Token $token)

   368     {

   369         // first return the normal text tags

   370         if ($token->getType() == Zend_Markup_Token::TYPE_NONE) {

   371             return $this->_filter($token->getTag());

   372         }

   373 

   374         // if the token doesn't have a notation, return the plain text

   375         if (!isset($this->_markups[$token->getName()])) {

   376             $oldToken  = $this->_token;

   377             $return = $this->_filter($token->getTag()) . $this->_render($token) . $token->getStopper();

   378             $this->_token = $oldToken;

   379             return $return;

   380         }

   381 

   382         $name   = $this->_getMarkupName($token);

   383         $markup = (!$name) ? false : $this->_markups[$name];

   384         $empty  = (is_array($markup) && array_key_exists('empty', $markup) && $markup['empty']);

   385 

   386         // check if the tag has content

   387         if (!$empty && !$token->hasChildren()) {

   388             return '';

   389         }

   390 

   391         // check for the context

   392         if (is_array($markup) && !in_array($markup['group'], $this->_groups[$this->_group])) {

   393             $oldToken = $this->_token;

   394             $return   = $this->_filter($token->getTag()) . $this->_render($token) . $token->getStopper();

   395             $this->_token = $oldToken;

   396             return $return;

   397         }

   398 

   399         // check for the filter

   400         if (!isset($markup['filter'])

   401             || (!($markup['filter'] instanceof Zend_Filter_Interface) && ($markup['filter'] !== false))) {

   402             $this->_markups[$name]['filter'] = $this->getDefaultFilter();

   403         }

   404 

   405         // save old values to reset them after the work is done

   406         $oldFilter = $this->_filter;

   407         $oldGroup  = $this->_group;

   408 

   409         $return = '';

   410 

   411         // set the filter and the group

   412         $this->_filter = $this->getFilter($name);

   413 

   414         if ($group = $this->_getGroup($token)) {

   415             $this->_group = $group;

   416         }

   417 

   418         // callback

   419         if (is_array($markup) && ($markup['type'] & self::TYPE_CALLBACK)) {

   420             // load the callback if the tag doesn't exist

   421             if (!($markup['callback'] instanceof Zend_Markup_Renderer_TokenConverterInterface)) {

   422                 $class = $this->getPluginLoader()->load($name);

   423 

   424                 $markup['callback'] = new $class;

   425 

   426                 if (!($markup['callback'] instanceof Zend_Markup_Renderer_TokenConverterInterface)) {

   427                     require_once 'Zend/Markup/Renderer/Exception.php';

   428                     throw new Zend_Markup_Renderer_Exception("Callback for tag '$name' found, but it isn't valid.");

   429                 }

   430 

   431                 if (method_exists($markup['callback'], 'setRenderer')) {

   432                     $markup['callback']->setRenderer($this);

   433                 }

   434             }

   435             if ($markup['type'] && !$empty) {

   436                 $return = $markup['callback']->convert($token, $this->_render($token));

   437             } else {

   438                 $return = $markup['callback']->convert($token, null);

   439             }

   440         } else {

   441             // replace

   442             if ($markup['type'] && !$empty) {

   443                 $return = $this->_executeReplace($token, $markup);

   444             } else {

   445                 $return = $this->_executeSingleReplace($token, $markup);

   446             }

   447         }

   448 

   449         // reset to the old values

   450         $this->_filter = $oldFilter;

   451         $this->_group  = $oldGroup;

   452 

   453         return $return;

   454     }

   455 

   456     /**

   457      * Filter method

   458      *

   459      * @param string $value

   460      *

   461      * @return string

   462      */

   463     protected function _filter($value)

   464     {

   465         if ($this->_filter instanceof Zend_Filter_Interface) {

   466             return $this->_filter->filter($value);

   467         }

   468         return $value;

   469     }

   470 

   471     /**

   472      * Get the markup name

   473      *

   474      * @param Zend_Markup_Token

   475      *

   476      * @return string

   477      */

   478     protected function _getMarkupName(Zend_Markup_Token $token)

   479     {

   480         $name = $token->getName();

   481         if (empty($name)) {

   482             return false;

   483         }

   484 

   485         return $this->_resolveMarkupName($name);

   486     }

   487 

   488     /**

   489      * Resolve aliases for a markup name

   490      *

   491      * @param string $name

   492      *

   493      * @return string

   494      */

   495     protected function _resolveMarkupName($name)

   496     {

   497         while (($type = $this->_getMarkupType($name))

   498                && ($type & self::TYPE_ALIAS)

   499         ) {

   500             $name = $this->_markups[$name]['name'];

   501         }

   502 

   503         return $name;

   504     }

   505 

   506     /**

   507      * Retrieve markup type

   508      *

   509      * @param  string $name

   510      * @return false|int

   511      */

   512     protected function _getMarkupType($name)

   513     {

   514         if (!isset($this->_markups[$name])) {

   515             return false;

   516         }

   517         if (!isset($this->_markups[$name]['type'])) {

   518             return false;

   519         }

   520         return $this->_markups[$name]['type'];

   521     }

   522 

   523     /**

   524      * Execute a replace token

   525      *

   526      * @param  Zend_Markup_Token $token

   527      * @param  array $tag

   528      * @return string

   529      */

   530     protected function _executeReplace(Zend_Markup_Token $token, $tag)

   531     {

   532         return $tag['start'] . $this->_render($token) . $tag['end'];

   533     }

   534 

   535     /**

   536      * Execute a single replace token

   537      *

   538      * @param  Zend_Markup_Token $token

   539      * @param  array $tag

   540      * @return string

   541      */

   542     protected function _executeSingleReplace(Zend_Markup_Token $token, $tag)

   543     {

   544         return $tag['replace'];

   545     }

   546 

   547     /**

   548      * Get the default filter

   549      *

   550      * @return void

   551      */

   552     public function getDefaultFilter()

   553     {

   554         if (null === $this->_defaultFilter) {

   555             $this->addDefaultFilters();

   556         }

   557 

   558         return $this->_defaultFilter;

   559     }

   560 

   561     /**

   562      * Add a default filter

   563      *

   564      * @param string $filter

   565      *

   566      * @return void

   567      */

   568     public function addDefaultFilter(Zend_Filter_Interface $filter, $placement = Zend_Filter::CHAIN_APPEND)

   569     {

   570         if (!($this->_defaultFilter instanceof Zend_Filter)) {

   571             $defaultFilter = new Zend_Filter();

   572             $defaultFilter->addFilter($filter);

   573             $this->_defaultFilter = $defaultFilter;

   574         }

   575 

   576         $this->_defaultFilter->addFilter($filter, $placement);

   577     }

   578 

   579     /**

   580      * Set the default filter

   581      *

   582      * @param Zend_Filter_Interface $filter

   583      *

   584      * @return void

   585      */

   586     public function setDefaultFilter(Zend_Filter_Interface $filter)

   587     {

   588         $this->_defaultFilter = $filter;

   589     }

   590 

   591     /**

   592      * Get the filter for an existing markup

   593      *

   594      * @param string $markup

   595      *

   596      * @return Zend_Filter_Interface

   597      */

   598     public function getFilter($markup)

   599     {

   600         $markup = $this->_resolveMarkupName($markup);

   601 

   602         if (!isset($this->_markups[$markup]['filter'])

   603             || !($this->_markups[$markup]['filter'] instanceof Zend_Filter_Interface)

   604         ) {

   605             if (isset($this->_markups[$markup]['filter']) && $this->_markups[$markup]['filter']) {

   606                 $this->_markups[$markup]['filter'] = $this->getDefaultFilter();

   607             } else {

   608                 return false;

   609             }

   610         }

   611 

   612         return $this->_markups[$markup]['filter'];

   613     }

   614 

   615     /**

   616      * Add a filter for an existing markup

   617      *

   618      * @param Zend_Filter_Interface $filter

   619      * @param string $markup

   620      * @param string $placement

   621      *

   622      * @return Zend_Markup_Renderer_RendererAbstract

   623      */

   624     public function addFilter(Zend_Filter_Interface $filter, $markup, $placement = Zend_Filter::CHAIN_APPEND)

   625     {

   626         $markup = $this->_resolveMarkupName($markup);

   627 

   628         $oldFilter = $this->getFilter($markup);

   629 

   630         // if this filter is the default filter, clone it first

   631         if ($oldFilter === $this->getDefaultFilter()) {

   632             $oldFilter = clone $oldFilter;

   633         }

   634 

   635         if (!($oldFilter instanceof Zend_Filter)) {

   636             $this->_markups[$markup]['filter'] = new Zend_Filter();

   637 

   638             if ($oldFilter instanceof Zend_Filter_Interface) {

   639                 $this->_markups[$markup]['filter']->addFilter($oldFilter);

   640             }

   641         } else {

   642             $this->_markups[$markup]['filter'] = $oldFilter;

   643         }

   644 

   645         $this->_markups[$markup]['filter']->addFilter($filter, $placement);

   646 

   647         return $this;

   648     }

   649 

   650     /**

   651      * Set the filter for an existing

   652      *

   653      * @param Zend_Filter_Interface $filter

   654      * @param string $markup

   655      *

   656      * @return Zend_Markup_Renderer_RendererAbstract

   657      */

   658     public function setFilter(Zend_Filter_Interface $filter, $markup)

   659     {

   660         $markup = $this->_resolveMarkupName($markup);

   661 

   662         $this->_markups[$markup]['filter'] = $filter;

   663 

   664         return $this;

   665     }

   666 

   667     /**

   668      * Add a render group

   669      *

   670      * @param string $name

   671      * @param array $allowedInside

   672      * @param array $allowsInside

   673      *

   674      * @return void

   675      */

   676     public function addGroup($name, array $allowedInside = array(), array $allowsInside = array())

   677     {

   678         $this->_groups[$name] = $allowsInside;

   679 

   680         foreach ($allowedInside as $group) {

   681             $this->_groups[$group][] = $name;

   682         }

   683     }

   684 

   685     /**

   686      * Get group definitions

   687      *

   688      * @return array

   689      */

   690     public function getGroups()

   691     {

   692         return $this->_groups;

   693     }

   694 

   695     /**

   696      * Set the default filters

   697      *

   698      * @return void

   699      */

   700     abstract public function addDefaultFilters();

   701 

   702 }