documentation/manual/en/module_specs/Zend_Markup-Renderers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.markup.renderers">
   4     <title>Zend_Markup Renderers</title>
   5
   6     <para>
   7         <classname>Zend_Markup</classname> is currently shipped with one renderer, the
   8         <acronym>HTML</acronym> renderer.
   9     </para>
  10
  11     <sect2 id="zend.markup.renderers.add">
  12         <title>Adding your own markups</title>
  13
  14         <para>
  15             By adding your own markups, you can add your own functionality to the
  16             <classname>Zend_Markup</classname> renderers. With the markup structure, you can add
  17             about any functionality you want. From simple markups, to complicated markup structures.
  18             A simple example for a 'foo' markup:
  19         </para>
  20
  21         <programlisting language="php"><![CDATA[
  22 // Creates instance of Zend_Markup_Renderer_Html,
  23 // with Zend_Markup_Parser_BbCode as its parser
  24 $bbcode = Zend_Markup::factory('Bbcode');
  25
  26 // this will create a simple 'foo' markup
  27 // The first parameter defines the markup's name.
  28 // The second parameter takes an integer that defines the markups type.
  29 // The third parameter is an array that defines other things about a
  30 // markup, like the markup's group, and (in this case) a start and end markup.
  31 $bbcode->addMarkup(
  32     'foo',
  33     Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE,
  34     array(
  35         'start' => '-bar-',
  36         'end'   => '-baz-',
  37         'group' => 'inline'
  38     )
  39 );
  40
  41 // now, this will output: 'my -bar-markup-baz-'
  42 echo $bbcode->render('my [foo]markup[/foo]');
  43 ]]></programlisting>
  44
  45         <para>
  46             Please note that creating your own markups only makes sense when your parser also
  47             supports it with a markup structure. Currently, only BBCode supports this. Textile
  48             doesn't have support for custom markups.
  49         </para>
  50
  51         <para>
  52             Some renderers (like the <acronym>HTML</acronym> renderer) also have support for a
  53             'markup' parameter. This replaces the 'start' and 'end' parameters, and
  54             it renders the markups including some default attributes and the
  55             closing markup.
  56         </para>
  57
  58         <sect3 id="zend.markup.renderers.add.callback">
  59             <title>Add a callback markup</title>
  60
  61             <para>
  62                 By adding a callback markup, you can do a lot more then just a
  63                 simple replace of the markups. For instance, you can change the
  64                 contents, use the parameters to influence the output etc.
  65             </para>
  66
  67             <para>
  68                 A callback is a class that implements the
  69                 <classname>Zend_Markup_Renderer_TokenInterface</classname>
  70                 interface. An example of a callback class:
  71             </para>
  72
  73             <programlisting language="php"><![CDATA[
  74 class My_Markup_Renderer_Html_Upper
  75     implements Zend_Markup_Renderer_TokenConverterInterface
  76 {
  77
  78     public function convert(Zend_Markup_Token $token, $text)
  79     {
  80         return '!up!' . strtoupper($text) . '!up!';
  81     }
  82
  83 }
  84 ]]></programlisting>
  85
  86             <para>
  87                 Now you can add the 'upper' markup, with as callback, an instance
  88                 of the <classname>My_Markup_Renderer_Html_Upper</classname>
  89                 class. A simple example:
  90             </para>
  91
  92             <programlisting language="php"><![CDATA[
  93 // Creates instance of Zend_Markup_Renderer_Html,
  94 // with Zend_Markup_Parser_BbCode as its parser
  95 $bbcode = Zend_Markup::factory('Bbcode');
  96
  97 // this will create a simple 'foo' markup
  98 // The first parameter defines the markup's name.
  99 // The second parameter takes an integer that defines the markups type.
 100 // The third parameter is an array that defines other things about a
 101 // markup, like the markup's group, and (in this case) a start and end markup.
 102 $bbcode->addMarkup(
 103     'upper',
 104     Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE,
 105     array(
 106         'callback' => new My_Markup_Renderer_Html_Upper(),
 107         'group'    => 'inline'
 108     )
 109 );
 110
 111 // now, this will output: 'my !up!MARKUP!up!'
 112 echo $bbcode->render('my [upper]markup[/upper]');
 113 ]]></programlisting>
 114         </sect3>
 115     </sect2>
 116
 117     <sect2 id="zend.markup.renderers.list">
 118         <title>List of markups</title>
 119
 120         <table id="zend.markup.renderers.list.markups">
 121             <title>List of markups</title>
 122
 123             <tgroup cols="2" align="left" colsep="1" rowsep="1">
 124                 <thead>
 125                     <row>
 126                         <entry>Sample input (bbcode)</entry>
 127                         <entry>Sample output</entry>
 128                     </row>
 129                 </thead>
 130
 131                 <tbody>
 132                     <row>
 133                         <entry>[b]foo[/b]</entry>
 134                         <entry><![CDATA[<strong>foo</strong>]]></entry>
 135                     </row>
 136
 137                     <row>
 138                         <entry>[i]foo[/i]</entry>
 139                         <entry><![CDATA[<em>foo</em>]]></entry>
 140                     </row>
 141
 142                     <row>
 143                         <entry>[cite]foo[/cite]</entry>
 144                         <entry><![CDATA[<cite>foo</cite>]]></entry>
 145                     </row>
 146
 147                     <row>
 148                         <entry>[del]foo[/del]</entry>
 149                         <entry><![CDATA[<del>foo</del>]]></entry>
 150                     </row>
 151
 152                     <row>
 153                         <entry>[ins]foo[/ins]</entry>
 154                         <entry><![CDATA[<ins>foo</ins>]]></entry>
 155                     </row>
 156
 157                     <row>
 158                         <entry>[sup]foo[/sup]</entry>
 159                         <entry><![CDATA[<sup>foo</sup>]]></entry>
 160                     </row>
 161
 162                     <row>
 163                         <entry>[sub]foo[/sub]</entry>
 164                         <entry><![CDATA[<sub>foo</sub>]]></entry>
 165                     </row>
 166
 167                     <row>
 168                         <entry>[span]foo[/span]</entry>
 169                         <entry><![CDATA[<span>foo</span>]]></entry>
 170                     </row>
 171
 172                     <row>
 173                         <entry>[acronym title="PHP Hypertext Preprocessor]PHP[/acronym]</entry>
 174
 175                         <entry>
 176                             <![CDATA[<acronym title="PHP Hypertext Preprocessor">PHP</acronym>]]>
 177                         </entry>
 178                     </row>
 179
 180                     <row>
 181                         <entry>[url=http://framework.zend.com/]Zend Framework[/url]</entry>
 182
 183                         <entry>
 184                             <![CDATA[<a href="http://framework.zend.com/">Zend Framework</a>]]>
 185                         </entry>
 186                     </row>
 187
 188                     <row>
 189                         <entry>[h1]foobar[/h1]</entry>
 190                         <entry><![CDATA[<h1>foobar</h1>]]></entry>
 191                     </row>
 192
 193                     <row>
 194                         <entry>[img]http://framework.zend.com/images/logo.gif[/img]</entry>
 195
 196                         <entry>
 197                             <![CDATA[<img src="http://framework.zend.com/images/logo.gif" />]]>
 198                         </entry>
 199                     </row>
 200                 </tbody>
 201             </tgroup>
 202         </table>
 203     </sect2>
 204 </sect1>