DM - Dynamic Mentions

Table of contents:

Description

DM is a Question2Answer plugin that allows users to be mentioned using the @user syntax.

Features

• Easily transform a username into a clickable link when writing a post (mention)
• Users can be selected from a popup list of matched users
• An additional user field can be displayed in the popup (e.g. the full name of the user)
• Mentions can be used in questions, answers and comments
• Full and basic editors can be selected for each kind post
• Flexible Notifications System plugin integration that allows mentioned users to receive a notifications
• The admin can choose to enable sending email notifications to mentioned users
• User permits can be configured to allow a minimum user level allowed to generate mentions
• Very simple installation
• Upgrade system support: the plugin is able to properly upgrade from previous versions
• Full internationalization support (Spanish translation included)
• Does not require any core hack and does not modify the core tables structure

Requirements

These are the technical requirements for the plugin to work properly:

• Q2A core version 1.8.*

Limitations

• This plugin does not support external users.
• This plugin is not tested with non-english characters. You can test it in the demo site.
• This plugin will replace your default editor.

Installation steps

1. Copy the pupi-dm directory into the qa-plugin directory.
2. Navigate to admin/plugins and enable the Dynamic Mentions plugin.
3. Navigate to admin/posting and select PUPI DM Editor in the Default editor for questions/answers/comments field. Make sure you do not set both the PUPI DM Editor and the WYSIWYG Editor for two different post types. For example, if you set the PUPI DM Editor to handle questions and answers, then do not set the WYSIWYG Editor for comments. It is still possible to set the Basic Editor for comments. Just do not mix the PUPI DM Editor and the WYSIWYG Editor.

Sample usage and screenshots

Let's start with a screenshot of a post:

In the screenshot above it is displayed a link to john's profile and the popup with the user selection that matches the text @jo. The popup for the user selection has three fields:

• An avatar: it is taken from the user's profile or from the site's default avatar, depending on how Q2A is configured.
• A user name: the unique user identification (a.k.a. handle).
• An extra field: it could be any field from the user profile (or even no field at all). The field to display can be selected from the admin settings.

In order to select a user it is possible to click on it or locate it with the keyboard arrows and either press the Enter or Tab keys.

Type of editors per post

It is possible to select two type o editors: the full and the basic one.

• The full editor is the standard CKEditor and should look exactly the same as the WYSIWYG editor distributed with Q2A:
• The basic editor is a simplified version of the full editor which doesn't have the toolbars but still allows users to create user mentions: Note the format of the post saved with the basic editor is HTML and not plain text.

The type of editor that is displayed per post type can be configured in the plugin settings. Note that setting the type of editor does not mean it is possible to omit setting the PUPI DM Editor in the admin/posting section, as explained in the installation steps.

Notifications

There are 2 notification systems supported: email notifications and notifications through the Flexible Notifications System plugin.

Either notification is fired whenever a post is saved and contains a newly mentioned user. That means that if a post is created and the user @john is mentioned, that user will receive a notification. If the post is later edited and another user is mentioned in addition to @john, for example, @peter, then only @peter will receive the notification.

Here is a short description of the different notification types:

• Email notifications: these can be enabled from the plugin settings and the texts can be configured from the language files, in a similar way as Q2A's own email language files. It is possible to configure both: the subject and the body of the email.

• Flexible Notifications System: these can be enabled from the plugin settings and require the Flexible Notifications System plugin installed and enabled. This is what a notification looks like:

  

User matching and site performance

There are some things and limitations to bear in mind regarding how user names are matched while writing a post:

• The matching starts when writing an @ followed by, at least, 2 user name characters. This is used not to query the server too often.
• The matching finishes after selecting a user or after typing any of the following 6 characters: @/ ,:;. If a developer would like to change this, it can be changed from the injector.js file but there will not be any support or assistance provided on how to do so. Keeping spaces as user name delimiters considerably decreases the amount of queries to the server.
• In order to match a user that has a space in its user name, e.g. John Smith, a plus sign will need to be used, such as @john+smith. Again, using spaces as user name delimiters improves performance.
• Matching of user names happens from left to right, which means if there are two users named John Smith and Smith John and the current users types @john only John Smith will be matched. This limitation considerably improves performance.
• There will be a maximum of 7 users displayed in the popup.

It's important to note that the limitations are intentional and are present to keep a healthy and performant Q2A site.

Admin section

Here is a screenshot of the admin section:

Here is a description of the main settings the admin can change:

