Widget Extensions

Widget extensions are plugins that support exposing APIs to widgets.  Documentation for the extensions that are included with Telligent Community can be found at Widget Extensions Documentation.

Why should I create a Widget Extension?

Do you have any custom methods or properties you want to be able to call directly from a widget?  A custom widget extension can expose these methods and properties so they can be called directly in velocity scripts.

Creating a Widget Extension

First we need a class with one or more public methods or properties that we want to expose in our widget extension.  Velocity (the script engine used by scripted widgets) works best with simple data types and IDictionarys.

The following class has a single public method named Hello.  The method takes a single string parameter name and return "Hello {name}".

    public class Sample 
    {
        public string SayHello(string name) 
        {
            return "Hello " + name;
        }
    }

In order to expose this class we will use a second class that implements the IScriptedContentFragmentExtension Plugin type. First we return an instance of our Sample class to the Extension method.

public object Extension
{
    get { return new Sample(); }
}

We also need to provide a unique name for the sample extension.  For the example we will use the name "telligent_v1_samples".  We recommend using {vendor}_v{version_number}_{service_name} when naming your widget extensions to ensure the extensions are named uniquely, easily versioned and remain consistent with existing extensions.

public string ExtensionName
{
    get { return "telligent_v1_samples"; }
}

Once an IScriptedContentFragmentExtension is implemented and deployed to the bin/ folder of a Telligent Community site, it must be enabled within the Administration area before it is available to scripted widgets.

Sample

The completed source code for the sample extension:

using Telligent.Evolution.Extensibility.UI.Version1;

namespace Samples
{
    public class Sample 
    {
        public string SayHello(string name) 
        {
            return "Hello " + name;
        }
    }

    public class SampleWidgetExtension : IScriptedContentFragmentExtension
    {
        #region IScriptedContentFragmentExtension Members

        public string ExtensionName
        {
            get { return "sample_v1"; }
        }

        public object Extension
        {
            get { return new Sample(); }
        }

        #endregion

        #region IPlugin Members
        
        public string Name
        {
            get { return "Sample Extension"; }
        }

        public string Description
        {
            get { return "Enables widgets to use the public members of the Sample class."; }
        }

        public void Initialize()
        {
        }

        #endregion
    }
}

Using the Extension

Now that our extension is enabled, we can create a widget that calls our extension:

$telligent_v1_samples.SayHello('World')

Add this widget to a page and you should see widget output "Hello World".  If the call to the widget extension had thrown an exception, the widget would not be rendered for the end user.  While editing the page you would see the exception rendered instead of the expected widget contents.  Error messages may also be returned the response, to provide translatable or easier to understand error messages.  Returning a value that uses or inherits one of following types (ApiList, PagedList, ApiEntity or AdditionalInfo) facilitates the return of errors by providing an Errors collection property on the return object.