Writing your own macro
Create a python file called MacroName.py located in your data/plugin/macro directory. Ensure it has a single function called macro_MacroName(macro, arg1, arg2, ...), which is the entry-point.
the first argument macro is an instance of class Macro, and also evaluates to a string of the macroname,
- arguments arg1, arg2, ... are the arguments given by the user, but special rules apply, see below.
You can access the request object by using macro.request - e.g. to access form parameters and other information related to user interaction.
Your function should use the formatter to construct valid markup for the current target format. In most cases this is HTML, so writing a macro which returns HTML will work in most cases but fail when formats like XML or text/plain are requested - you can use macro.formatter to access the current formatter.
For example, your wiki page has the following line on it:
<<MacroName(True, 1.7772, 17)>>
You could write a MacroName.py file like this:
1 from MoinMoin.wikiutil import get_unicode, get_bool, get_int, get_float
2
3 Dependencies = []
4 generates_headings = False
5
6 def macro_MacroName(macro, arg1, arg2, arg3=7):
7 # arguments passed in can be None or a unicode object
8
9 arg1 = get_bool(macro.request, arg1)
10 arg2 = get_float(macro.request, arg2)
11 # because arg3 has a default of 7, it is always of type int or long
12
13 return macro.formatter.text("arguments are: %s %2.3f %d" % (arg1, arg2, arg3))
![/!\](/moin_static19/modernized/img/alert.png "/!\")
Add an entry into Dependencies if the output from your macro should not be cached. This is important if the macro output could change from one moment to another, for example if your macro searches in wiki pages which may be being edited by other users, or loads information from an external database whose contents may change. Currently the value of any entry does not matter and may be considered a short description for 'why results from this macro should not be cached', but please look at the entries used in other macros for values which may be suitable.
If your macro can generate headings (by calling macro.formatter.heading()) then set generates_headings to True to allow the TableOfContents macro to evaluate your macro for headings to take into the table of contents.
Macro arguments
The arguments given to your macro are normally passed as unicode instances or None if the user gave no argument.
Consider this example macro:
and the wiki code (together with the result)
1. <<Example()>> - passes None, None
2. <<Example(a,b)>> - passes u'a', u'b'
3. <<Example(,)>> - passes None, None
4. <<Example("",)>> - passes u'', None
default values
If your macro declares default values as in this example:
Then the arguments can be skipped or left out and are automatically converted to the type of the default value:
1. <<Example()>> - passes 7, 2.1 2. <<Example(,3)>> - passes 7, 3.0 3. <<Example(2)>> - passes 2, 2.1 4. <<Example(a,7.54)>> - error, "a" not an integer
Additionally, it is possible to declare the type you would like to get:
def macro_Example(macro, arg1=int, arg2=float): ...
This requires that the user enters the correct parameter types, but it is possible to skip over them by giving an empty argument in which case it'll be passed into the macro code as None:
1. <<Example()>> - passes None, None 2. <<Example(a, 2.2)>> - error, "a" not an integer 3. <<Example(7, 2.2)>> - passes 7, 2.2 4. <<Example(, 3.14)>> - passes None, 3.14
unit arguments
If your macro declares unitsarguments then units are required as in this example:
The defaultunit of px is used if the user does not enter a unit. He has to enter valid units of px or %.
1. <<Example()>> - argument is: None 2. <<Example(100)>> - argument is: 100px 3. <<Example(100mm)>> - <<Example: Invalid unit in value 100mm (allowed units: px, %)>> 4. <<Example(100px)>> - argument is: 100px
choices
If your plugin takes one of several choices, you can declare it as such:
This requires that the user enter any of the given choices and uses the first choice if nothing is entered:
1. <<Example(apple)>> - passes u'apple' 2. <<Example(OrAnGe)>> - error, tells user which choices are valid 3. <<Example()>> - passes u'apple'
required arguments
If you require some arguments, you can tell the generic code by using the required_arg class that is instantiated getting the type of the argument:
from MoinMoin.wikiutil import required_arg def macro_Example(macro, arg1=required_arg(int)): ...
This requires that the user enters the argument:
1. <<Example()>> - error, argument "arg1" required 2. <<Example(4.3)>> - error, "4.3" not an integer 3. <<Example(5)>> - passes 5
keyword arguments
If your macro needs to accept arbitrary keyword arguments to pass to something else, it must declare a _kwargs parameter which should default to the empty dict:
This makes the user able to pass in anything, even arbitrary unicode strings as key names:
1. <<Example(äöü=7)>> - passes the dict {u'äöü': u'7'}
2. <<Example(=7)>> - passes the dict {u'': u'7'}
3. <<Example(a=1,"d e"=3)>> - passes the dict {u'a': u'1', u'd e': u'3'}
4. <<Example(a)>> - error, too many (non-keyword) arguments
trailing arguments
Trailing arguments allow your macro to take any number of positional arguments, or to be able to handle the syntax of some existing macros that looks like
<<Macro(1, 2, 3, name=value, name2=value2, someflag, anotherflag)>>
In order to handle this, declare a _trailing_args macro parameter which should have a an empty list as the default:
Also, when the user gives too many arguments, these are put into _trailing_args as in the second example:
1. <<Example(1, 2, 3, name=test, name2=test2, flag1)>> - valid, passes u'flag1' in _trailing_args 2. <<Example(1, 2, 3, test, test2, flag1)>> - same
It is possible to use this feature together with the arbitrary keyword arguments feature _kwargs.