Test

PmWiki

pmwiki.org

edit SideBar

PmWiki • CustomMarkup

administrators (intermediate)

Introduction

PmWiki'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 "preg_replace" function.

Rules are added to the translation engine via PmWiki's Markup() function, which looks like

Markup($name, $when, $pattern, $replace);

where $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.

For example, here's the code that creates the rule for ''emphasized text'' (in scripts/stdmarkup.php):

Markup("em", "inline", "/''(.*?)''/", "<em>$1</em>");

Basically 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 <em> and </em>.

The 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.

The 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:

_begin      start of translation
fulltext    translations to be performed on the full text            
split       conversion of the full markup text into lines to be processed
directives  directive processing
inline      inline markups
links       conversion of [[links]], url-links, and WikiWords     
block       block markups
style       style handling       
_end        end of translation

Thus, 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" or "<inline" for the second parameter.

The third parameter is a Perl-compatible regular expression. Basically, it is a slash, a regular expression, another slash, and a set of optional modifiers.

The 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.)

The 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.

In the example, we have "<em>$1</em>", which is an <em>, the text matched by the first parentheses (i.e. by the .*? section of the pattern), and </em>.

Here's a rule for @@monospaced@@ text:

Markup("@@", "inline", "/@@(.*?)@@/", "<code>$1</code>");

and for a [:comment ...:] directive that is simply removed from the output:

Markup("comment", "directives", "/\\[:comment .*?:\\]/", '');

Okay, 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:

Markup("strong", "<em", "/'''(.*?)'''/", "<strong>$1</strong>");

This creates a rule called "strong", and the second parameter "<em" 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 "<inline" to specify rules that should be handled before any other inline rules.)

If you want to disable available markup just call e.g.:

DisableMarkup("strong")

PmWiki'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.

Other common examples

Define a custom markup to produce a specific HTML or Javascript sequence

Suppose an admin wants to have a simple "(:example:)" markup that will always produce a fixed HTML string in the output, such as for a webring, Google AdSense display, or Javascript. The Markup() call to do this would be:

Markup('example', 'directives',
  '/\\(:example:\\)/',
  Keep("<div class='example'><p>Here is a 
    <a target='_blank' href='http://www.example.com'>link</a> to
    <em>example.com</em></p></div>");

  • The first argument is a unique name for the markup ("example").
  • The second argument says to perform this markup along with other directives.
  • The third argument is the pattern to look for "(:example:)".
  • The fourth argument is the HTML that "(:example:)" is to be replaced with. We use the Keep() function here to prevent the output from being further processed by PmWiki's markup rule -- in the above example, we don't want the http://www.example.com url to be again converted to a link.

Define a markup to call a custom function that returns content

An 'e' option on the $pattern parameter will cause the $replace parameter to be treated as a PHP expression to be evaluated instead of replacement text. Thus, a markup to produce a random number between 1 and 100 might look like:

Markup('random', 'directives',
  '/\\(:random:\\)/e',
  "random(1, 10)");

This calls the PHP built-in random() function and substitutes the directive with the result. Any function can be called, including functions defined in a local customization file.

Arguments can also be passed by using regular expression capturing parentheses, thus

Markup('randomargs', 'directives',
  '/\\(:random (\\d+) (\\d+):\\)/e',
  "random('$1', '$2')");

will cause the markup (:random 50 100:) to generate a random number between 50 and 100.

Note: Be very careful with the /e modifier in regular expressions; malicious authors may be able to pass strings that cause arbitrary and undesirable PHP functions to be executed.

For a PmWiki function to help with parsing arbitrary sequences of arguments and key=value pairs, see Cookbook:ParseArgs.

<< Custom InterMap | Documentation Index | Custom WikiStyles >>

July 2014:
Yate 5.4 and YateBTS 4 launched. Added JSON and DNS support in Javascript, Handover support in YateBTS.

March 2014:
YateBTS 2.0 launched. Added authentication and WebGUI. Added USSD support in commercial version.

March 2014:
Yate 5.2 launched. Better JavaScript support and a fixed memory leak.

Jan 2014:
YateBTS 1.0 launched. The first GSM Basestation which works with an IMS/VoLTE core network.

Jan 2014:
Yate 5.1 launched. Better JavaScript support and added libygsm. Elisa chatbot added in RManager

Oct 2013:
OpenHSS is the Yate based HLR/HSS solution for MVNO and LTE carriers.

Oct 2013:
Yate 5 released. Added IPv6 support in SIP for LTE. Improved JavaScript support. Download NOW

Jan 2013:
Yate 4.3 released: Added XML support in Javascript. SCCP - GTT routing between different networks. Stability improvements.
Download NOW

Aug 2012:
Yate 4.2 released: SIP flood protection. Better Jabber/Google Voice support. Usable Javascript. Fixed SIGTRAN links fluctuations.
Download NOW

Apr 2012:
YateClient was accepted in the Mac Store.

Yate 4.1 released: better Gvoice support, iSAC codec, support for new Wanpipe drivers. Fixes T.38 and Mac client issues.

Mar 2012:
SS7Cloud is launched today, 1st March, 2012, by NullTeam, Yate creators. Having all you need to be a US CLEC, it brings SS7 services in a cloud.

Feb 2012:
Yate 4.0 released.
SCCP, TCAP, MAP and CAMEL, TCP and TLS in SIP, Javascript fast prototyping of telephony applications and brand new face for YateClient.

Nov 2011:
Here is a video that, quote "demonstrates the truly awesome power of the YATE engine, as it easily handles 3 simultaneous calls to an audio player application including dtmf (button press) handling "(from PaintedRockComm).

Nov 2011:
Yate will attend ORR - OPENRHEINRUHR (November 12 - 13).

04 May 2011:
sipgate chooses open source project Yate for core infrastructure.

12 Apr 2011:
Yate 3.3.2 released.
Fix for Jingle calls to Google Voice dropping after 5 minutes.
4 Apr 2011:
Yate 3.3 released.
Support for GMail chat conference, fixes for internal microphone in MacOS. Minor fixes in SS7 M2PA and ANSI. Fixes in H.323, SIP and RTP.

9 Mar 2011:
Yate 3.2 released.
Bug fixes in SIGTRAN/MGCP/SS7 and added support for CNAM/LNP lookup by SIP INVITE/3xx.

Feb 2011:
Yate will attend FOSDEM and XMPP summit.

31 Jan 2011:
Yate 3.1 released.
Yate client support for Google Voice. Support for any country tones in tonegen.

20 Dec 2010:
Yate 3.0 released.
SS7 ITU certified. SS7 STP added. Client supports Jabber IM (Google Talk + Facebook).

3 May 2010:
Yate 3.0.0 alpha 3 released. Featuring the new Jabber server and wideband audio.

8 March 2010:
Yate 2.2 released. Mostly bug fixes. Dahdi compatible. Latest 2 release before 3.0.

6-7 February 2010:
Yate booth at FOSDEM 2010. Free CD with Freesentral available.

2 Nov 2009:
Yate 2.1 launched. Can replace a Cisco PGW2200 to control a Cisco AS54xx.

6 Aug 2008:
Yate and OpenSIPS (former OpenSER) join to build IP based clusters.

4 Aug 2008:
Yate 2 launched.


EditHistoryBacklinksRecent ChangesSearch