Telerik blogs
DotNetT2 Light_1200x303

Get familiar with the new functionality in RadRichTextBox for WPF—Mentions.

Today I would like to present you the latest addition to our RadRichTextBox control. The functionality is called Mentions and it enables you to open a list of suggestions when the user types a specific character inside the document. And yes, the default behavior is to show a list of persons and insert the name of the chosen one along with a hyperlink with their email address.

But wait, that’s not all! 🤗 The functionality is pretty much customizable, so you can use it to insert a mention to a person, or some predefined content with images, tables, etc.

In this post, I will show you both the built-in functionality and an example for a custom setup.

Introduction to the API

Before showing you how the mentions look, let’s take a step back so I can get you familiar with the most important members of the API and the terminology.

All the settings for the mentions reside in the MentionContext property of the RadRichTextBox class. At this point, there are two properties inside the context:

  • Providers: The mention providers are the classes responsible for keeping a collection of items, filtering them and inserting them into the document. Each mention provider must be associated with a unique mention character. The mention character is the symbol that, when inserted into the document, triggers the visibility of the list with the suggestions. You can add as many providers as you need.
  • Templates: RadRichTextBox needs to know how to visualize the objects inside the suggestions list. To instruct it, you can create a DataTemplate and define the properties you would like the users to see when the list with the suggestions opens. Each mention template should be associated with the type of item that it represents.

Default Behavior—Mention Persons

For your convenience, RadRichTextBox comes with the built-in PersonMentionProvider. It covers the most common use case—tagging people with their name and email. The default mention character for this provider is “@” and, when it’s pressed, the list of the registered people shows. The user can select a person from the list or continue to type further to filter the suggestions. Each person in the list is visualized with their image and name. When a specific person is selected, the provider inserts the name of the person and a hyperlink with their email, preceded by the “@”.

Anything in the functionality and presentation of the PersonMentionProvider is customizable—you can control the insertion of content after the selection, the filtering of the records, the visualization. Changing the mention character that triggers the provider is also possible.

All you need to set up the default provider is to assign data to it and add it to the Providers collection:

List<PersonMentionItem> personMentionItems = new List<PersonMentionItem>() {
new PersonMentionItem() { Name = "Maria Anders", Mail = "manders@somecompany.com", ImageSource = new BitmapImage(new Uri("../../../../Images/manders.png", UriKind.Relative)) },
new PersonMentionItem() { Name = "Antonio Taquería", Mail = "ataqueria@somecompany.com", ImageSource = new BitmapImage(new Uri("../../../../Images/ataqueria.png", UriKind.Relative)) },
new PersonMentionItem() { Name = "Thomas Hardy", Mail = "thardy@somecompany.com", ImageSource = new BitmapImage(new Uri("../../../../Images/thardy.png", UriKind.Relative)) },
new PersonMentionItem() { Name = "Anabela Domingues", Mail = "adomingues@somecompany.com", ImageSource = new BitmapImage(new Uri("../../../../Images/adomingues.png", UriKind.Relative)) }
};
PersonMentionProvider personMentionProvider = new PersonMentionProvider();
personMentionProvider.ItemsSource = personMentionItems;
this.radRichTextBox.MentionContext.Providers.Add(personMentionProvider);

And it’s ready to shine:

Person Mention Provider - user types 'Can @Ma' and the dropdown pops up; user selects Maria Anders, which gets added with a hyperlink to the email. The final result reads 'Can @Maria Anders help with that?'

Custom Behavior—Suggestions To Autocomplete

As I mentioned at the beginning of this post, the functionality is pretty customizable and can be used also for suggestions to autocomplete long titles, descriptions and any contents your users might need. This flexibility is achieved through the mention providers—you can use as many as you need. The only requirement for them is to assign a unique mention character for each provider.

To enable the custom behavior, you should implement a custom mention provider by inheriting the MentionProviderBase<T> class, where T is the type of items you need to list. The class requires you to implement two methods—one for defining how the items should be filtered inside the list when users type after the mention character, and one containing the logic for what and how it should be inserted when an item is selected.

The second step is to define a DataTemplate that instructs RadRichTextBox how it should visualize the items from your objects inside the list with the suggestions. Note that every template should be linked to a unique item type. It is not possible to add more than one DataTemplate for the same item type.

When you are ready with the implementations, add them to the respective properties of the MentionContext and surprise your customers with the new functionality!

The following GIF shows two mention providers in action:

Multiple mention providers - the @ and the # bring up different lists. The end result is: 'One of our colleagues, @Antonio Taqueria, is also a member of #United Nations Children's Fund.'

👉 If you are eager to try this out yourself, go ahead to our documentation for detailed instructions on setting up both—default and custom behaviors.

Try It and Share Your Feedback

In case you still haven’t tried Telerik UI for WPF, use the button below to obtain a trial version and explore all the components and their countless features.

Download a Free Trial

If you are already familiar with the package, don’t forget that we are eager to hear your feedback and will be very happy if you share it. Feel free to drop us a comment below with your thoughts. Or visit our Telerik UI for WPF Feedback Portal and let us know if you have any suggestions or if you need any particular features.


Tanya-Dimitrova
About the Author

Tanya Dimitrova

Tanya Dimitrova is a Tech Support Engineer in the Telerik XAML Team. In her work her main responsibility is to assist clients to implement different scenarios using the document processing libraries and editors. She is passionate in finding new adventures and in her free time enjoys travelling, reading, swimming, dancing or just spending time with friends.

Related Posts

Comments

Comments are disabled in preview mode.