User Mentions API

Last modified by Admin on 2024/10/28 18:24
cogAPI to support the mention of users
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

  Download v16.9.0SourcesIssues

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

This step is optional. When no formatter is provided for a given type, the default formatter is used. In this case the identifier of the mentioned actors is displayed without further formatting.

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.Named;
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.List;
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

This features is not yet available as of XWiki 12.10.

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.9.0):

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected