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.

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.