Adding 7.x Features to Existing Widgets

Customizations made to widgets in Telligent Evolution 6.x can be used as-is in Telligent Evolution 7.x. After upgrading to Telligent Evolution 7.x, these custom widgets can be modified to include new platform functionality exposed by Telligent Evolution 7.x. This guide identifies each of the new features that are exposed at the widget level and provides techniques for adding these features to existing, customized widgets.

Exposure of Core Services

Telligent Evolution 7.x introduces a number of core services to existing and custom applications to simplify the implementation of common functionality and behavior. Within widgets, core services can be easily exposed via the $core_v2_ui widget extension.

Likes

The Likes core service supports liking any content within the site. Once installed, Telligent Evolution 7.x supports liking comments, blog posts, blogs, forum replies, forum threads, forums, media files, media galleries, wiki pages, wikis, groups, and users (though the exposure to liking these content items is not included in all widgets). To add support for liking a supporting content item, use the following syntax in a Widget Studio widget:

$core_v2_ui.Like($contentId, $contentTypeId)

where $contentId is the GUID identifying the individual content item and $contentTypeId is the GUID identifying the type of the content. The content ID is exposed on all core entities, for example, a blog post returned from $core_v2_blogPost.Get(). The content type is exposed on the primary extension from which the content item is retrieved; for example the blog post content type ID is exposed as $core_v2_blogPost.ContentTypeId.

This simple call will render the standard like UI inline. To adjust the like UI, additional options are exposed on the $core_v2_ui.Like() method, or the Like API can be used directly by interaction with the $core_v2_like widget extension and the Like REST endpoints.

For reference, $core_v2_ui.Like() is used in the following factory default widgets for Telligent Evolution 7.0: Blog - Post, Blog - Post List, Blog - Comment List, Media Gallery - File, Media Gallery - File List, Media Gallery - Comment List, Wiki - Page, Wiki - Page List, Wiki - Comment List, Forum - Thread, Forum - Thread List, Liked Content, Activity Story Stream.

Ratings

The Ratings core service supports rating any content that implements the IRateableContentType interface. Telligent Evolution 7.x supports rating comments, blog posts, forum replies, forum threads, media files, and wiki pages. To add support for rating a supporting content item, use the following syntax in a Widget Studio widget:

$core_v2_ui.Rate($contentId, $contentTypeId)

This call will render the standard rating UI inline. To adjust the rating UI, additional options are exposed on the $core_v2_ui.Rate() method, or the Ratings API can be used directly be interacting with the $core_v2_rating widget extension and the Rating REST endpoints.

For reference, $core_v2_ui.Rate() is used in the following factory default widgets for Telligent Evolution 7.0: Blog - Post, Blog - Post List, Media Gallery - File, Media Gallery - File List, Wiki - Page, Forum - Thread, Forum - Thread Details.

Abuse

The Abuse core service supports flagging any content that implements the IAbuseCheckingContentType interface. Telligent Evolution 7.x supports abuse reporting on comments, blog posts, forum replies, forum threads, media files, and wiki pages. To Add support for rendering the abuse reporting UI, use the following syntax in a Widget Studio widget:

$core_v2_ui.Moderate($contentId, $contentTypeId)

This call will render the standard moderation UI (with support for flagging the content as abusive) inline. To adjust the moderation/abuse UI, additional options are exposed on the $core_v2_ui.Moderate() method, or the Abuse API can be used directly by interacting with the $core_v2_abuseAppeal, $core_v2_abuseReport, and $core_v2_abusiveContent widget extensions or the abuse appeal, abuse report, and abusive content REST endpoints.

For reference, $core_v2_ui.Moderate() is used in the following factory default widgets for Telligent Evolution 7.0: Blog - Post, Blog - Comment List, Media Gallery - File, Media Gallery - Comment List, Wiki - Page, Wikis - Comment List, Forum - Thread, Forum - Thread Details, Activity Story Stream.

Comments

The Comments core service supports commenting on any content that implements the ICommentableContentType interface. Telligent Evolution 7.x supports commenting on comments, blog posts, media files, and wiki pages. Where commenting APIs existed in Evolution 6.x, those same APIs are supported in 7.x, however, there is also a new API for interacting directly against the comments core services: $core_v2_comments widget extension and the comment REST endpoints.

There is no standard UI for comments. To add comments to a new content type, an implementation for an existing comment-supporting-content-type's UI can be reviewed.

#hashtags and @mentions

@mentions allow content implementing the IMentionContainingContentType interface to embed references to content implementing the IMentionableContentType interface. Telligent Evolution 7.x supports status messages, comments, blog posts, media files, forum threads, forum replies, and media gallery files to contain mentions. It supports mentioning users, groups, blogs, forums, media galleries, and wikis.

#hashtags allow content implementing the IHashTaggableContentType interface to embed tags within text associated to the content. Telligent Evolution 7.x supports hashtags in status messages, comments, blog posts, media files, forum threads, forum replies, and media gallery files.

Support for detecting #hashtags and @mentions and providing highlighting and suggestions is different for plain vs rich text inputs.

Plain Text #hashtags and @mentions

To support #hashtags and/or @mentions in simple plain-text fields such as status messages, comments, simple forum replies, and post subject lines, the evolutionComposer jQuery plugin should be used. Given a textarea with an id of, message...

