data/TWiki/TWikiRenderDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Mon, 11 Aug 2008 20:33:37 +0200
changeset 2 7bc60a767fa4
parent 0 414e01d06fd5
permissions -rw-r--r--
TWiki-4.2.2 Release
     1 head	1.5;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.5
     9 date	2008.01.22.03.21.32;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.4;
    12 
    13 1.4
    14 date	2007.03.03.14.51.47;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.3;
    17 
    18 1.3
    19 date	2007.02.05.00.18.34;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	1.2;
    22 
    23 1.2
    24 date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
    25 branches;
    26 next	1.1;
    27 
    28 1.1
    29 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    30 branches;
    31 next	;
    32 
    33 
    34 desc
    35 @new-topic
    36 @
    37 
    38 
    39 1.5
    40 log
    41 @buildrelease
    42 @
    43 text
    44 @---+ Package =TWiki::Render=
    45 
    46 This module provides most of the actual HTML rendering code in TWiki.
    47 
    48 
    49 %TOC%
    50 
    51 ---++ ClassMethod *new* <tt>($session)</tt>
    52 
    53 Creates a new renderer
    54 
    55 
    56 
    57 ---++ ObjectMethod *finish* <tt>()</tt>
    58 Break circular references.
    59 
    60 
    61 
    62 ---++ ObjectMethod *renderParent* <tt>($web,$topic,$meta,$params) -> $text</tt>
    63 
    64 Render parent meta-data
    65 
    66 
    67 
    68 ---++ ObjectMethod *renderMoved* <tt>($web,$topic,$meta,$params) -> $text</tt>
    69 
    70 Render moved meta-data
    71 
    72 
    73 
    74 ---++ ObjectMethod *makeAnchorName* <tt>($anchorName,$compatibilityMode) -> $anchorName</tt>
    75 
    76    * =$anchorName= - the unprocessed anchor name
    77    * =$compatibilityMode= - SMELL: compatibility with *what*?? Who knows. :-(
    78 
    79 Build a valid HTML anchor name
    80 
    81 
    82 
    83 ---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html</tt>
    84 
    85 Generate a link. 
    86 
    87 Note: Topic names may be spaced out. Spaced out names are converted to <nop>WikWords,
    88 for example, "spaced topic name" points to "SpacedTopicName".
    89    * =$theWeb= - the web containing the topic
    90    * =$theTopic= - the topic to be link
    91    * =$theLinkText= - text to use for the link
    92    * =$theAnchor= - the link anchor, if any
    93    * =$doLinkToMissingPages= - boolean: false means suppress link for non-existing pages
    94    * =$doKeepWeb= - boolean: true to keep web prefix (for non existing Web.TOPIC)
    95    * =$hasExplicitLinkLabel= - boolean: true in case of [[TopicName][explicit link label]] 
    96 
    97 Called by _handleWikiWord and _handleSquareBracketedLink and by Func::internalLink
    98 
    99 Calls _renderWikiWord, which in turn will use Plurals.pm to match fold plurals to equivalency with their singular form 
   100 
   101 SMELL: why is this available to Func?
   102 
   103 
   104 
   105 ---++ ObjectMethod *renderFORMFIELD* <tt>(%params,$topic,$web) -> $html</tt>
   106 
   107 Returns the fully rendered expansion of a %FORMFIELD{}% tag.
   108 
   109 
   110 
   111 ---++ ObjectMethod *getRenderedVersion* <tt>($text,$theWeb,$theTopic) -> $html</tt>
   112 
   113 The main rendering function.
   114 
   115 
   116 
   117 ---++ StaticMethod *verbatimCallBack* <tt></tt>
   118 
   119 Callback for use with putBackBlocks that replaces &lt; and >
   120 by their HTML entities &amp;lt; and &amp;gt;
   121 
   122 
   123 
   124 ---++ ObjectMethod *TML2PlainText* <tt>($text,$web,$topic,$opts) -> $plainText</tt>
   125 
   126 Clean up TWiki text for display as plain text without pushing it
   127 through the full rendering pipeline. Intended for generation of
   128 topic and change summaries. Adds nop tags to prevent TWiki 
   129 subsequent rendering; nops get removed at the very end.
   130 
   131 Defuses TML.
   132 
   133 $opts:
   134    * showvar - shows !%VAR% names if not expanded
   135    * expandvar - expands !%VARS%
   136    * nohead - strips ---+ headings at the top of the text
   137    * showmeta - does not filter meta-data
   138 
   139 
   140 
   141 ---++ ObjectMethod *protectPlainText* <tt>($text) -> $tml</tt>
   142 
   143 Protect plain text from expansions that would normally be done
   144 duing rendering, such as wikiwords. Topic summaries, for example,
   145 have to be protected this way.
   146 
   147 
   148 
   149 ---++ ObjectMethod *makeTopicSummary* <tt>($theText,$theTopic,$theWeb,$theFlags) -> $tml</tt>
   150 
   151 Makes a plain text summary of the given topic by simply trimming a bit
   152 off the top. Truncates to $TMTRUNC chars or, if a number is specified in $theFlags,
   153 to that length.
   154 
   155 
   156 
   157 ---++ ObjectMethod *takeOutBlocks* <tt>(\$text,$tag,\%map) -> $text</tt>
   158 
   159    * =$text= - Text to process
   160    * =$tag= - XHTML-style tag.
   161    * =\%map= - Reference to a hash to contain the removed blocks
   162 
   163 Return value: $text with blocks removed
   164 
   165 Searches through $text and extracts blocks delimited by a tag, appending each
   166 onto the end of the @@buffer and replacing with a token
   167 string which is not affected by TWiki rendering.  The text after these
   168 substitutions is returned.
   169 
   170 Parameters to the open tag are recorded.
   171 
   172 This is _different_ to takeOutProtected, because it requires tags
   173 to be on their own line. it also supports a callback for post-
   174 processing the data before re-insertion.
   175 
   176 
   177 
   178 ---++ ObjectMethod *putBackBlocks* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
   179 
   180 Return value: $text with blocks added back
   181    * =\$text= - reference to text to process
   182    * =\%map= - map placeholders to blocks removed by takeOutBlocks
   183    * =$tag= - Tag name processed by takeOutBlocks
   184    * =$newtag= - Tag name to use in output, in place of $tag. If undefined, uses $tag.
   185    * =$callback= - Reference to function to call on each block being inserted (optional)
   186 
   187 Reverses the actions of takeOutBlocks.
   188 
   189 Each replaced block is processed by the callback (if there is one) before
   190 re-insertion.
   191 
   192 Parameters to the outermost cut block are replaced into the open tag,
   193 even if that tag is changed. This allows things like
   194 &lt;verbatim class=''>
   195 to be mapped to
   196 &lt;pre class=''>
   197 
   198 Cool, eh what? Jolly good show.
   199 
   200 And if you set $newtag to '', we replace the taken out block with the valuse itself
   201    * which i'm using to stop the rendering process, but then at the end put in the html directly
   202    (for <literal> tag.
   203 
   204 
   205 
   206 ---++ ObjectMethod *renderRevisionInfo* <tt>($web,$topic,$meta,$rev,$format) -> $string</tt>
   207 
   208 Obtain and render revision info for a topic.
   209    * =$web= - the web of the topic
   210    * =$topic= - the topic
   211    * =$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
   212    * =$rev= - the rev number, defaults to latest rev
   213    * =$format= - the render format, defaults to =$rev - $time - $wikiusername=
   214 =$format= can contain the following keys for expansion:
   215    | =$web= | the web name |
   216    | =$topic= | the topic name |
   217    | =$rev= | the rev number |
   218    | =$comment= | the comment |
   219    | =$username= | the login of the saving user |
   220    | =$wikiname= | the wikiname of the saving user |
   221    | =$wikiusername= | the web.wikiname of the saving user |
   222    | =$date= | the date of the rev (no time) |
   223    | =$time= | the time of the rev |
   224    | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME |
   225 
   226 
   227 
   228 ---++ ObjectMethod *summariseChanges* <tt>($user,$web,$topic,$orev,$nrev,$tml) -> $text</tt>
   229 
   230    * =$user= - user (null to ignore permissions)
   231    * =$web= - web
   232    * =$topic= - topic
   233    * =$orev= - older rev
   234    * =$nrev= - later rev
   235    * =$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)
   236 Generate a (max 3 line) summary of the differences between the revs.
   237 
   238 If there is only one rev, a topic summary will be returned.
   239 
   240 If =$tml= is not set, all HTML will be removed.
   241 
   242 In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text.
   243 
   244 
   245 
   246 ---++ ObjectMethod *forEachLine* <tt>($text,\&fn,\%options) -> $newText</tt>
   247 
   248 Iterate over each line, calling =\&fn= on each.
   249 \%options may contain:
   250    * =pre= => true, will call fn for each line in pre blocks
   251    * =verbatim= => true, will call fn for each line in verbatim blocks
   252    * =literal= => true, will call fn for each line in literal blocks
   253    * =noautolink= => true, will call fn for each line in =noautolink= blocks
   254 The spec of \&fn is =sub fn( $line, \%options ) -> $newLine=. The %options
   255 hash passed into this function is passed down to the sub, and the keys
   256 =in_literal=, =in_pre=, =in_verbatim= and =in_noautolink= are set boolean
   257 TRUE if the line is from one (or more) of those block types.
   258 
   259 The return result replaces $line in $newText.
   260 
   261 
   262 
   263 ---++ StaticMethod *getReferenceRE* <tt>($web,$topic,%options) -> $re</tt>
   264 
   265    * $web, $topic - specify the topic being referred to, or web if $topic is
   266      undef.
   267    * %options - the following options are available
   268       * =interweb= - if true, then fully web-qualified references are required.
   269       * =grep= - if true, generate a GNU-grep compatible RE instead of the
   270         default Perl RE.
   271       * =url= - if set, generates an expression that will match a TWiki
   272         URL that points to the web/topic, instead of the default which
   273         matches topic links in plain text.
   274 Generate a regular expression that can be used to match references to the
   275 specified web/topic. Note that the resultant RE will only match fully
   276 qualified (i.e. with web specifier) topic names and topic names that
   277 are wikiwords in text. Works for spaced-out wikiwords for topic names.
   278 
   279 The RE returned is designed to be used with =s///=
   280 
   281 
   282 
   283 ---++ StaticMethod *replaceTopicReferences* <tt>($text,\%options) -> $text</tt>
   284 
   285 Callback designed for use with forEachLine, to replace topic references.
   286 \%options contains:
   287    * =oldWeb= => Web of reference to replace
   288    * =oldTopic= => Topic of reference to replace
   289    * =newWeb= => Web of new reference
   290    * =newTopic= => Topic of new reference
   291    * =inWeb= => the web which the text we are presently processing resides in
   292    * =fullPaths= => optional, if set forces all links to full web.topic form
   293 For a usage example see TWiki::UI::Manage.pm
   294 
   295 
   296 
   297 ---++ StaticMethod *replaceWebReferences* <tt>($text,\%options) -> $text</tt>
   298 
   299 Callback designed for use with forEachLine, to replace web references.
   300 \%options contains:
   301    * =oldWeb= => Web of reference to replace
   302    * =newWeb= => Web of new reference
   303 For a usage example see TWiki::UI::Manage.pm
   304 
   305 
   306 
   307 ---++ ObjectMethod *replaceWebInternalReferences* <tt>(\$text,\%meta,$oldWeb,$oldTopic)</tt>
   308 
   309 Change within-web wikiwords in $$text and $meta to full web.topic syntax.
   310 
   311 \%options must include topics => list of topics that must have references
   312 to them changed to include the web specifier.
   313 
   314 
   315 
   316 ---++ StaticMethod *breakName* <tt>($text,$args) -> $text</tt>
   317 
   318    * =$text= - text to "break"
   319    * =$args= - string of format (\d+)([,\s*]\.\.\.)?)
   320 Hyphenates $text every $1 characters, or if $2 is "..." then shortens to
   321 $1 characters and appends "..." (making the final string $1+3 characters
   322 long)
   323 
   324 _Moved from Search.pm because it was obviously unhappy there,
   325 as it is a rendering function_
   326 
   327 
   328 
   329 ---++ StaticMethod *protectFormFieldValue* <tt>($value,$attrs) -> $html</tt>
   330 
   331 Given the value of a form field, and a set of attributes that control how
   332 to display that value, protect the value from further processing.
   333 
   334 The protected value is determined from the value of the field after:
   335    * newlines are replaced with &lt;br> or the value of $attrs->{newline}
   336    * processing through breakName if $attrs->{break} is defined
   337    * escaping of $vars if $attrs->{protectdollar} is defined
   338    * | is replaced with &amp;#124; or the value of $attrs->{bar} if defined
   339 
   340 
   341 @
   342 
   343 
   344 1.4
   345 log
   346 @buildrelease
   347 @
   348 text
   349 @d10 6
   350 a15 3
   351 Creates a new renderer with initial state from preference values
   352 (NEWTOPICBGCOLOR, NEWTOPICFONTCOLOR NEWTOPICLINKSYMBOL
   353  LINKTOOLTIPINFO)
   354 a30 6
   355 ---++ ObjectMethod *renderFormField* <tt>($web,$topic,$meta,$params) -> $text</tt>
   356 
   357 Render meta-data for a single formfield
   358 
   359 
   360 
   361 d33 2
   362 a34 2
   363    * =$anchorName= -
   364    * =$compatibilityMode= -
   365 d40 1
   366 a40 1
   367 ---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb) -> $html</tt>
   368 d47 1
   369 a47 1
   370    * =$theTopic= - the topic to be lunk
   371 d52 1
   372 a113 26
   373 ---++ ObjectMethod *takeOutProtected* <tt>(\$text,$re,\%map) -> $text</tt>
   374 
   375    * =$text= - Text to process
   376    * =$re= - Regular expression that matches tag expressions to remove
   377    * =\%map= - Reference to a hash to contain the removed blocks
   378 
   379 Return value: $text with blocks removed
   380 
   381 used to extract from $text comment type tags like &lt;!DOCTYPE blah>
   382 
   383 WARNING: if you want to take out &lt;!-- comments --> you _will_ need to re-write all the takeOuts
   384 	to use a different placeholder
   385 
   386 
   387 
   388 ---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$callback) -> $text</tt>
   389 
   390 Return value: $text with blocks added back
   391    * =\$text= - reference to text to process
   392    * =\%map= - map placeholders to blocks removed by takeOutBlocks
   393    * =$callback= - Reference to function to call on each block being inserted (optional)
   394 
   395 Reverses the actions of takeOutProtected.
   396 
   397 
   398 
   399 d209 1
   400 d211 4
   401 a214 1
   402 The spec of \&fn is sub fn( \$line, \%options ) -> $newLine; the %options hash passed into this function is passed down to the sub, and the keys =in_pre=, =in_verbatim= and =in_noautolink= are set boolean TRUE if the line is from one (or more) of those block types.
   403 d220 20
   404 a245 1
   405    * =spacedTopic= => RE matching spaced out oldTopic
   406 a272 14
   407 ---++ StaticMethod *renderFormFieldArg* <tt>($meta,$args) -> $text</tt>
   408 
   409 Parse the arguments to a $formfield specification and extract
   410 the relevant formfield from the given meta data.
   411 
   412    * =args= string containing name of form field
   413    
   414 In addition to the name of a field =args= can be appended with a commas
   415 followed by a string format (\d+)([,\s*]\.\.\.)?). This supports the formatted
   416 search function $formfield and is used to shorten the returned string or a 
   417 hyphenated string.        
   418 
   419 
   420 
   421 d285 13
   422 @
   423 
   424 
   425 1.3
   426 log
   427 @buildrelease
   428 @
   429 text
   430 @d131 1
   431 a131 1
   432 ---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
   433 d136 1
   434 @
   435 
   436 
   437 1.2
   438 log
   439 @buildrelease
   440 @
   441 text
   442 @d282 7
   443 @
   444 
   445 
   446 1.1
   447 log
   448 @buildrelease
   449 @
   450 text
   451 @d17 1
   452 d23 1
   453 d29 1
   454 d47 2
   455 a48 2
   456 SMELL: why can topic be spaced out? is this to support auto squishing of [[Spaced Topic Naming]]?
   457 and [[lowercase Spaced Topic Naming]]
   458 a201 2
   459    | =$date= | the date of the rev (no time) |
   460    | =$time= | the full date and time of the rev |
   461 d206 3
   462 d213 1
   463 d244 1
   464 d259 1
   465 d285 1
   466 @