Module: Redmine::WikiFormatting::Macros
- Defined in:
- lib/redmine/wiki_formatting/macros.rb
Defined Under Namespace
Modules: Definitions
Constant Summary collapse
- @@available_macros =
{}
- @@inline_attachments =
true
Class Method Summary collapse
-
.desc(txt) ⇒ Object
Sets description for the next macro to be defined.
-
.macro(name, options = {}, &block) ⇒ Object
Defines a new macro with the given name, options and block.
-
.register(&block) ⇒ Object
Plugins can use this method to define new macros:.
Class Method Details
.desc(txt) ⇒ Object
Sets description for the next macro to be defined
168 169 170 |
# File 'lib/redmine/wiki_formatting/macros.rb', line 168 def desc(txt) @@desc = txt end |
.macro(name, options = {}, &block) ⇒ Object
Defines a new macro with the given name, options and block.
Options:
-
:desc - A description of the macro
-
:parse_args => false - Disables arguments parsing (the whole arguments string is passed to the macro)
Macro blocks accept 2 or 3 arguments:
-
obj: the object that is rendered (eg. an Issue, a WikiContent…)
-
args: macro arguments
-
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.
Examples: By default, when the macro is invoked, the comma 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:
macro :my_macro do |obj, args|
# args is an array
# and this macro do not accept a block of text
end
You can disable arguments spliting with the :parse_args => false option. In this case, the full string of arguments is passed to the macro:
macro :my_macro, :parse_args => false do |obj, args|
# args is a string
end
Macro can optionally accept a block of text:
macro :my_macro do |obj, args, text|
# this macro accepts a block of text
end
Macros are invoked in formatted text 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 passe to the macro (invoking a macro that do not accept a block of text with some text will fail). Examples:
No arguments:
{{my_macro}}
With arguments:
{{my_macro(arg1, arg2)}}
With a block of text:
{{my_macro
multiple lines
of text
}}
With arguments and a block of text
{{my_macro(arg1, arg2)
multiple lines
of text
}}
If a block of text is given, the closing tag }} must be at the start of a new line.
152 153 154 155 156 157 158 159 160 161 162 163 164 165 |
# File 'lib/redmine/wiki_formatting/macros.rb', line 152 def macro(name, ={}, &block) .assert_valid_keys(:desc, :parse_args) unless /\A\w+\z/.match?(name.to_s) raise "Invalid macro name: #{name} (only 0-9, A-Z, a-z and _ characters are accepted)" end unless block_given? raise "Can not create a macro without a block!" end name = name.to_s.downcase.to_sym available_macros[name] = {:desc => @@desc || ''}.merge() @@desc = nil Definitions.send :define_method, "macro_#{name}", &block end |
.register(&block) ⇒ Object
Plugins can use this method to define new macros:
Redmine::WikiFormatting::Macros.register do
desc "This is my macro"
macro :my_macro do |obj, args|
"My macro output"
end
desc "This is my macro that accepts a block of text"
macro :my_macro do |obj, args, text|
"My macro output"
end
end
86 87 88 |
# File 'lib/redmine/wiki_formatting/macros.rb', line 86 def register(&block) class_eval(&block) if block_given? end |