Module: Redmine::WikiFormatting::Macros

Defined in:

lib/redmine/wiki_formatting/macros.rb

Defined Under Namespace

Modules: Definitions

Constant Summary

@@available_macros =

{}

@@inline_attachments =

true

Class Method Summary

• .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

# 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.

# 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

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

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