I'm looking for a part-time remote job.

Hire me

I'm the author of:

Mastering Redmine is a comprehensive guide with tips, tricks and best practices, and an easy-to-learn structure.

Check the book's project or

Buy the book

Social pages of the book:

By buying this book you also donate to Redmine (see this page).

Follow me:

Supporting mentions in third-party plugins

WikiNG mentions were designed to work for any textilizable (i.e., Wiki syntax-powered) content.

Here “to work” means:

  • Render user# and user: rules as links.
  • Add objects, that mention users, to these users’ mention lists, which can be found under the “Mentions” tab in their profiles.

However, omissions in the code or incomplete object classes may make mentions fail to work!

So, here are some recommendations and tricks you can use to make your objects support WikiNG mentions.

Always specify the object for the #textilizable method

The Wiki content is rendered using the Redmine’s textlizable method, that requires only the text content. However, in order to be able to add a mention WikiNG must know the object, that mentions the user...

Anyway, specifying the object for textilizable should be considered to be a good practice! As many other plugins may rely on this too.

There are two ways to specify the object for the textilizable method:

  1. textilizable(object, :method_returning_text)
    This is the preferred style!
  2. textilizable(text, :object => object)
    Use this style, if you cannot use the first one.

Make sure, that the object utilizes the Event API

The mention list resembles the activity list (therefore, both appear under tabs in a single tabbed menu). The activity list is implemented using the Event API. So, WikiNG uses the same API to implement mentions (this API is also used for implementing search results, by the way).

Even if you do not want your objects to appear in the activity list, implement the event interface for your object to support mentions (consider also adding support for the search)! Event API interface for the object alone does not make it appear in the activity list.

A Redmine’s “event” object should support the following methods:

  • event_type – used as the class name for the mention.
  • event_author – the user, who mentioned the mentioned one.
    It’s not returned for Wiki pages, as Wiki pages can have many authors.
  • event_title – the title of the event object.
  • event_url – the URL to the object.
  • event_description – short description or excerpt of the object.

The “event” object must have updated_on or created_on method. Optionally, it can have project.

Don’t worry – these changes are not enough for your objects to appear in the activity list (you would also need to implement the activity provider and the event observer for this).

Implement a better support

Considering the previous instructions: if you use the textilizable method in the right way and if your object implements the Event API, mentions should work just fine. But...

Sometimes you may want to avoid altering the event API (for example, if you use it for activities). So let’s now speak, how can you add support for mentions in other ways:

Use the special Mention API

These methods should be used, if you want to provide special values intended just for mentions and/or ensure, that they won’t be used for anything else. This API was designed to be similar to the Redmine Event API.

  • mentioning_date – used as the date, when the user was mentioned
  • mentioning_class – used as the class name for the mention.
  • mentioning_project – used as the project of the mentioning object.
  • mentioning_title – used as the title of the mentioning object.
  • mentioning_url – used as the URL to the mentioning object.
  • mentioning_description – used as the description of the object.
  • mentioning_author – used as the author, who mentioned the user.

Use other suitable methods

These methods are used, only when no better methods are available! I.e., these are fallback methods! So, certainly, you should avoid using them...

However, you may find these methods useful, if you want to provide the same values for several cases (i.e., you are about to use them not only for mentions).

  • title, subject or name – the title of the mentioning object.
  • url – the URL to the object, that mentions the user.
  • summary, description or text – the description of the object.
  • author – who mentioned the user.
Terms of use | Privacy policy