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:

https://community.telligent.com/cfs-file/__key/communityserver-wikis-components-files/00-00-00-07-14/3247_2E00_SampleWidgetExtension_2E00_cs

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.