Module: Redmine::WikiFormatting::Macros

Defined in:
lib/redmine/wiki_formatting/macros.rb

Defined Under Namespace

Modules: Definitions

Constant Summary

@@available_macros = 
{}

Class Method Summary collapse

Class Method Details

.desc(txt) ⇒ Object

Sets description for the next macro to be defined



157
158
159
 
# File 'lib/redmine/wiki_formatting/macros.rb', line 157

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.



142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/redmine/wiki_formatting/macros.rb', line 142

def macro(name, options={}, &block)
  options.assert_valid_keys(:desc, :parse_args)
  unless name.to_s.match(/\A\w+\z/)
    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(options)
  @@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



76
77
78
 
# File 'lib/redmine/wiki_formatting/macros.rb', line 76

def register(&block)
  class_eval(&block) if block_given?
end