PageRenderTime 69ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 1ms

/www/caches/scripts/StringParcer/doc/en/chapter4.html

http://ds-pro-chat.googlecode.com/
HTML | 164 lines | 163 code | 0 blank | 1 comment | 0 complexity | b486038abcee1ba3c09c0b09845aa6e0 MD5 | raw file
Possible License(s): MIT 
    

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4.   <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    5. 

  5.   <meta http-equiv="Content-Language" content="en">
    6. 

  6.   <title>StringParser_BBCode class documentation</title>
    7. 

  7.   <meta name="author" content="Christian Seiler">
    8. 

  8.   <link rel="stylesheet" href="../css/print.css"  type="text/css" media="print">
    9. 

  9.   <link rel="stylesheet" href="../css/screen.css" type="text/css" media="screen, projection">
    10. 

  10. </head>
    11. 

  11. <body id="doku">
    12. 

  12. <div id="container">
    13. 

  13. <h1><span><code>StringParser_<abbr title="Bulletin Board Code">BBCode</abbr></code> class</span> documentation</h1>
    14. 

  14.  <ul id="mainmenu">
    15. 

  15.   <li><a href="http://www.christian-seiler.de/projekte/php/bbcode/index_en.html">Project homepage</a></li>
    16. 

  16.   <li><a href="chapter1.html">Documentation</a></li>
    17. 

  17.   <li><a href="../phpdoc/index.html">PHPDOC Documentation</a></li>
    18. 

  18.   <li><a href="http://www.christian-seiler.de/projekte/php/bbcode/download_en.html">Download</a></li>
    19. 

  19.   <li><a href="../de/kapitel4.html">Diese Seite auf Deutsch</a></li>
    20. 

  20.  </ul>
    21. 

  21. <ul id="menu">
    22. 

  22.   <li><a href="chapter1.html">1. Introduction</a>
    23. 

  23.     <ul>
    24. 

  24.       <li><a href="chapter1.html#general">1.1 General</a></li>
    25. 

  25.       <li><a href="chapter1.html#nesting">1.2 Nesting</a></li>
    26. 

  26.       <li><a href="chapter1.html#special">1.3 Special codes</a></li>
    27. 

  27.     </ul></li>
    28. 

  28.   <li><a href="chapter2.html">2. Defining own <abbr>BBCode</abbr></a>
    29. 

  29.     <ul>
    30. 

  30.       <li><a href="chapter2.html#including">2.1 Including the class</a></li>
    31. 

  31.       <li><a href="chapter2.html#first">2.2 The first code</a></li>
    32. 

  32.       <li><a href="chapter2.html#processing_types">2.3 Processing types</a></li>
    33. 

  33.       <li><a href="chapter2.html#parsing">2.4 Parsing text</a></li>
    34. 

  34.     </ul></li>
    35. 

  35.   <li><a href="chapter3.html">3. Parser functions</a>
    36. 

  36.     <ul>
    37. 

  37.       <li><a href="chapter3.html#task">3.1 Task of parser functions</a></li>
    38. 

  38.       <li><a href="chapter3.html#content_types">3.2 Relevance of content types</a></li>
    39. 

  39.       <li><a href="chapter3.html#registration">3.3 Registration of parser functions</a></li>
    40. 

  40.     </ul></li>
    41. 

  41.   <li><a href="chapter4.html">4. Callback functions</a>
    42. 

  42.     <ul>
    43. 

  43.       <li><a href="chapter4.html#processing_types">4.1 Processing types that need callback functions</a></li>
    44. 

  44.       <li><a href="chapter4.html#prototype">4.2 Prototype of a callback function</a></li>
    45. 

  45.       <li><a href="chapter4.html#example">4.3 Example for a callback function that replaces links</a></li>
    46. 

  46.       <li><a href="chapter4.html#revalidation">4.4 Revalidation on close tag occurrence</a></li>
    47. 

  47.     </ul></li>
    48. 

  48.   <li><a href="chapter5.html">5. Filters</a>
    49. 

  49.     <ul>
    50. 

  50.       <li><a href="chapter5.html#types">5.1 Filter types</a></li>
    51. 

  51.       <li><a href="chapter5.html#defining">5.2 Defining filters</a></li>
    52. 

  52.     </ul></li>
    53. 

  53.   <li><a href="chapter6.html">6. Flags to control the behaviour of the class</a>
    54. 

  54.     <ul>
    55. 

  55.       <li><a href="chapter6.html#general">6.1 General</a></li>
    56. 

  56.       <li><a href="chapter6.html#flags">6.2 List of all flags</a></li>
    57. 

  57.       <li><a href="chapter6.html#global">6.2 Global flags</a></li>
    58. 

  58.     </ul></li>
    59. 

  59.   <li><a href="chapter7.html">7. Limiting the amount of occurrences</a>
    60. 

  60.     <ul>
    61. 

  61.       <li><a href="chapter7.html#grouping">7.1 Grouping codes</a></li>
    62. 

  62.       <li><a href="chapter7.html#limits">7.2 Setting limits</a></li>
    63. 

  63.     </ul></li>
    64. 

  64.   <li><a href="chapter8.html">8. Paragraph handling</a>
    65. 

  65.     <ul>
    66. 

  66.       <li><a href="chapter8.html#general">8.1 General</a></li>
    67. 

  67.       <li><a href="chapter8.html#activating">8.2 Activating paragraph handling</a></li>
    68. 

  68.       <li><a href="chapter8.html#further">8.3 Further possibilities</a></li>
    69. 

  69.     </ul></li>
    70. 

  70.   <li><a href="chapter9.html">9. Examples</a>
    71. 

  71.     <ul>
    72. 

  72.       <li><a href="chapter9.html#example">9.1 Simple example</a></li>
    73. 

  73. <!--      <li><a href="chapter9.html#complex">9.2 More complex example</a></li> -->
    74. 

  74.     </ul></li>
    75. 

  75.   <li><a href="chapter10.html">10. Miscellaneous</a>
    76. 

  76.     <ul>
    77. 

  77.       <li><a href="chapter10.html#faq">10.1 Frequently asked questions</a></li>
    78. 

  78.       <li><a href="chapter10.html#internals">10.2 Useful internals</a></li>
    79. 

  79.     </ul></li>
    80. 

  80. </ul>
    81. 

  81. <div id="content"><h2>4. Callback functions</h2>
    82. 

  82. <h3 id="processing_types"><a name="processing_types">4.1 Processing types that need callback functions</a></h3>
    83. 

  83. <p>As is already described in the <a href="chapter2.html#first">explanation how to add <abbr>BBCode</abbr></a> there are several processing types that need callback functions to process <abbr>BBCode</abbr>. These are:</p>
    84. 

  84. <ul>
    85. 

  85.   <li><code>callback_replace</code></li>
    86. 

  86.   <li><code>callback_replace_single</code></li>
    87. 

  87.   <li><code>usecontent</code></li>
    88. 

  88.   <li><code>usecontent?</code></li>
    89. 

  89.   <li><code>callback_replace?</code></li>
    90. 

  90. </ul>
    91. 

  91. <p>With all these processing types one must pass the name of a function as a third parameter to the <code>addCode</code> method.
    92. 

  92. <h3 id="prototype"><a name="prototype">4.2 Prototype of a callback function</a></h3>
    93. 

  93. <p>All callback functions must have the following prototype:</p>
    94. 

  94. <p class="php"><code>function name_der_funktion ($action, $attributes, $content, $params, &$node_object) { <br>&nbsp;&nbsp;// do something<br>}</code></p>
    95. 

  95. <p>The following list shows how and when callback functions are called during the processing of <abbr>BBCode</abbr>:</p>
    96. 

  96. <ol>
    97. 

  97.   <li>A <abbr>BBCode</abbr> start tag is found. Name and attributes are extracted from it.</li>
    98. 

  98.   <li>It is determined if the code is allowed here. If not, it is ignored.</li>
    99. 

  99.   <li>The callback function for this <abbr>BBCode</abbr> is called with the <code>$action</code> parameter set to <code>'validate'</code>.</li>
    100. 

  100.   <li>If the callback function has returned <code>false</code> the <abbr>BBCode</abbr> is ignored. If it has returned <code>true</code> the <abbr>BBCode</abbr> is added to the tree structure.</li>
    101. 

  101.   <li>The processing continues.</p>
    102. 

  102.   <li><em>If</em> revalidation is active, the callback function will be called with the <code>$action</code> parameter set to <code>'validate_again'</code> on occurrence of the closing BBCode tag. If the callback function returns <code>false</code> the code will be treated as invalid and everything right after the opening BBCode tag will be processed again.</li>
    103. 

  103.   <li>After the whole text is processed the tree structure is converted back into a string.</li>
    104. 

  104.   <li>During this process the callback function is called again with the <code>$action</code> parameter set to <code>'output'</code>.</li>
    105. 

  105.   <li>The callback function must now return a string that will be used as a replacement for the complete element (including its contents!). If the function returns something other than a string <strong>the complete processing is immediately terminated</strong>.</li>
    106. 

  106. </ol>
    107. 

  107. <p>The parameters that the function must accept are the following:</p>
    108. 

  108. <dl>
    109. 

  109.   <dt><code>$action</code></dt>
    110. 

  110.   <dd>Either <code>'validate'</code> or <code>'output'</code> - see above.</dd>
    111. 

  111.   <dt><code>$attributes</code></dt>
    112. 

  112.   <dd>The attributes that were found in the start tag as an associative array. <code>$attributes['source']</code> e.g. contains the content of the attribute<code>source</code>.</dd>
    113. 

  113.   <dt><code>$content</code></dt>
    114. 

  114.   <dd>The complete content between start and end tag. This value is always set when <code>$action == 'output'</code> where all parser functions were already applied and it is also set if <code>$action == 'validate'</code> and the processing type of the code is <code>usecontent</code> or <code>usecontent?</code>. Please notice that when dealing with these processing types the parser functions will not have been called if <code>$action == 'validate'</code> but will have been called if <code>$action == 'output'</code>.</dd>
    115. 

  115.   <dt><code>$params</code></dt>
    116. 

  116.   <dd>The parameters that were given to the class with the <code>addCode</code> call. The use of these parameters is up to the programmer.</dd>
    117. 

  117.   <dt><code>$node_object</code></dt>
    118. 

  118.   <dd>The object of the type <code>StringParser_BBCode_Node_Element</code> that contains all information on the current node in the tree structure. With this you can access parent and children for example. <strong>Warning:</strong> This object should only be interesting in some very special cases. A manipulation of this object cause unexpected results including infinite loops or similar. <strong>Notice:</strong> If <code>$action == 'validate'</code> the tree is still being built and the node will posess no child nodes yet.</dd>
    119. 

  119. </dl>
    120. 

  120. <h3 id="example"><a name="example">4.3 Example for a callback function that replaces links</a></h3>
    121. 

  121. <p class="php"><code>function <span class="funcn">do_bbcode_url</span> ($action, $attributes, $content, $params, &$node_object) {<br>
    122. 

  122. &nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// 1) the code is being valided</span><br>
    123. 

  123. &nbsp;&nbsp;&nbsp;&nbsp;if ($action == 'validate') {<br>
    124. 

  124. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// the code is specified as follows: [url]http://.../[/url]</span><br>
    125. 

  125. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!isset ($attributes['default'])) {<br>
    126. 

  126. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// is this a valid URL?</span><br>
    127. 

  127. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return is_valid_url ($content);<br>
    128. 

  128. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
    129. 

  129. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// the code is specified as follows: [url=http://.../]Text[/url]</span><br>
    130. 

  130. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// is this a valid URL?</span><br>
    131. 

  131. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return is_valid_url ($attributes['default']);<br>
    132. 

  132. &nbsp;&nbsp;&nbsp;&nbsp;}<br>
    133. 

  133. &nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// 2) the code is being output</span><br>
    134. 

  134. &nbsp;&nbsp;&nbsp;&nbsp;else {<br>
    135. 

  135. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// the code was specified as follows: [url]http://.../[/url]</span><br>
    136. 

  136. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!isset ($attributes['default'])) {<br>
    137. 

  137. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return '&lt;a href=&quot;'.htmlspecialchars ($content).'&quot;&gt;'.htmlspecialchars ($content).'&lt;/a&gt;';<br>
    138. 

  138. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
    139. 

  139. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">// the code was specified as follows: [url=http://.../]Text[/url]</span><br>
    140. 

  140. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return '&lt;a href=&quot;'.htmlspecialchars ($attributes['default']).'&quot;&gt;'.$content.'&lt;/a&gt;';<br>
    141. 

  141. &nbsp;&nbsp;&nbsp;&nbsp;}<br>
    142. 

  142. }<br>
    143. 

  143. <br>
    144. 

  144. <span class="comment">// ...</span><br>
    145. 

  145. <br>
    146. 

  146. $bbcode->addCode ('url', 'usecontent?', <span class="funcn">'do_bbcode_url'</span>, array ('usecontent_param' => 'default'),<br>
    147. 

  147. &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'link', array ('block', 'inline'), array ('link'));</code></p>
    148. 

  148. <p>The above example implies that there is a function <code>is_valid_url</code> that checks if a URL is valid and returns either <code>true</code> or <code>false</code>. One could not perform this type of check and always return <code>true</code> if <code>$action == 'validate'</code>. But this is not recommended as <code>[url]this://is everything else / than a valid url[/url]</code> would also be replaced what would cause error messages in every browser when trying to follow the link.</p>
    149. 

  149. <p>Furthermore in the above example the <code>[url]</code> code has the processing type <code>usecontent?</code> to be able to write normal text between start and end tag that will be the link title if the code is specified in the form <code>[url=http://.../]</code> or that the URL is specified between start and end tag like <code>[url]http://.../[/url]</code>. Depending on the existance of the <code>default</code> attribute the function determines which form the user has chosen.</p>
    150. 

  150. <h3 id="revalidation"><a name="revalidation">4.4 Revalidation on close tag occurrence</a></h3>
    151. 

  151. <p>Normally the callback function is only called with <code>$action == 'validate'</code> set if the opening tag occurs. But it is possible to tell the class to call the callback function again when the closing tag occurs - this time with <code>$action == 'validate_again'</code>. Just call the method <code>setValidateAgain</code>:</p>
    152. 

  152. <p><code>$bbcode->setValidateAgain(true);</code></p>
    153. 

  153. <p>Since <code>usecontent</code> (and for the case that <code>usecontent?</code> or <code>callback_replace?</code> behave like <code>usecontent</code>) the callback function is called at the time the closing tag occurs anyway, this does not apply for that case.</p>
    154. 

  154. <hr>
    155. 

  155. <ul>
    156. 

  156.   <li>Next: <a href="chapter5.html">5. Filters</a></li>
    157. 

  157.   <li>Previous: <a href="chapter3.html">3. Parser functions</a></li>
    158. 

  158. </ul>
    159. 

  159. </div>
    160. 

  160. <p id="footer">This is the documentation for the <code>StringParser_BBCode</code> class version <em>0.3.3</em><br>
    161. 

  161. Author: Christian Seiler, <a href="mailto:webmaster@christian-seiler.de">webmaster@christian-seiler.de</a></p>
    162. 

  162. </div>
    163. 

  163. </body>
    164. 

  164. </html>
    165. 

  165.