RedmineMacros » History » Version 1

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

1 1 Jean-Philippe Lang
h1. Macros
2 1 Jean-Philippe Lang
3 1 Jean-Philippe Lang
{{>toc}}
4 1 Jean-Philippe Lang
5 1 Jean-Philippe Lang
h2. Invoking macros in formatted text
6 1 Jean-Philippe Lang
7 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).
8 1 Jean-Philippe Lang
9 1 Jean-Philippe Lang
Examples:
10 1 Jean-Philippe Lang
11 1 Jean-Philippe Lang
<pre>
12 1 Jean-Philippe Lang
No arguments:
13 1 Jean-Philippe Lang
{{my_macro}}
14 1 Jean-Philippe Lang
15 1 Jean-Philippe Lang
With arguments:
16 1 Jean-Philippe Lang
{{my_macro(arg1, arg2)}}
17 1 Jean-Philippe Lang
18 1 Jean-Philippe Lang
With a block of text:
19 1 Jean-Philippe Lang
{{my_macro
20 1 Jean-Philippe Lang
multiple lines
21 1 Jean-Philippe Lang
of text
22 1 Jean-Philippe Lang
}}
23 1 Jean-Philippe Lang
24 1 Jean-Philippe Lang
With arguments and a block of text
25 1 Jean-Philippe Lang
{{my_macro(arg1, arg2)
26 1 Jean-Philippe Lang
multiple lines
27 1 Jean-Philippe Lang
of text
28 1 Jean-Philippe Lang
}}
29 1 Jean-Philippe Lang
</pre>
30 1 Jean-Philippe Lang
31 1 Jean-Philippe Lang
If a block of text is given, the closing tag @}}@ must be at the start of a new line.
32 1 Jean-Philippe Lang
33 1 Jean-Philippe Lang
h2. Adding custom macros
34 1 Jean-Philippe Lang
35 1 Jean-Philippe Lang
Custom macros can be added from a Redmine plugin using the following syntax:
36 1 Jean-Philippe Lang
37 1 Jean-Philippe Lang
<pre><code class="ruby">
38 1 Jean-Philippe Lang
Redmine::WikiFormatting::Macros.macro(name, options={}, &block)
39 1 Jean-Philippe Lang
</code></pre>
40 1 Jean-Philippe Lang
41 1 Jean-Philippe Lang
Options:
42 1 Jean-Philippe Lang
43 1 Jean-Philippe Lang
* @:desc@ - A description of the macro
44 1 Jean-Philippe Lang
* @:parse_args => false@ - Disables arguments parsing (the whole arguments string is passed to the macro)
45 1 Jean-Philippe Lang
46 1 Jean-Philippe Lang
Macro blocks accept 2 or 3 arguments:
47 1 Jean-Philippe Lang
* @obj@ - the object that is rendered (eg. an Issue, a WikiContent...)
48 1 Jean-Philippe Lang
* @args@ - the macro arguments
49 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.  
50 1 Jean-Philippe Lang
51 1 Jean-Philippe Lang
Examples:
52 1 Jean-Philippe Lang
53 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:
54 1 Jean-Philippe Lang
55 1 Jean-Philippe Lang
<pre><code class="ruby">
56 1 Jean-Philippe Lang
macro :my_macro, :desc => 'This is a custom macro' do |obj, args|
57 1 Jean-Philippe Lang
  # args is an array
58 1 Jean-Philippe Lang
  # and this macro does not accept a block of text
59 1 Jean-Philippe Lang
end
60 1 Jean-Philippe Lang
</code></pre>
61 1 Jean-Philippe Lang
62 1 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:
63 1 Jean-Philippe Lang
64 1 Jean-Philippe Lang
<pre><code class="ruby">
65 1 Jean-Philippe Lang
macro :my_macro, :parse_args => false do |obj, args|
66 1 Jean-Philippe Lang
  # args is a string
67 1 Jean-Philippe Lang
end
68 1 Jean-Philippe Lang
</code></pre>
69 1 Jean-Philippe Lang
70 1 Jean-Philippe Lang
Macro can optionally accept a block of text:
71 1 Jean-Philippe Lang
72 1 Jean-Philippe Lang
<pre><code class="ruby">
73 1 Jean-Philippe Lang
macro :my_macro do |obj, args, text|
74 1 Jean-Philippe Lang
  # this macro accepts a block of text
75 1 Jean-Philippe Lang
  # text is a String that represent the whole of text passed to the macro
76 1 Jean-Philippe Lang
end
77 1 Jean-Philippe Lang
</code></pre>