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

Class Method Details

.desc(txt) ⇒ Object

Sets description for the next macro to be defined


167
168
169
# File 'lib/redmine/wiki_formatting/macros.rb', line 167

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
# File 'lib/redmine/wiki_formatting/macros.rb', line 152

def macro(name, options={}, &block)
  options.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(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

86
87
88
# File 'lib/redmine/wiki_formatting/macros.rb', line 86

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