<textarea id="message"></textarea>

... its value would have previously been accessible via

$('#message').val()

To enable this same textarea to support #hashtags and @mentions, it is necessary to call the new jQuery.evolutionComposer plugin. At some point in the setup of the widget's client script, the plugin should be called against the textarea to initiate it as an instance of an evolutionComposer. For performance reasons, this is typically recommended to be initiated once, only on the focus event of the texarea.

$('#message').one('focus', function(e){
    $(e.target).evolutionComposer({
        plugins: ['mentions','hashtags']
    });
});

Then, to retrieve the tokenized value from the composer, previous usage of $('#message).val() should be replaced with

$('#message').evolutionComposer('val')

For reference, the evolutionComposer jQuery plugin is used in the following factory default widgets for Telligent Evolution 7.0: Blog - Add Comment Form, Media Gallery - Add Comment Form, Wikis - Add Comment Form, Search Result List, Forums - Create/Edit Post, Forum - Thread, Media Gallery - Upload/Edit File Form, Quick Post, Wikis - Edit Page, Activity Story Stream.

Rich Text #hashtags and @mentions

To support #hashtags and @mentions in the rich text editor, widgets must identify the type of the content used within the editor. When inserting a rich text editor within a widget, the $core_v2_editor.Render() method should specify a ContentTypeId:

$core_v2_editor.Render('ID_OF_EDITOR', "%{ ContentTypeId=$contentTypeId }")

Where $contentTypeId is the content type of the content being created/edited. The content type is exposed on the primary extension from which the content item is retrieved; for example the blog post content type ID is exposed as $core_v2_blogPost.ContentTypeId. This allows the editor to identify which core services (#hashtags and/or @mentions) are supported by the content type and enable the associated plugins to recognize #hashtags and/or @mentions.

For reference, the content's type ID is provided to editors in the following factory default widgets for Telligent Evolution 7.0: Forum - Create/Edit Post, Wikis- Edit Page, Media Gallery - Upload/Edit File Form.

General Widget Improvements

Along with core services, other improvements were made to the Studio Widget API to enable easier widget development.

Ajax Paging

The $core_v2_ui.PagedContent() method was added to support standardized support for Ajax-based paging of lists. Most simple views of widget content were updated in Telligent Evolution 7.x to support paging via Ajax using this extension. Paging support in Telligent Evolution 6.x is still supported, but this new technique greatly simplifies the implementation of Ajax-based paging.

Improvements to Specific Widgets

In Telligent Evolution 7.x, plugin types were added to simplify the inclusion of third party content and information within the UI. In these cases, significant changes were made to the widgets that render content associated to these core services.

Search Results List

The Search Results List widget was updated to support the custom rendering options exposed by the new ISearchableContentType plugin and custom filtering options exposed by ISearchCategories plugins. The search results API is backwards compatible and the 6.x implementation of the Search Results List will continue to function in 7.x, however, the new implementation of the Search Results List widget enables individual content types to define how they should be rendered within search results.

It is recommended to review and revert this widget, if possible. Or review the updates to the search results API, specifically the view methods on the SearchResult entity and the $core_v2_searchCategory widget extension to consider including the new functionality in customized versions of rendered search results.

Activity Message List / Activity Story Stream

The Activity Message List widget was replaced with the Activity Story Stream widget in Telligent Evolution 7.x (this migration occurs automatically during an upgrade). The Activity Story Stream widget makes use of IActivityStoryType plugins and core services to generate the activity stream. This version of the stream allows the plugin to define how each story in the stream should be rendered and also automatically includes support for liking, commenting, and reporting abuse on supporting stories.

It is recommended that this new widget be reviewed to ensure that it matches the visual styling of custom themes.

Post and Comment Forms

The following widgets now all expose the abililty to embed #hashtags and @mentions. While it is possible to manually add this support by editing the widgets in Widget Studio to take advantage of the new jQuery.evolutionComposer plugin as described above, it's easier and safer to use the new default implementations of these widgets when possible. Additional updates to these widgets are identified below.

Quick Post
- The Quick Post's 'Status Message' entry now also supports attaching a user file associated with the status message.
Forum Thread
- Forum threads and replies now embed all of their editing UI within $core_v2_ui.Moderate.
Forum Create/Edit Post
Media Gallery - Add Comment Form
Media Gallery - Upload/Edit File Form
Wikis - Add Comment Form
Wikis - Edit Page
Blog - Add Comment Form

New Pages

A few new pages were added in Telligent Evolution 7.x to support new core services. These pages are added automatically during the site upgrade, but include only necessary functionality to implement the feature. Each of the new pages should be reviewed after upgrading to ensure that the page matches the visual style of custom themes.

User Mentions (in the Site Theme)
This page shows the list of mentions of a user within the user's profile.
User Likes (in the Site Theme)
This page shows a list of content that the user has liked (shown in the user's profile).
Content Abuse Appeal (in the Site Theme)
This page supports the abuse process by exposing a form enabling a content author to appeal their content being marked as abusive.
Content Appeal Queue (in the Site Theme)
This page supports the abuse process by exposing an actionable list of abuse appeals.
Common OAuth Authorize (in the Site Theme)
This page supports the new OAuth application support by providing a form for authorizing OAuth applications.
Group Mentions (in the Group Theme)
This page shows a list of mentions of a group.

Developer Space