====== Macros Plugin ====== ---- plugin ---- description: Use macro expressions and conditional expressions to generate page text author : Ian G. Burleigh email : ian dot george dot burleigh at gmail dot com type : action, syntax lastupdate : 2012-02-09 compatible : Angua, Adora Belle, Weatherwax, Binky, Greebo depends : conflicts : similar : easyvar, replace, kixovar, fields, textinsert, wst, templater tags : extension, formatting, macro, !obsolete downloadurl: https://github.com/phi53/dokuwiki_plugin_macros/archive/master.zip bugtracker : https://github.com/phi53/dokuwiki_plugin_macros/issues sourcerepo : https://github.com/phi53/dokuwiki_plugin_macros/ donationurl: ---- ===== Download and Installation ===== **Since the repository has been removed, a workaround is to download comicslate.org-version of the plugin\\ https://comicslate.org/_/macros.rar\\ MD5-check 1d28e5fdb7feb05aae44820169bdbe36** Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. ===== Description ===== This plugin allows you to define custom macros that can be used to generate page text. It also processes simple conditional expressions, removes block comments and allows escaping of literal characters (those are useful features when using macros). ===== Syntax and Usage ===== === Block Comments === Any text between block comment markers is simply removed: {{## comment ##}} === Escaped Characters === A character that is preceded by a backtick ` will be rendered as a literal character. That allows use of characters that otherwise would be interpreted as markup characters: `{`{ literal braces `}`} Double that to render a backtick: `` === Macros === The format of a macro definition is: {{$name=definition$}} where //name// is the macro identifier and //definition// is the macro text. The definition may contain placeholders //@0//, //@1//, ... //@9// for up to ten macro arguments. Macros are used (expanded) by: $name (without specified arguments - equal to an empty argument list) $name[] (with an empty argument list) $name[arg] (with one argument) $name[arg1|arg2] (with two arguments, etc.) An example: {{$format=**@0** @1 //@2//$}} $format[bold|and|italics] Produces this text: **bold** and //italics// === Conditionals === The plugin processes two types of conditional expressions: $??[cond|T|F] expands to ''T'' if ''cond'' is not an empty string, otherwise expands to ''F'' $?[a|b] (shortcut for $??[a|a|b]) expands to ''a'' if ''a'' is not an empty string, otherwise expands to ''b'' ===== Discussion ===== ==== Vanishing PHP text ==== Unfortunately, the Macros plugin simply removes undefined macros. This clobbers PHP code, because PHP variables look a lot like macros. There is an easy fix: in ''macros.php'', function ''expand_macro_callback()'', change the following code to return the original match instead of an empty string: // a defined macro? $res = @$this->macroDefs[$name]; if(!$res) { $this->undefinedMacros[] = $name; return $m[0]; // return ''; } Also, the macro identifying character ''$'' can be changed to another character or a sequence of characters. In ''macros.php'', search for and replace ''\$'' in regular expressions. ==== Bug Report ==== === 1. Macros affect verbatim environments === Macro definitions go through all environments (, , %%, ) and this is not only a problem (it's impossible to present the macro syntax when it is installed) but also dangerous, because it manipulates source codes which are presented on the wiki. Any solution for that? --- [[user>mubed|mubed]] //2012/05/24 17:32// === 2. Edit button disappeared === The "edit" button for page sections disappear after installing the macros plugin. > :!: one idea is to disable ''global $conf; $conf['maxseclevel'] = 0;'' in action.php >>>[[http://forum.dokuwiki.org/post/26514]] > > The author says: The plugin definitely would benefit from better integration. It was created as a quick port of a module from my own experiments with another wiki. > >If a macro is processed, that changes the length of a section text. It may even generate new sections! I could not find how to make dokuwiki adjust the sections (and positions of edit buttons) properly, therefore I decided to disable the section buttons, when a macro is involved in generating page text. Like so, although this is an ugly hack, I think: > > if ($data != $event->data) { // disable section edit if any change took place global $conf; $conf['maxseclevel'] = 0; $event->data = $data; } > If anyone, who knows well how dokuwiki environments work, could improve the plugin integration, it would be most appreciated! And what about this one? Any better idea? --- [[user>mubed|mubed]] //2012/05/24 17:32// I have started a thread form regarding this: https://forum.dokuwiki.org/thread/9138 --- Cristian //2012/11/22// ==== Feature Requests ==== === add autolink2 compatibility === The plugin [[plugin:autolink2]] substitutes defined words with corresponding internal page links.\\ Unfortunately the replacements through macros are **not substituted**.\\ Is there any way to change that? It will be great! //Joachim 2011-11-05// === seems to be working == This code, run by the latest version of the plugin, with Cristian's changes, properly links "some name" 6 times. (I do not think that the changes made it to do so - perhaps some update in the DokuWiki core?) {{$SN=@0ome @1ame$}} The text on the page. Blah, blah, blah... And of course the text Some Name. Also some name is valid, as well as SOME NAME. |The test can be in a table also| Some Name, **but** there needs to be a space after the leading`|| through a macro: $SN[S|N] | $SN[s|n] //Ian 2012-03-05// ==== New Feature Added ==== Thanks to Cristian Spiescu for submitting a patch which now has been rolled into the plugin. It is possible to specify a "global include" page (as namespace:page) in Configuration Manager/Macros Plugin Setting. Macro definitions from that page become available in the whole wiki.