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