Added documentation for callbacks.

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@20289 44c647ce-9c0f-0410-b52a-842ac1e357ba

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

@@ -30,12 +30,11 @@ $bbcode = Zend_Markup::factory('Bbcode');
 // tag, like the tag's group, and (in this case) a start and end tag.
 $bbcode->addTag(
     'foo',
-    Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE
-        | Zend_Markup_Renderer_RendererAbstract::TAG_NORMAL,
+    Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE,
     array(
         'start' => '-bar-',
         'end'   => '-baz-',
-        'group' => 'inline',
+        'group' => 'inline'
     )
 );
 
@@ -48,6 +47,70 @@ echo $bbcode->render('my [foo]tag[/foo]');
             it with a tag structure. Currently, only BBCode supports this. Textile doesn't have
             support for custom tags.
         </para>
+        
+        <para>
+            Some renderers (like the HTML renderer) also have support for a
+            'tag' parameter. This replaces the 'start' and 'end' parameters, and
+            it renders the tags including some default attributes and the
+            closing tag. 
+        </para>
+        
+        <sect3 id="zend.markup.renderers.add.callback">
+            <title>Add a callback tag</title>
+            
+            <para>
+                By adding a callback tag, you can do a lot more then just a
+                simple replace of the tags. For instance, you can change the
+                contents, use the parameters to influence the output etc.
+            </para>
+            
+            <para>
+                A callback is a class that implements the
+                <classname>Zend_Markup_Renderer_TokenInterface</classname>
+                interface. An example of a callback class:
+            </para>
+            
+            <programlisting language="php"><![CDATA[
+class My_Markup_Renderer_Html_Upper extends Zend_Markup_Renderer_TokenConverterInterface
+{
+
+    public function convert(Zend_Markup_Token $token, $text)
+    {
+        return '!up!' . strtoupper($text) . '!up!';
+    }
+
+}
+]]></programlisting>
+
+            <para>
+                Now you can add the 'upper' tag, with as callback, an instance
+                of the <classname>My_Markup_Renderer_Html_Upper</classname>
+                class. A simple example:
+            </para>
+            
+            <programlisting language="php"><![CDATA[
+// Creates instance of Zend_Markup_Renderer_Html,
+// with Zend_Markup_Parser_BbCode as its parser
+$bbcode = Zend_Markup::factory('Bbcode');
+
+// this will create a simple 'foo' tag
+// The first parameter defines the tag's name.
+// The second parameter takes an integer that defines the tags type.
+// The third parameter is an array that defines other things about a
+// tag, like the tag's group, and (in this case) a start and end tag.
+$bbcode->addTag(
+    'upper',
+    Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE,
+    array(
+        'callback' => new My_Markup_Renderer_Html_Upper(),
+        'group'    => 'inline'
+    )
+);
+
+// now, this will output: 'my !up!TAG!up!'
+echo $bbcode->render('my [upper]tag[/upper]');
+]]></programlisting>
+        </sect3>
     </sect2>
     
     <sect2 id="zend.markup.renderers.list">