version=pmwiki-2.0.0 ordered=1 urlencoded=1
agent=Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; Maxthon; .NET CLR 1.1.4322)
author=Jeff
host=216.63.217.100
name=PmWiki.CustomMarkup
rev=47
targets=PmWiki.PmWiki,PmWiki.CustomMarkup,PmWiki.CustomInterMap,PmWiki.DocumentationIndex,PmWiki.CustomWikiStyles
text=%25audience%25 administrators (intermediate)%0a!! Introduction%0a%0aPmWiki's markup translation engine is handled by a set of rules; each rule searches for a specific pattern in the markup text and replaces it with some replacement text.  Internally, this is accomplished by using PHP's "[[(http://www.php.net/)preg_replace]]" function.%0a%0aRules are added to the translation engine via PmWiki's Markup() function, which looks like%0a%0a->[@Markup($name, $when, $pattern, $replace);@]%0a%0awhere [@$name@] is a unique name (a string) given to the rule, [@$when@] says when the rule should be applied relative to other rules, [@$pattern@] is the pattern to be searched for in the markup text, and [@$replace@] is what the pattern should be replaced with.%0a%0aFor example, here's the code that creates the rule for [@''emphasized text''@] (in ''scripts/stdmarkup.php''):%0a%0a->[@Markup("em", "inline", "/''(.*?)''/", "%3cem>$1%3c/em>");@]%0a%0aBasically this statement says to create a rule called "em" to be performed with the other "inline" markups, and the rule replaces any text inside two pairs of single quotes with the same text ($1) surrounded by [@%3cem>@] and [@%3c/em>@].%0a%0aThe first two parameters to Markup() are used to specify the sequence in which rules should be applied.  The first parameter provides a name for a rule -- "[@em@]" in the example above.  We could've chosen other names such as "[@''@]", or even "[@twosinglequotes@]".  In general PmWiki uses the markup itself to name the rule (i.e., PmWiki uses "[@''@]" instead of "[@em@]"), but to keep this example easier to read later on we'll use a mnemonic name for now.%0a%0aThe second parameter says that this rule is to be done along with the other "inline" markups.  PmWiki divides the translation process into a number of phases:%0a%0a-> [@%0a_begin      start of translation%0afulltext    translations to be performed on the full text            %0asplit       conversion of the full markup text into lines to be processed%0adirectives  directive processing%0ainline      inline markups%0alinks       conversion of [[links]], url-links, and WikiWords     %0ablock       block markups%0astyle       style handling       %0a_end        end of translation%0a@]%0a%0aThus, specifying "inline" for the second parameter says that this rule should be applied when the other "inline" rules are being performed.  If we want a rule to be performed with the directives -- i.e., before inline rules are processed, we would specify "directives" for the second parameter.%0a%0aThe third parameter is a Perl-compatible regular expression. Basically, it is a slash, a [[regular expression -> http://www.php.net/manual/en/reference.pcre.pattern.syntax.php]], another slash, and (optionally) a set of [[options ("modifiers")-> http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php]].%0a%0aThe example uses the pattern string [@"/''(.*?)''/"@], which uses [@''(.*)''@] as the regular expression and no options. (The regular expression says "find two single quotes in succession, then as few arbitrary characters as are needed to make the match find something, then two additional single quotes in succession"; the parentheses "capture" a part of the wikitext for later use.)%0a%0aThe fourth parameter is the replacement text that should be inserted instead of the marked-up wikitext. You can use [@$1@], [@$2@], etc. to insert the text from the first, second etc. parenthesised part of the regular expression.%0a%0aIn the example, we have [@"%3cem>$1%3c/em>"@], which is an [@%3cem>@], the text matched by the first parentheses (i.e. by the [@.*?@] section of the pattern), and [@%3c/em>@].%0a%0a!!!Examples%0a%0aHere's a rule for [@@@monospaced@@@] text:%0a%0a->[@Markup("@@", "inline", "/@@(.*?)@@/", "%3ccode>$1%3c/code>");@]%0a%0aand for a [@[:comment ...:]@] directive that is simply removed from the output:%0a%0a->[@Markup("comment", "directives", "/\\(:comment .*?:\\)/", '');@]%0a%0aOkay, now how about the rule for [@'''strong emphasis'''@]?  We have to be a bit careful here, because although this translation should be performed along with other inline markup, we also have to make sure that the rule for [@'''@] is handled ''before'' the rule for [@''@], because [@'''@] also contains [@''@]. The second parameter to Markup() can be used to specify the new rule's relationship to any other rule:%0a%0a->[@Markup("strong", "%3cem", "/'''(.*?)'''/", "%3cstrong>$1%3c/strong>");@]%0a%0aThis creates a rule called "strong", and the second parameter "%3cem" says to be sure that this rule is processed before the "em" rule we defined above.  If we wanted to do something after the "em" rule, we would use ">em" instead.  Thus, it's possible to add rules at any point in PmWiki's markup translation process in an extensible manner.  (In fact, the "inline", "block", "directives", etc., phases above are just placeholder rules used to provide an overall sequence for other rules.  Thus one can use "%3cinline" to specify rules that should be handled before any%0aother inline rules.)             %0a%0aIf you want to disable available markup just call e.g.:%0a%0a->[@Markup("strong", "%3cem");@]%0a%0aThe lack of a pattern & replacement parameters indicates that you simply wish to disable the markup.%0a%0aPmWiki's default markup rules are defined in the ''scripts/stdmarkup.php'' file.  To see the entire translation table as the program is running, the scripts/diag.php module adds "[@?action=ruleset@]", which displays the set of defined markup rules in the sequence in which they will be processed.  You can see it at [[CustomMarkup?action=ruleset | CustomMarkup?action=ruleset]].%0a%0a%0a!! More examples%0a%0a!!!Call a user function which returns some content%0a%0aAn 'e' option on the [@$pattern@] parameter will make PmWiki interpret the [@$replace@] parameter not as a replacement text, but as a PHP expression that returns the replacement text.%0a%0aThe markup [=(:meeting:)=] uses this by calling a hypothetical global function meeting() (say, defined in [@config.php@]), which is supposed to return the date of the next BLUG Meeting as a string:%0a%0a-> [@Markup('meeting', 'directives', '/\\(:meeting:\\)/e', 'meeting()');@]%0a%0aNote also, that the 'e' option is a standard [@preg_replace()@] option - and it still allows for 'references substitution' (that is, the parentheses in the [@$pattern@] are caught and inserted where [@$1@], [@$2@]... etc. are). [-''That might help you also in solving the excercise left below ;)''-]%0a%0a%0a!!!Simple macro replacement:%0a%0a-> [@%0aMarkup('bigP', 'fulltext', '/\{bigP\}/',%0a  '%25font-size="40px"%25 P' .%0a  '%25block font-size="15px" border="0px" ' .%0a  'padding="4px 14px 7px 14px" bgcolor=#FFB%25 ');%0a@]%0a%0aThis uses the fulltext phase to simply replace the @@[={bigP}=]@@ sequence with a bunch of random markup, so that%0a%0a [={bigP}ie Jesu Domine, dona eis requiem (''whack'').=]%0a%0aproduces this effect:%0a%0a%25font-size="40px"%25 P%25block font-size="15px" border="0px" padding="4px 14px 7px 14px" bgcolor=#FFB%25 ie Jesu Domine, dona eis requiem (''whack'').%0a%0aAdding an argument (as in @@[={big P}=]@@, here) to a macro is left as an exercise for the reader.%0a%0a%0a!!!Add Google Search to your wiki[[#googlesearch]]%0a%0a'''German Example, Same Window'''%0a%0aPut this text at the bottom of your config.php file%0a%0a-> [@%0aMarkup('googlesearch', 'directives', '/\\(:googlesearch:\\)/e',"Keep(\"%0a%3cFORM method=GET action='http://www.google.de/search'>%0a%3cTABLE>%3ctr>%3ctd>%0a%3cA HREF='http://www.google.de'>%0a%3cIMG SRC='http://www.google.de/logos/Logo_40wht.gif' border='0'%0aALT='Google' align='absmiddle'>%3c/A>%0a%3cINPUT TYPE=text name=q size=20 maxlength=255 value=''>%0a%3cINPUT TYPE=hidden name=hl value=de>%0a%3cINPUT type=submit name=btnG VALUE='Google Search'>%0a%3c/td>%3c/tr>%3c/TABLE>%0a%3c/FORM>%0a\")");%0a@]%0a%0aPut [=(:googlesearch:)=] anywhere on your Page. --newmy%0a%0a%0a!!!Add Google Safe Search in a New Window to your wiki[[#googlesearch]]%0a%0a'''English Example, Safe Search in a New Window'''%0a%0aPut this text at the bottom of your config.php file%0a%0a-> [@%0aMarkup('googlesearch', 'directives', '/\\(:googlesearch:\\)/e',"Keep(\"%0a%3cFORM method=GET action='http://www.google.com/search' target='_blank'>%0a%3cTABLE>%3ctr>%3ctd>%0aGoogle Safe Search%0a%3cA HREF='http://www.google.com/search?safe=vss'>%3c/A>%0a%3cINPUT TYPE=text name=q size=42 maxlength=255 value=''>%0a%3cINPUT type=hidden name=safe value=strict>%0a%3cINPUT type=submit name=sa value='Google Search'>%0a%3c/td>%3c/tr>%3c/TABLE>%0a%3c/FORM>%0a\")");%0a@]%0a%0aNow you can put [=(:googlesearch:)=] anywhere on your Page. --Jeff, Corpus Christi, Texas%0a%0a'''Add Local Weather to your site'''%0a%0aPut this text at the bottom of your config.php file%0a%0a->[@%0aMarkup('localweather', 'directives', '/\\(:localweather:\\)/e',"Keep(\"%0a%3cscript src='http://voap.weather.com/weather/oap/78410?template=GENXV&par=null&unit=0&key=021c5b063db71b7fdd9a11f5ec88c033'>%3c/script>%0a\")");%0a@]%0a%0aNow you can put [=(:localweather:)=] anywhere on your Page. --Jeff, Corpus Christi, Texas%0a%0aNote: You will need to go to [[http://www.weather.com]] to get the script line to replace the script line above.%0a%0aJust place your script between:%0a[@%0aMarkup('localweather', 'directives', '/\\(:localweather:\\)/e',"Keep(\"%0a@]%0a%0aand%0a%0a[@%0a\")");%0a@]%0a%0a%25trail%25%3c%3c|[[DocumentationIndex]]|>>
time=1125604500