User Mentions API
API to support the mention of users |
Type | JAR |
Category | |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Bundled With | XWiki Standard |
Table of contents
Description
The User Mentions API allows to configure how the mentions are sent, and to registers new kinds of mentionable actors.
Configuration
The MentionsConfiguration provides the shared constants and configurable values used for the mentions:
- USER_MENTION_TYPE: the default type of mentions
- getMentionsColor(): the default background color of the mentions
- getSelfMentionsColor() the default background color of the mentions to the current user
- isQuoteActivated() returns true if a quote of the text surrounding a mention must be generated when sending a notification
Integrating a new mention type
Declaring a new mention type is made in three steps.
Declaring a formatter
The formatter is used to display the mentioned actor in a textual form according to its type.
Three display styles can be asked for:
- full name (first and last names)
- first name only
- login
Declaring a provider is done by declaring a component with the role org.xwiki.mentions.MentionsFormatter.
For instance:
import javax.inject.Singleton;
import org.xwiki.component.annotation.Component;
import org.xwiki.mentions.DisplayStyle;
import org.xwiki.mentions.MentionsFormatter;
@Singleton
@Component
@Named("example") // the hint must match the type of actor
public class ExampleMentionsFormatter implements MentionsFormatter
{
@Override
public String formatMention(String actorReference, DisplayStyle style)
{
switch (style) {
case FULL_NAME:
return "...full name...";
case FIRST_NAME:
return "...first name...";
case LOGIN:
return "...login...";
default:
return null;
}
}
}
Declaring a listener
When new mentions are identified in the wiki, a org.xwiki.mentions.events.NewMentionsEvent event is sent.
The data attached to this event is an object of type org.xwiki.mentions.notifications.MentionNotificationParameters and contains the information relative to the locations of the new mentions, their author, and the list and type of the new mentions.
To listen to this event, an org.xwiki.observation.EventListener component should be declared (see WritingEventListenerTutorial)
For instance:
import java.util.Set;
import javax.inject.Named;
import javax.inject.Singleton;
import org.xwiki.component.annotation.Component;
import org.xwiki.mentions.events.NewMentionsEvent;
import org.xwiki.mentions.notifications.MentionNotificationParameter;
import org.xwiki.mentions.notifications.MentionNotificationParameters;
import org.xwiki.observation.EventListener;
import org.xwiki.observation.event.Event;
import static java.util.Collections.singletonList;
@Component
@Named(ExampleMentionsEventListener.TYPE)
@Singleton
public class ExampleMentionsEventListener implements EventListener
{
public static final String TYPE = "ExampleMentionsEventListener";
@Override
public String getName()
{
return TYPE;
}
@Override
public List<Event> getEvents()
{
// Listen to the NewMentionsEvent.
return singletonList(new NewMentionsEvent());
}
@Override
public void onEvent(Event event, Object source, Object data)
{
if (data instanceof MentionNotificationParameters) {
MentionNotificationParameters mentionNotificationParameters = (MentionNotificationParameters) data;
// Get the mentions to actors of type "example".
Set<MentionNotificationParameter> exampleMentions =
mentionNotificationParameters.getNewMentions().get("example");
// If some users of type example have been mentioned
if (exampleMentions != null) {
exampleMentions.forEach(mentionNotificationParameter -> {
// Notify the mentioned actors of type "example" ...
});
}
}
}
}
Declaring an actor provider
Scripting
* See the NOTICE file distributed with this work for additional
* information regarding copyright ownership.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.xwiki.mentions.script;
import javax.inject.Inject;
import javax.inject.Named;
import javax.inject.Singleton;
import org.apache.commons.lang3.StringUtils;
import org.xwiki.component.annotation.Component;
import org.xwiki.mentions.DisplayStyle;
import org.xwiki.mentions.MentionsConfiguration;
import org.xwiki.mentions.MentionsFormatter;
import org.xwiki.mentions.internal.MentionFormatterProvider;
import org.xwiki.mentions.internal.MentionsEventExecutor;
import org.xwiki.script.service.ScriptService;
import org.xwiki.stability.Unstable;
/**
* Script service for the Mentions application.
*
* @version $Id: a4fd022d49f57d2f6c6562129fc6a6d49eed6b85 $
* @since 12.5RC1
*/
@Component
@Singleton
@Unstable
@Named("mentions")
public class MentionsScriptService implements ScriptService
{
@Inject
private MentionsConfiguration configuration;
@Inject
private MentionFormatterProvider mentionFormatterProvider;
@Inject
private MentionsEventExecutor eventExecutor;
/**
*
* @see MentionsConfiguration#getMentionsColor()
* @return the mentions color configuration value.
*/
public String getMentionsColor()
{
return this.configuration.getMentionsColor();
}
/**
*
* @see MentionsConfiguration#getSelfMentionsColor()
* @return the mentions colors configuration value for the current user.
*/
public String getSelfMentionsColor()
{
return this.configuration.getSelfMentionsColor();
}
/**
* @see MentionsEventExecutor#getQueueSize()
* @return the current size of the queue of elements (page, comments...) with mentions to analyze
* @since 12.6
*/
@Unstable
public long getQueueSize()
{
return this.eventExecutor.getQueueSize();
}
/**
*
* @see MentionsConfiguration#isQuoteActivated()
* @return {@code true} if the mentions quote feature is activated.
* @since 12.6
*/
public boolean isQuoteActivated()
{
return this.configuration.isQuoteActivated();
}
/**
* Format an actor mention according to its type.
*
* @param actorReference the reference of the mentioned actor
* @param style the display style
* @param type the type of the actor to format
* @return the formatted actor mention
* @see MentionsFormatter#formatMention(String, DisplayStyle)
* @since 12.10
*/
@Unstable
public String format(String actorReference, DisplayStyle style, String type)
{
// Uses the "user" type when the mention has an undefined type.
String hint;
if (StringUtils.isEmpty(type)) {
hint = MentionsConfiguration.USER_MENTION_TYPE;
} else {
hint = type;
}
return this.mentionFormatterProvider.get(hint).formatMention(actorReference, style);
}
}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-mentions-api 16.8.0):
- org.xwiki.platform:xwiki-platform-eventstream-api 16.8.0
- org.xwiki.platform:xwiki-platform-model-api 16.8.0
- org.xwiki.platform:xwiki-platform-index-api 16.8.0
- org.xwiki.rendering:xwiki-rendering-api 16.8.0