data/TWiki/TWikiRenderDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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 @