TWiki/TWikiRenderDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Render="></a> Package =TWiki::Render
   2
   3 This module provides most of the actual HTML rendering code in TWiki.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Package =TWiki::Render="> Package TWiki::Render</a><ul>
   8         <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
   9         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  10         <li><a href="#ObjectMethod <strong>renderParent</strong> ($we"> ObjectMethod renderParent <tt>($web,$topic,$meta,$params) -&gt; $text</tt></a></li>
  11         <li><a href="#ObjectMethod <strong>renderMoved</strong> ($web"> ObjectMethod renderMoved <tt>($web,$topic,$meta,$params) -&gt; $text</tt></a></li>
  12         <li><a href="#ObjectMethod <strong>make_AnchorName</strong> ("> ObjectMethod makeAnchorName <tt>($anchorName,$compatibilityMode) -&gt; $anchorName</tt></a></li>
  13         <li><a href="#ObjectMethod *make_UniqueAnchorN"> ObjectMethod makeUniqueAnchorName <tt>($web,$topic,$anchorName,$compatibility) -&gt; $anchorName</tt></a></li>
  14         <li><a href="#ObjectMethod <strong>internalLink</strong> ($th"> ObjectMethod internalLink <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -&gt; $html</tt></a></li>
  15         <li><a href="#ObjectMethod <strong>renderFORMFIELD</strong> ("> ObjectMethod renderFORMFIELD <tt>(%params,$topic,$web) -&gt; $html</tt></a></li>
  16         <li><a href="#ObjectMethod *get_RenderedVersio"> ObjectMethod getRenderedVersion <tt>($text,$theWeb,$theTopic) -&gt; $html</tt></a></li>
  17         <li><a href="#StaticMethod *verbatim_CallBack*"> StaticMethod verbatimCallBack <tt></tt></a></li>
  18         <li><a href="#ObjectMethod <strong>_TML2PlainText</strong> ($"> ObjectMethod TML2PlainText <tt>($text,$web,$topic,$opts) -&gt; $plainText</tt></a></li>
  19         <li><a href="#ObjectMethod *protect_PlainText*"> ObjectMethod protectPlainText <tt>($text) -&gt; $tml</tt></a></li>
  20         <li><a href="#ObjectMethod *make_TopicSummary*"> ObjectMethod makeTopicSummary <tt>($theText,$theTopic,$theWeb,$theFlags) -&gt; $tml</tt></a></li>
  21         <li><a href="#ObjectMethod <strong>take_OutBlocks</strong> (\"> ObjectMethod takeOutBlocks <tt>(\$text,$tag,\%map) -&gt; $text</tt></a></li>
  22         <li><a href="#ObjectMethod <strong>put_BackBlocks</strong> (\"> ObjectMethod putBackBlocks <tt>(\$text,\%map,$tag,$newtag,$callBack) -&gt; $text</tt></a></li>
  23         <li><a href="#ObjectMethod *render_RevisionInf"> ObjectMethod renderRevisionInfo <tt>($web,$topic,$meta,$rev,$format) -&gt; $string</tt></a></li>
  24         <li><a href="#ObjectMethod *summariseChanges*"> ObjectMethod summariseChanges <tt>($user,$web,$topic,$orev,$nrev,$tml) -&gt; $text</tt></a></li>
  25         <li><a href="#ObjectMethod <strong>for_EachLine</strong> ($te"> ObjectMethod forEachLine <tt>($text,\&amp;fn,\%options) -&gt; $newText</tt></a></li>
  26         <li><a href="#StaticMethod <strong>get_ReferenceRE</strong> ("> StaticMethod getReferenceRE <tt>($web,$topic,%options) -&gt; $re</tt></a></li>
  27         <li><a href="#StaticMethod *replace_TopicRefer"> StaticMethod replaceTopicReferences <tt>($text,\%options) -&gt; $text</tt></a></li>
  28         <li><a href="#StaticMethod *replace_WebReferen"> StaticMethod replaceWebReferences <tt>($text,\%options) -&gt; $text</tt></a></li>
  29         <li><a href="#ObjectMethod *replace_WebInterna"> ObjectMethod replaceWebInternalReferences <tt>(\$text,\%meta,$oldWeb,$oldTopic)</tt></a></li>
  30         <li><a href="#StaticMethod <strong>breakName</strong> ($text,"> StaticMethod breakName <tt>($text,$args) -&gt; $text</tt></a></li>
  31         <li><a href="#StaticMethod *protect_FormFieldV"> StaticMethod protectFormFieldValue <tt>($value,$attrs) -&gt; $html</tt></a></li>
  32       </ul>
  33     </li>
  34   </ul>
  35 </div>
  36
  37 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session)"></a> [[ClassMethod]] **new** `($session)`
  38
  39 Creates a new renderer
  40
  41 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  42
  43 Break circular references.
  44
  45 ## <a name="ObjectMethod &lt;strong&gt;renderParent&lt;/strong&gt; ($we"></a> [[ObjectMethod]] **renderParent** `($web,$topic,$meta,$params) -> $text`
  46
  47 Render parent meta-data
  48
  49 ## <a name="ObjectMethod &lt;strong&gt;renderMoved&lt;/strong&gt; ($web"></a> [[ObjectMethod]] **renderMoved** `($web,$topic,$meta,$params) -> $text`
  50
  51 Render moved meta-data
  52
  53 ## <a name="ObjectMethod &lt;strong&gt;make_AnchorName&lt;/strong&gt; ("></a> [[ObjectMethod]] **makeAnchorName** `($anchorName,$compatibilityMode) -> $anchorName`
  54
  55 - `$anchorName` - the unprocessed anchor name
  56 - `$compatibilityMode` - SMELL: compatibility with **what**?? Who knows. :-(
  57
  58 Build a valid HTML anchor name
  59
  60 ## <a name="ObjectMethod &lt;strong&gt;make_UniqueAnchorN"></a> [[ObjectMethod]] \*makeUniqueAnchorName `($web,$topic,$anchorName,$compatibility) -> $anchorName`
  61
  62 - `$anchorName` - the unprocessed anchor name
  63 - `$compatibilityMode` - SMELL: compatibility with **what**?? Who knows. :-(
  64
  65 Build a valid HTML anchor name (unique w.r.t. the list stored in %anchornames)
  66
  67 ## <a name="ObjectMethod &lt;strong&gt;internalLink&lt;/strong&gt; ($th"></a> [[ObjectMethod]] **internalLink** `($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html`
  68
  69 Generate a link.
  70
  71 Note: Topic names may be spaced out. Spaced out names are converted to WikWords, for example, "spaced topic name" points to "SpacedTopicName".
  72
  73 - `$theWeb` - the web containing the topic
  74 - `$theTopic` - the topic to be link
  75 - `$theLinkText` - text to use for the link
  76 - `$theAnchor` - the link anchor, if any
  77 - `$doLinkToMissingPages` - boolean: false means suppress link for non-existing pages
  78 - `$doKeepWeb` - boolean: true to keep web prefix (for non existing Web.TOPIC)
  79 - `$hasExplicitLinkLabel` - boolean: true in case of [[explicit link label|Main/TopicName]]
  80
  81 Called by \_handleWikiWord and \_handleSquareBracketedLink and by Func::internalLink
  82
  83 Calls \_renderWikiWord, which in turn will use Plurals.pm to match fold plurals to equivalency with their singular form
  84
  85 SMELL: why is this available to Func?
  86
  87 ## <a name="ObjectMethod &lt;strong&gt;renderFORMFIELD&lt;/strong&gt; ("></a> [[ObjectMethod]] **renderFORMFIELD** `(%params,$topic,$web) -> $html`
  88
  89 Returns the fully rendered expansion of a tag.
  90
  91 ## <a name="ObjectMethod &lt;strong&gt;get_RenderedVersio"></a> [[ObjectMethod]] \*getRenderedVersion `($text,$theWeb,$theTopic) -> $html`
  92
  93 The main rendering function.
  94
  95 ## <a name="StaticMethod &lt;strong&gt;verbatim_CallBack*"></a> [[StaticMethod]] \*verbatimCallBack ``
  96
  97 Callback for use with putBackBlocks that replaces &lt; and &gt; by their HTML entities &amp;lt; and &amp;gt;
  98
  99 ## <a name="ObjectMethod &lt;strong&gt;_TML2PlainText&lt;/strong&gt; ($"></a> [[ObjectMethod]] **TML2PlainText** `($text,$web,$topic,$opts) -> $plainText`
 100
 101 Clean up TWiki text for display as plain text without pushing it through the full rendering pipeline. Intended for generation of topic and change summaries. Adds nop tags to prevent TWiki subsequent rendering; nops get removed at the very end.
 102
 103 Defuses TML.
 104
 105 $opts:
 106
 107 - showvar - shows %VAR% names if not expanded
 108 - expandvar - expands %VARS%
 109 - nohead - strips ---+ headings at the top of the text
 110 - showmeta - does not filter meta-data
 111
 112 ## <a name="ObjectMethod &lt;strong&gt;protect_PlainText*"></a> [[ObjectMethod]] \*protectPlainText `($text) -> $tml`
 113
 114 Protect plain text from expansions that would normally be done duing rendering, such as wikiwords. Topic summaries, for example, have to be protected this way.
 115
 116 ## <a name="ObjectMethod &lt;strong&gt;make_TopicSummary*"></a> [[ObjectMethod]] \*makeTopicSummary `($theText,$theTopic,$theWeb,$theFlags) -> $tml`
 117
 118 Makes a plain text summary of the given topic by simply trimming a bit off the top. Truncates to $TMTRUNC chars or, if a number is specified in $theFlags, to that length.
 119
 120 ## <a name="ObjectMethod &lt;strong&gt;take_OutBlocks&lt;/strong&gt; (\"></a> [[ObjectMethod]] **takeOutBlocks** `(\$text,$tag,\%map) -> $text`
 121
 122 - `$text` - Text to process
 123 - `$tag` - XHTML-style tag.
 124 - `\%map` - Reference to a hash to contain the removed blocks
 125
 126 Return value: $text with blocks removed
 127
 128 Searches through $text and extracts blocks delimited by a tag, appending each onto the end of the @buffer and replacing with a token string which is not affected by TWiki rendering. The text after these substitutions is returned.
 129
 130 Parameters to the open tag are recorded.
 131
 132 This is _different_ to takeOutProtected, because it requires tags to be on their own line. it also supports a callback for post- processing the data before re-insertion.
 133
 134 ## <a name="ObjectMethod &lt;strong&gt;put_BackBlocks&lt;/strong&gt; (\"></a> [[ObjectMethod]] **putBackBlocks** `(\$text,\%map,$tag,$newtag,$callBack) -> $text`
 135
 136 Return value: $text with blocks added back
 137
 138 - `\$text` - reference to text to process
 139 - `\%map` - map placeholders to blocks removed by takeOutBlocks
 140 - `$tag` - Tag name processed by takeOutBlocks
 141 - `$newtag` - Tag name to use in output, in place of $tag. If undefined, uses $tag.
 142 - `$callback` - Reference to function to call on each block being inserted (optional)
 143
 144 Reverses the actions of takeOutBlocks.
 145
 146 Each replaced block is processed by the callback (if there is one) before re-insertion.
 147
 148 Parameters to the outermost cut block are replaced into the open tag, even if that tag is changed. This allows things like &lt;verbatim class=''&gt; to be mapped to &lt;pre class=''&gt;
 149
 150 Cool, eh what? Jolly good show.
 151
 152 And if you set $newtag to '', we replace the taken out block with the valuse itself
 153
 154 - which i'm using to stop the rendering process, but then at the end put in the html directly (for tag. ---++ ObjectMethod \*renderRevisionInfo\* `($web,$topic,$meta,$rev,$format) -> $string` Obtain and render revision info for a topic. \* =$web= - the web of the topic \* =$topic= - the topic \* =$meta= if specified, get rev info from here. If not specified, or meta contains rev info for a different version than the one requested, will reload the topic \* =$rev= - the rev number, defaults to latest rev \* =$format= - the render format, defaults to =$rev - $time - $wikiusername= =$format= can contain the following keys for expansion: | =$web= | the web name | | =$topic= | the topic name | | =$rev= | the rev number | | =$comment= | the comment | | =$username= | the login of the saving user | | =$wikiname= | the wikiname of the saving user | | =$wikiusername= | the web.wikiname of the saving user | | =$date= | the date of the rev (no time) | | =$time= | the time of the rev | | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME | ---++ ObjectMethod \*summariseChanges\* `($user,$web,$topic,$orev,$nrev,$tml) -> $text` \* =$user= - user (null to ignore permissions) \* =$web= - web \* =$topic= - topic \* =$orev= - older rev \* =$nrev= - later rev \* =$tml= - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example) Generate a (max 3 line) summary of the differences between the revs. If there is only one rev, a topic summary will be returned. If =$tml= is not set, all HTML will be removed. In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text. ---++ ObjectMethod \*forEachLine\* `($text,\&fn,\%options) -> $newText` Iterate over each line, calling =\\&amp;fn= on each. \\%options may contain: \* =pre= =&gt; true, will call fn for each line in pre blocks \* =verbatim= =&gt; true, will call fn for each line in verbatim blocks \* =literal= =&gt; true, will call fn for each line in literal blocks \* =noautolink= =&gt; true, will call fn for each line in =noautolink= blocks The spec of \\&amp;fn is =sub fn( $line, \\%options ) -&gt; $newLine=. The %options hash passed into this function is passed down to the sub, and the keys =in\_literal=, =in\_pre=, =in\_verbatim= and =in\_noautolink= are set boolean TRUE if the line is from one (or more) of those block types. The return result replaces $line in $newText. ---++ StaticMethod \*getReferenceRE\* `($web,$topic,%options) -> $re` \* $web, $topic - specify the topic being referred to, or web if $topic is undef. \* %options - the following options are available \* =interweb= - if true, then fully web-qualified references are required. \* =grep= - if true, generate a GNU-grep compatible RE instead of the default Perl RE. \* =url= - if set, generates an expression that will match a TWiki URL that points to the web/topic, instead of the default which matches topic links in plain text. Generate a regular expression that can be used to match references to the specified web/topic. Note that the resultant RE will only match fully qualified (i.e. with web specifier) topic names and topic names that are wikiwords in text. Works for spaced-out wikiwords for topic names. The RE returned is designed to be used with =s///= ---++ StaticMethod \*replaceTopicReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace topic references. \\%options contains: \* =oldWeb= =&gt; Web of reference to replace \* =oldTopic= =&gt; Topic of reference to replace \* =newWeb= =&gt; Web of new reference \* =newTopic= =&gt; Topic of new reference \* =inWeb= =&gt; the web which the text we are presently processing resides in \* =fullPaths= =&gt; optional, if set forces all links to full web.topic form For a usage example see TWiki::UI::Manage.pm ---++ StaticMethod \*replaceWebReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace web references. \\%options contains: \* =oldWeb= =&gt; Web of reference to replace \* =newWeb= =&gt; Web of new reference For a usage example see TWiki::UI::Manage.pm ---++ ObjectMethod \*replaceWebInternalReferences\* `(\$text,\%meta,$oldWeb,$oldTopic)` Change within-web wikiwords in $$text and $meta to full web.topic syntax. \\%options must include topics =&gt; list of topics that must have references to them changed to include the web specifier. ---++ StaticMethod \*breakName\* `($text,$args) -> $text` \* =$text= - text to "break" \* =$args= - string of format (\\d+)([,\\s\*]\\.\\.\\.)?) Hyphenates $text every $1 characters, or if $2 is "..." then shortens to $1 characters and appends "..." (making the final string $1+3 characters long) \_Moved from Search.pm because it was obviously unhappy there, as it is a rendering function\_ ---++ StaticMethod \*protectFormFieldValue\* `($value,$attrs) -> $html` Given the value of a form field, and a set of attributes that control how to display that value, protect the value from further processing. The protected value is determined from the value of the field after: \* newlines are replaced with &lt;br&gt; or the value of $attrs-&gt;\{newline\} \* processing through breakName if $attrs-&gt;\{break\} is defined \* escaping of $vars if $attrs-&gt;\{protectdollar\} is defined \* | is replaced with &amp;#124; or the value of $attrs-&gt;\{bar\} if defined