1head	1.11;
2access;
3symbols;
4locks; strict;
5comment	@# @;
6
7
81.11
9date	2018.07.16.03.20.47;	author TWikiContributor;	state Exp;
10branches;
11next	1.10;
12
131.10
14date	2014.10.05.11.03.29;	author TWikiContributor;	state Exp;
15branches;
16next	1.9;
17
181.9
19date	2013.10.14.08.02.47;	author TWikiContributor;	state Exp;
20branches;
21next	1.8;
22
231.8
24date	2013.02.16.23.22.24;	author TWikiContributor;	state Exp;
25branches;
26next	1.7;
27
281.7
29date	2010.05.29.14.44.26;	author TWikiContributor;	state Exp;
30branches;
31next	1.6;
32
331.6
34date	2008.12.06.09.02.17;	author TWikiContributor;	state Exp;
35branches;
36next	1.5;
37
381.5
39date	2008.01.22.03.21.32;	author TWikiContributor;	state Exp;
40branches;
41next	1.4;
42
431.4
44date	2007.03.03.14.51.47;	author TWikiContributor;	state Exp;
45branches;
46next	1.3;
47
481.3
49date	2007.02.05.00.18.34;	author TWikiContributor;	state Exp;
50branches;
51next	1.2;
52
531.2
54date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
55branches;
56next	1.1;
57
581.1
59date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
60branches;
61next	;
62
63
64desc
65@new-topic
66@
67
68
691.11
70log
71@buildrelease
72@
73text
74@---+ Package =TWiki::Render=
75
76This module provides most of the actual HTML rendering code in TWiki.
77
78
79%TOC%
80
81---++ ClassMethod *new* <tt>($session)</tt>
82
83Creates a new renderer
84
85
86
87---++ ObjectMethod *finish* <tt>()</tt>
88Break circular references.
89
90
91
92---++ ObjectMethod *renderParent* <tt>($web,$topic,$meta,$params) -> $text</tt>
93
94Render parent meta-data
95
96
97
98---++ ObjectMethod *renderMoved* <tt>($web,$topic,$meta,$params) -> $text</tt>
99
100Render moved meta-data
101
102
103
104---++ StaticMethod *chompUtf8Fragment* <tt>($str) -> $str</tt>
105
106String truncation may happen in the middle of a UTF-8 byte sequence.
107This function gets rid of the truncated fragment.
108
109
110
111---++ ObjectMethod *makeAnchorName* <tt>($anchorName,$compatibilityMode) -> $anchorName</tt>
112
113   * =$anchorName= - the unprocessed anchor name
114   * =$compatibilityMode= - SMELL: compatibility with *what*?? Who knows. :-(
115
116Build a valid HTML anchor name
117
118
119
120---++ ObjectMethod *makeUniqueAnchorName* <tt>($web,$topic,$anchorName,$compatibility) -> $anchorName</tt>
121
122   * =$anchorName= - the unprocessed anchor name
123   * =$compatibilityMode= - SMELL: compatibility with *what*?? Who knows. :-(
124
125Build a valid HTML anchor name (unique w.r.t. the list stored in %anchornames)
126
127
128
129---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel,$theParams) -> $html</tt>
130
131Generate a link.
132
133Note: Topic names may be spaced out. Spaced out names are converted to <nop>WikWords,
134for example, "spaced topic name" points to "SpacedTopicName".
135   * =$theWeb= - the web containing the topic
136   * =$theTopic= - the topic to be link
137   * =$theLinkText= - text to use for the link
138   * =$theAnchor= - the link anchor, if any
139   * =$doLinkToMissingPages= - boolean: false means suppress link for non-existing pages
140   * =$doKeepWeb= - boolean: true to keep web prefix (for non existing Web.TOPIC)
141   * =$hasExplicitLinkLabel= - boolean: true in case of [[TopicName][explicit link label]]
142   * =$theParams= - the URL parameters specified by ?name1=value1;name2=valu2;... excluding the leading ?.
143     This is added as per Item7505. This parameter's natural position is before
144     =$theAnchor=. But to minimize code changes, it's introduced as the laster
145     one
146
147Called by _handleWikiWord and _handleSquareBracketedLink and by Func::internalLink
148
149Calls _renderWikiWord, which in turn will use Plurals.pm to match fold plurals to equivalency with their singular form
150
151SMELL: why is this available to Func?
152
153
154
155---++ ObjectMethod *renderFORM* <tt>(%params,$topic,$web) -> $tml</tt>
156
157Returns TML of a TWiki Form, based on %FORM{}% variable.
158
159
160
161---++ ObjectMethod *renderFORMFIELD* <tt>(%params,$topic,$web) -> $html</tt>
162
163Returns the fully rendered expansion of a %FORMFIELD{}% tag.
164
165
166
167---++ ObjectMethod *renderEDITFORM* <tt>(%params,$topic,$web) -> $tml</tt>
168
169Returns TML of a TWiki Form, based on %EDITFORM{}% variable.
170
171
172
173---++ ObjectMethod *renderEDITFORMFIELD* <tt>(%params,$topic,$web) -> $html</tt>
174
175Returns the fully rendered expansion of a %EDITFORMFIELD{}% tag.
176
177
178
179---++ ObjectMethod *getRenderedVersion* <tt>($text,$theWeb,$theTopic) -> $html</tt>
180
181The main rendering function.
182
183
184
185---++ StaticMethod *verbatimCallBack* <tt></tt>
186
187Callback for use with putBackBlocks that replaces &lt; and >
188by their HTML entities &amp;lt; and &amp;gt;
189
190
191
192---++ ObjectMethod *TML2PlainText* <tt>($text,$web,$topic,$opts) -> $plainText</tt>
193
194Clean up TWiki text for display as plain text without pushing it
195through the full rendering pipeline. Intended for generation of
196topic and change summaries. Adds nop tags to prevent TWiki
197subsequent rendering; nops get removed at the very end.
198
199Defuses TML.
200
201$opts:
202   * showvar - shows !%VAR% names if not expanded
203   * expandvar - expands !%VARS%
204   * nohead - strips ---+ headings at the top of the text
205   * showmeta - does not filter meta-data
206   * entityencode - entity encode the resulting plain text (for title parameter)
207
208
209
210---++ ObjectMethod *protectPlainText* <tt>($text) -> $tml</tt>
211
212Protect plain text from expansions that would normally be done
213duing rendering, such as wikiwords. Topic summaries, for example,
214have to be protected this way.
215
216
217
218---++ ObjectMethod *makeTopicSummary* <tt>($theText,$theTopic,$theWeb,$theFlags) -> $tml</tt>
219
220Makes a plain text summary of the given topic by simply trimming a bit
221off the top. Truncates to $TMTRUNC chars or, if a number is specified in $theFlags,
222to that length.
223
224
225
226---++ ObjectMethod *takeOutBlocks* <tt>(\$text,$tag,\%map) -> $text</tt>
227
228   * =$text= - Text to process
229   * =$tag= - XHTML-style tag.
230   * =\%map= - Reference to a hash to contain the removed blocks
231
232Return value: $text with blocks removed
233
234Searches through $text and extracts blocks delimited by a tag, appending each
235onto the end of the @@buffer and replacing with a token
236string which is not affected by TWiki rendering.  The text after these
237substitutions is returned.
238
239Parameters to the open tag are recorded.
240
241This is _different_ to takeOutProtected, because it requires tags
242to be on their own line. it also supports a callback for post-
243processing the data before re-insertion.
244
245
246
247---++ ObjectMethod *putBackBlocks* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
248
249Return value: $text with blocks added back
250   * =\$text= - reference to text to process
251   * =\%map= - map placeholders to blocks removed by takeOutBlocks
252   * =$tag= - Tag name processed by takeOutBlocks
253   * =$newtag= - Tag name to use in output, in place of $tag. If undefined, uses $tag.
254   * =$callback= - Reference to function to call on each block being inserted (optional)
255
256Reverses the actions of takeOutBlocks.
257
258Each replaced block is processed by the callback (if there is one) before
259re-insertion.
260
261Parameters to the outermost cut block are replaced into the open tag,
262even if that tag is changed. This allows things like
263&lt;verbatim class=''>
264to be mapped to
265&lt;pre class=''>
266
267Cool, eh what? Jolly good show.
268
269And if you set $newtag to '', we replace the taken out block with the valuse itself
270   * which i'm using to stop the rendering process, but then at the end put in the html directly
271   (for <literal> tag.
272
273
274
275---++ ObjectMethod *renderRevisionInfo* <tt>($web,$topic,$meta,$rev,$format) -> $string</tt>
276
277Obtain and render revision info for a topic.
278   * =$web= - the web of the topic
279   * =$topic= - the topic
280   * =$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
281   * =$rev= - the rev number, defaults to latest rev
282   * =$format= - the render format, defaults to =$rev - $time - $wikiusername=
283=$format= can contain the following keys for expansion:
284   | =$web= | the web name |
285   | =$topic= | the topic name |
286   | =$rev= | the rev number |
287   | =$comment= | the comment |
288   | =$username= | the login of the saving user |
289   | =$wikiname= | the wikiname of the saving user |
290   | =$wikiusername= | the web.wikiname of the saving user |
291   | =$date= | the date of the rev (no time) |
292   | =$time= | the time of the rev |
293   | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME |
294
295
296
297---++ ObjectMethod *summariseChanges* <tt>($user,$web,$topic,$orev,$nrev,$tml) -> $text</tt>
298
299   * =$user= - user (null to ignore permissions)
300   * =$web= - web
301   * =$topic= - topic
302   * =$orev= - older rev
303   * =$nrev= - later rev
304   * =$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)
305Generate a (max 3 line) summary of the differences between the revs.
306
307If there is only one rev, a topic summary will be returned.
308
309If =$tml= is not set, all HTML will be removed.
310
311In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text.
312
313
314
315---++ ObjectMethod *forEachLine* <tt>($text,\&fn,\%options) -> $newText</tt>
316
317Iterate over each line, calling =\&fn= on each.
318\%options may contain:
319   * =pre= => true, will call fn for each line in pre blocks
320   * =verbatim= => true, will call fn for each line in verbatim blocks
321   * =literal= => true, will call fn for each line in literal blocks
322   * =noautolink= => true, will call fn for each line in =noautolink= blocks
323The spec of \&fn is =sub fn( $line, \%options ) -> $newLine=. The %options
324hash passed into this function is passed down to the sub, and the keys
325=in_literal=, =in_pre=, =in_verbatim= and =in_noautolink= are set boolean
326TRUE if the line is from one (or more) of those block types.
327
328The return result replaces $line in $newText.
329
330
331
332---++ StaticMethod *getReferenceRE* <tt>($web,$topic,%options) -> $re</tt>
333
334   * $web, $topic - specify the topic being referred to, or web if $topic is
335     undef.
336   * %options - the following options are available
337      * =interweb= - if true, then fully web-qualified references are required.
338      * =grep= - if true, generate a GNU-grep compatible RE instead of the
339        default Perl RE.
340      * =url= - if set, generates an expression that will match a TWiki
341        URL that points to the web/topic, instead of the default which
342        matches topic links in plain text.
343Generate a regular expression that can be used to match references to the
344specified web/topic. Note that the resultant RE will only match fully
345qualified (i.e. with web specifier) topic names and topic names that
346are wikiwords in text. Works for spaced-out wikiwords for topic names.
347
348The RE returned is designed to be used with =s///=
349
350
351
352---++ StaticMethod *replaceTopicReferences* <tt>($text,\%options) -> $text</tt>
353
354Callback designed for use with forEachLine, to replace topic references.
355\%options contains:
356   * =oldWeb= => Web of reference to replace
357   * =oldTopic= => Topic of reference to replace
358   * =newWeb= => Web of new reference
359   * =newTopic= => Topic of new reference
360   * =inWeb= => the web which the text we are presently processing resides in
361   * =fullPaths= => optional, if set forces all links to full web.topic form
362For a usage example see TWiki::UI::Manage.pm
363
364
365
366---++ StaticMethod *replaceWebReferences* <tt>($text,\%options) -> $text</tt>
367
368Callback designed for use with forEachLine, to replace web references.
369\%options contains:
370   * =oldWeb= => Web of reference to replace
371   * =newWeb= => Web of new reference
372For a usage example see TWiki::UI::Manage.pm
373
374
375
376---++ ObjectMethod *replaceWebInternalReferences* <tt>(\$text,\%meta,$oldWeb,$oldTopic)</tt>
377
378Change within-web wikiwords in $$text and $meta to full web.topic syntax.
379
380\%options must include topics => list of topics that must have references
381to them changed to include the web specifier.
382
383
384
385---++ StaticMethod *breakName* <tt>($text,$args) -> $text</tt>
386
387   * =$text= - text to "break"
388   * =$args= - string of format (\d+)([,\s*]\.\.\.)?)
389Hyphenates $text every $1 characters, or if $2 is "..." then shortens to
390$1 characters and appends "..." (making the final string $1+3 characters
391long)
392
393_Moved from Search.pm because it was obviously unhappy there,
394as it is a rendering function_
395
396
397
398---++ StaticMethod *protectFormFieldValue* <tt>($value,$attrs) -> $html</tt>
399
400Given the value of a form field, and a set of attributes that control how
401to display that value, protect the value from further processing.
402
403The protected value is determined from the value of the field after:
404   * newlines are replaced with value of $attrs->{newline} if defined
405   * processing through breakName if $attrs->{break} is defined
406   * escaping of $vars if $attrs->{protectdollar} is defined
407   * | is replaced with &amp;#124; or the value of $attrs->{bar} if defined
408
409
410@
411
412
4131.10
414log
415@buildrelease
416@
417text
418@d82 6
419d94 6
420@
421
422
4231.9
424log
425@buildrelease
426@
427text
428@d56 1
429a56 1
430---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html</tt>
431d69 4
432d319 1
433a319 1
434   * newlines are replaced with &lt;br> or the value of $attrs->{newline}
435@
436
437
4381.8
439log
440@buildrelease
441@
442text
443@d31 7
444d84 6
445@
446
447
4481.7
449log
450@buildrelease
451@
452text
453@d104 1
454@
455
456
4571.6
458log
459@buildrelease
460@
461text
462@d51 1
463a51 1
464Generate a link.
465d61 1
466a61 1
467   * =$hasExplicitLinkLabel= - boolean: true in case of [[TopicName][explicit link label]]
468d65 1
469a65 1
470Calls _renderWikiWord, which in turn will use Plurals.pm to match fold plurals to equivalency with their singular form
471d94 1
472a94 1
473topic and change summaries. Adds nop tags to prevent TWiki
474@
475
476
4771.5
478log
479@buildrelease
480@
481text
482@d40 9
483@
484
485
4861.4
487log
488@buildrelease
489@
490text
491@d10 6
492a15 3
493Creates a new renderer with initial state from preference values
494(NEWTOPICBGCOLOR, NEWTOPICFONTCOLOR NEWTOPICLINKSYMBOL
495 LINKTOOLTIPINFO)
496a30 6
497---++ ObjectMethod *renderFormField* <tt>($web,$topic,$meta,$params) -> $text</tt>
498
499Render meta-data for a single formfield
500
501
502
503d33 2
504a34 2
505   * =$anchorName= -
506   * =$compatibilityMode= -
507d40 1
508a40 1
509---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb) -> $html</tt>
510d47 1
511a47 1
512   * =$theTopic= - the topic to be lunk
513d52 1
514a113 26
515---++ ObjectMethod *takeOutProtected* <tt>(\$text,$re,\%map) -> $text</tt>
516
517   * =$text= - Text to process
518   * =$re= - Regular expression that matches tag expressions to remove
519   * =\%map= - Reference to a hash to contain the removed blocks
520
521Return value: $text with blocks removed
522
523used to extract from $text comment type tags like &lt;!DOCTYPE blah>
524
525WARNING: if you want to take out &lt;!-- comments --> you _will_ need to re-write all the takeOuts
526	to use a different placeholder
527
528
529
530---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$callback) -> $text</tt>
531
532Return value: $text with blocks added back
533   * =\$text= - reference to text to process
534   * =\%map= - map placeholders to blocks removed by takeOutBlocks
535   * =$callback= - Reference to function to call on each block being inserted (optional)
536
537Reverses the actions of takeOutProtected.
538
539
540
541d209 1
542d211 4
543a214 1
544The 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.
545d220 20
546a245 1
547   * =spacedTopic= => RE matching spaced out oldTopic
548a272 14
549---++ StaticMethod *renderFormFieldArg* <tt>($meta,$args) -> $text</tt>
550
551Parse the arguments to a $formfield specification and extract
552the relevant formfield from the given meta data.
553
554   * =args= string containing name of form field
555
556In addition to the name of a field =args= can be appended with a commas
557followed by a string format (\d+)([,\s*]\.\.\.)?). This supports the formatted
558search function $formfield and is used to shorten the returned string or a
559hyphenated string.
560
561
562
563d285 13
564@
565
566
5671.3
568log
569@buildrelease
570@
571text
572@d131 1
573a131 1
574---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
575d136 1
576@
577
578
5791.2
580log
581@buildrelease
582@
583text
584@d282 7
585@
586
587
5881.1
589log
590@buildrelease
591@
592text
593@d17 1
594d23 1
595d29 1
596d47 2
597a48 2
598SMELL: why can topic be spaced out? is this to support auto squishing of [[Spaced Topic Naming]]?
599and [[lowercase Spaced Topic Naming]]
600a201 2
601   | =$date= | the date of the rev (no time) |
602   | =$time= | the full date and time of the rev |
603d206 3
604d213 1
605d244 1
606d259 1
607d285 1
608@
609