• Users fetch type: defines how the user popup is filled with users. There are 2 possible values:
  • Local: users are fetched from the users that are involved in the question thread. In other words, it is possible to tag every user that posted the question, an answer or any comment to the question or answers. That way, the users to mention are limited to the ones that are involved. Note if a user only has hidden posts in the thread, they will not be displayed. Fetching users locally is also the fastest way to fetch them. There is no need to fetch them from the server because they are already known in advance.
  • Remote: users are fetched in the same was as in the Local approach but results are complemented from users from the server. In other words, the popup will display all users that match the search string, prioritizing users involved in the question thread and then users that are not involved in the question thread. In this case, users will need to be searched for in the server, which means there will be a delay while fetching them, in the same way there is a delay while accessing any question post in a Q2A site. In order to show the user that something is going on behind the scenes while they are typing a user name, a dynamic loading indicator is displayed as the last item in the popup. Here is a screenshot with the loading indicator: In the screenshot above, it is important to note that a user is already being displayed in the popup. This is because, as explained before, any user already involved in the question thread is displayed immediately (with no server request) and once the users from the server are returned, they are added to the popup.
• Users mention option: provides filtering capabilities to the users that can be mentioned. The filtering is applied when using the Remote user fetch type and ignores the users fetched locally (the ones that are already part of the thread). These are the possible values:
  • All users: no filtering is applied and any user is able to mention any other user
  • Only users who have favorited each other: mention suggestions is restricted to the users that have been favorited by the logged in user and viceversa
  • Only users who have favorited the mentioning user: mention suggestions is restricted to users who have favorited the logged in user
  • Only users who the mentioning user has favorited: mention suggestions is restricted to the users that have been favorited by the logged in user
• Type of editor for questions: allows the admin to define the type of editor used in questions, as explained in Type of editors per post.
• Type of editor for answers: allows the admin to define the type of editor used in answers, as explained in Type of editors per post.
• Type of editor for comments: allows the admin to define the type of editor used in comments, as explained in Type of editors per post.
• Extra field on popup: this is one of the user fields created in the site. The admin can select one (or none) of them. If one is selected, the information the user has added to their profile in that field will be displayed next to the user name in the popup. Note it will be displayed as plain text, without any formatting or markup.
• Minimum mention user permit: allows the admin to define which is the minimum user level that will be allowed to mention other users. For example, if the permit is set to Editors and above, then registered users won't be able to mention other users.
• Enable Flexible Notifications System integration: enables the integration with the Flexible Notifications System plugin. If that plugin is not installed or is disabled, this setting should be disabled. There is more information in the Notifications section.
• Enable email notifications: enables sending email notifications to mentioned users. There is more information in the Notifications section.
• Enable uploading images: enables Q2A to receive image uploads. This feature is similar to the one in the WYSIWYG Editor.
• Enable uploading uploading other file types: enables Q2A to receive any kind of files as an upload. Note that exactly in the same way as it works with the WYSIWYG Editor, this feature is not really usable from the user interface.
• Maximum file upload size in MB (max 2.0): sets the maximum upload file size as a float number. The limit is set by the web server and PHP configuration. This feature is similar to the one in the WYSIWYG Editor.

All these settings will take affect once the Save settings button is pressed.

Upgrading CKEditor

Instructions are included in a text file named UPGRADE.txt in the plugin directory.

Support

Technical support must all go through the issues section on this site and be in English.

• Bugs: if you find a bug or error in the plugin, create a bug issue detailing the steps needed to be performed in order to reproduce the issue. Provide the steps from scratch, i.e., starting just after a clean Q2A setup. Attaching screenshots might be useful too. Also include your PHP, MySQL, Q2A and plugin versions. Make sure you have no other plugin in the qa-plugin directory while reproducing it and that you are using the default Q2A theme.
• New features: feel free to request features using the issues section. Select the enhancement kind in the combobox and explain in detail the feature and why you consider it would be useful to others.
• Questions and other technical support: create a task issue explaining the situation in detail.

Administrative (all non-technical) issues should go through private message to my profile in the Q2A site. Make sure to provide your email address.

FAQ

• Do you give refunds in case I end up not liking the plugin?

  No. The reason for this is that not only this wiki is quite descriptive but also the plugin can be seen and interacted with live in the demo site. You can fully test the plugin before buying so there are no refunds.

• Do I have to replace my WYSIWYG plugin with this one?

  It is not needed to replace the files. Both plugins can be present in the qa-plugin directory. However, as this plugin is an editor plugin, it is needed to update the plugin that is going to handle questions, answers and comments in Q2A settings, as instructed in the installation steps.

• Are posts already created compatible with this editor?

  This editor is a CKEditor wrapper, the same as the WYSIWYG editor that comes with Q2A. So any post created with the WYSIWYG editor will be properly rendered by the PUPI DM Editor and viceversa.

• I created a post with the markdown editor and now I'm trying to edit it with the PUPI DM Editor, why am I unable to do so?

  That's how Q2A works. When you create a post it sets its format. The Markdown editor sets its format to markdown while the WYSIWYG and the PUPI DM Editor set its format to html. The Markdown editor will be the best choice to open the markdown format and the selected CKEditor wrapper will be used to open the html format. Newly created posts will always be created using the selected editor in the admin/posting settings.

• Would you mind doing some customizations to this plugin?

  Sure. Feel free to get in touch as explained in the Support section.

Get the plugin

Click here to navigate to the main plugin page. From there, you will be able to buy the plugin.