RedmineMacros » History » Version 2

Jean-Philippe Lang, 2012-10-17 22:20

1 1 Jean-Philippe Lang
h1. Macros
2 1 Jean-Philippe Lang
3 1 Jean-Philippe Lang
{{>toc}}
4 1 Jean-Philippe Lang
5 2 Jean-Philippe Lang
Redmine includes a macros system that lets you add custom functions to insert dynamic content in formatted text.
6 2 Jean-Philippe Lang
7 1 Jean-Philippe Lang
h2. Invoking macros in formatted text
8 1 Jean-Philippe Lang
9 1 Jean-Philippe Lang
Macros are invoked using double curly brackets. Arguments must be enclosed in parenthesis if any. A new line after the macro name or the arguments starts the block of text that will be passed to the macro (invoking a macro that do not accept a block of text with some text will fail).
10 1 Jean-Philippe Lang
11 1 Jean-Philippe Lang
Examples:
12 1 Jean-Philippe Lang
13 1 Jean-Philippe Lang
<pre>
14 1 Jean-Philippe Lang
No arguments:
15 1 Jean-Philippe Lang
{{my_macro}}
16 1 Jean-Philippe Lang
17 1 Jean-Philippe Lang
With arguments:
18 1 Jean-Philippe Lang
{{my_macro(arg1, arg2)}}
19 1 Jean-Philippe Lang
20 1 Jean-Philippe Lang
With a block of text:
21 1 Jean-Philippe Lang
{{my_macro
22 1 Jean-Philippe Lang
multiple lines
23 1 Jean-Philippe Lang
of text
24 1 Jean-Philippe Lang
}}
25 1 Jean-Philippe Lang
26 1 Jean-Philippe Lang
With arguments and a block of text
27 1 Jean-Philippe Lang
{{my_macro(arg1, arg2)
28 1 Jean-Philippe Lang
multiple lines
29 1 Jean-Philippe Lang
of text
30 1 Jean-Philippe Lang
}}
31 1 Jean-Philippe Lang
</pre>
32 1 Jean-Philippe Lang
33 1 Jean-Philippe Lang
If a block of text is given, the closing tag @}}@ must be at the start of a new line.
34 1 Jean-Philippe Lang
35 1 Jean-Philippe Lang
h2. Adding custom macros
36 1 Jean-Philippe Lang
37 1 Jean-Philippe Lang
Custom macros can be added from a Redmine plugin using the following syntax:
38 1 Jean-Philippe Lang
39 1 Jean-Philippe Lang
<pre><code class="ruby">
40 1 Jean-Philippe Lang
Redmine::WikiFormatting::Macros.macro(name, options={}, &block)
41 1 Jean-Philippe Lang
</code></pre>
42 1 Jean-Philippe Lang
43 1 Jean-Philippe Lang
Options:
44 1 Jean-Philippe Lang
45 1 Jean-Philippe Lang
* @:desc@ - A description of the macro
46 1 Jean-Philippe Lang
* @:parse_args => false@ - Disables arguments parsing (the whole arguments string is passed to the macro)
47 1 Jean-Philippe Lang
48 1 Jean-Philippe Lang
Macro blocks accept 2 or 3 arguments:
49 1 Jean-Philippe Lang
* @obj@ - the object that is rendered (eg. an Issue, a WikiContent...)
50 1 Jean-Philippe Lang
* @args@ - the macro arguments
51 1 Jean-Philippe Lang
* @text@ - the block of text given to the macro (should be present only if the macro accepts a block of text). text is a String or nil if the macro is invoked without a block of text.  
52 1 Jean-Philippe Lang
53 2 Jean-Philippe Lang
The block is called each time the macro is invoked in formatted text and its return value is inserted in the final output. This return value must be a html escaped string.
54 2 Jean-Philippe Lang
55 1 Jean-Philippe Lang
Examples:
56 1 Jean-Philippe Lang
57 1 Jean-Philippe Lang
By default, when the macro is invoked, the coma separated list of arguments is split and passed to the macro block as an array. If no argument is given the macro will be invoked with an empty array:
58 1 Jean-Philippe Lang
59 1 Jean-Philippe Lang
<pre><code class="ruby">
60 1 Jean-Philippe Lang
macro :my_macro, :desc => 'This is a custom macro' do |obj, args|
61 1 Jean-Philippe Lang
  # args is an array
62 1 Jean-Philippe Lang
  # and this macro does not accept a block of text
63 1 Jean-Philippe Lang
end
64 1 Jean-Philippe Lang
</code></pre>
65 1 Jean-Philippe Lang
66 2 Jean-Philippe Lang
You can disable arguments spliting with the @:parse_args => false@ option. In this case, the full string of arguments is passed to the macro:
67 1 Jean-Philippe Lang
68 1 Jean-Philippe Lang
<pre><code class="ruby">
69 1 Jean-Philippe Lang
macro :my_macro, :parse_args => false do |obj, args|
70 1 Jean-Philippe Lang
  # args is a string
71 1 Jean-Philippe Lang
end
72 1 Jean-Philippe Lang
</code></pre>
73 1 Jean-Philippe Lang
74 2 Jean-Philippe Lang
Macro can optionally accept a block of text as a third argument:
75 1 Jean-Philippe Lang
76 1 Jean-Philippe Lang
<pre><code class="ruby">
77 1 Jean-Philippe Lang
macro :my_macro do |obj, args, text|
78 1 Jean-Philippe Lang
  # this macro accepts a block of text
79 1 Jean-Philippe Lang
  # text is a String that represent the whole of text passed to the macro
80 1 Jean-Philippe Lang
end
81 1 Jean-Philippe Lang
</code></pre>
82 2 Jean-Philippe Lang
83 2 Jean-Philippe Lang
As a starting point for writing your own macros, you can have a look at the builtin macros definitions: source:/tags/2.1.0/lib/redmine/wiki_formatting/macros.rb#L162