Package TWiki::Render

This module provides most of the actual HTML rendering code in TWiki.

On this page:

ClassMethod new ($session)

Creates a new renderer

ObjectMethod finish ()

Break circular references.

ObjectMethod renderParent ($web,$topic,$meta,$params) -> $text

Render parent meta-data

ObjectMethod renderMoved ($web,$topic,$meta,$params) -> $text

Render moved meta-data

StaticMethod chompUtf8Fragment ($str) -> $str

String truncation may happen in the middle of a UTF-8 byte sequence. This function gets rid of the truncated fragment.

ObjectMethod makeAnchorName ($anchorName,$compatibilityMode) -> $anchorName

  • $anchorName - the unprocessed anchor name
  • $compatibilityMode - SMELL: compatibility with what?? Who knows. frown

Build a valid HTML anchor name

ObjectMethod makeUniqueAnchorName ($web,$topic,$anchorName,$compatibility) -> $anchorName

  • $anchorName - the unprocessed anchor name
  • $compatibilityMode - SMELL: compatibility with what?? Who knows. frown

Build a valid HTML anchor name (unique w.r.t. the list stored in %anchornames)

ObjectMethod internalLink ($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel,$theParams) -> $html

Generate a link.

Note: Topic names may be spaced out. Spaced out names are converted to WikWords, for example, "spaced topic name" points to "SpacedTopicName".

  • $theWeb - the web containing the topic
  • $theTopic - the topic to be link
  • $theLinkText - text to use for the link
  • $theAnchor - the link anchor, if any
  • $doLinkToMissingPages - boolean: false means suppress link for non-existing pages
  • $doKeepWeb - boolean: true to keep web prefix (for non existing Web.TOPIC)
  • $hasExplicitLinkLabel - boolean: true in case of explicit link label
  • $theParams - the URL parameters specified by ?name1=value1;name2=valu2;... excluding the leading ?. This is added as per Item7505. This parameter's natural position is before $theAnchor. But to minimize code changes, it's introduced as the laster one

Called by _handleWikiWord and _handleSquareBracketedLink and by Func::internalLink

Calls _renderWikiWord, which in turn will use to match fold plurals to equivalency with their singular form

SMELL: why is this available to Func?

ObjectMethod renderFORMFIELD (%params,$topic,$web) -> $html

Returns the fully rendered expansion of a tag.

ObjectMethod renderEDITFORMFIELD (%params,$topic,$web) -> $html

Returns the fully rendered expansion of a EDITFORMFIELD Error: Required form field name is missing tag.

ObjectMethod getRenderedVersion ($text,$theWeb,$theTopic) -> $html

The main rendering function.

StaticMethod verbatimCallBack

Callback for use with putBackBlocks that replaces < and > by their HTML entities &lt; and &gt;

ObjectMethod TML2PlainText ($text,$web,$topic,$opts) -> $plainText

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.

Defuses TML.


  • showvar - shows %VAR% names if not expanded
  • expandvar - expands %VARS%
  • nohead - strips ---+ headings at the top of the text
  • showmeta - does not filter meta-data
  • entityencode - entity encode the resulting plain text (for title parameter)

ObjectMethod protectPlainText ($text) -> $tml

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.

ObjectMethod makeTopicSummary ($theText,$theTopic,$theWeb,$theFlags) -> $tml

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.

ObjectMethod takeOutBlocks (\$text,$tag,\%map) -> $text

  • $text - Text to process
  • $tag - XHTML-style tag.
  • \%map - Reference to a hash to contain the removed blocks

Return value: $text with blocks removed

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.

Parameters to the open tag are recorded.

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.

ObjectMethod putBackBlocks (\$text,\%map,$tag,$newtag,$callBack) -> $text

Return value: $text with blocks added back

  • \$text - reference to text to process
  • \%map - map placeholders to blocks removed by takeOutBlocks
  • $tag - Tag name processed by takeOutBlocks
  • $newtag - Tag name to use in output, in place of $tag. If undefined, uses $tag.
  • $callback - Reference to function to call on each block being inserted (optional)

Reverses the actions of takeOutBlocks.

Each replaced block is processed by the callback (if there is one) before re-insertion.

Parameters to the outermost cut block are replaced into the open tag, even if that tag is changed. This allows things like <verbatim class=''> to be mapped to <pre class=''>

Cool, eh what? Jolly good show.

And if you set $newtag to '', we replace the taken out block with the valuse itself

  • which i'm using to stop the rendering process, but then at the end put in the html directly (for
Edit | Attach | Watch | Print version | History: r10 < r9 < r8 < r7 < r6 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r10 - 2014-10-05 - TWikiContributor
This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 1999-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on at TWiki:TWiki.TWikiRenderDotPm.