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 < and > 188by their HTML entities &lt; and &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<verbatim class=''> 264to be mapped to 265<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 &#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 <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 <!DOCTYPE blah> 524 525WARNING: if you want to take out <!-- 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