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