Using Custom Ajax Endpoints

Studio Widgets support using Ajax to access the Platform API via REST, and some helpful extensions are provided.  Whenever possible, the REST API should be preferred when Ajax functionality is needed from within Studio Widgets. However, there are occasions where custom Ajax endpoints are desirable:

• Complex and expensive custom formatting could be easier achieved on a server-side Ajax handler rather than piecing together the results of multiple REST API calls and templating via the client-side
• The REST API does not expose some portion of the Platform API which a script extension does support

Studio Widgets support custom Ajax endpoints implemented as Widget Script which can be referenced from the widget using a special URL format which executes the linked file when requested.

API:

$core_v2_widget.GetExecutedFileUrl('script.vm')

GetExecutedFileUrl returns a URL which, when requested against, will execute the velocity script named via its parameter.  The result of the execution will be returned as the response of the HTTP request.  The script will have the same context available to it as the calling widget.

Examples:

Calling a custom Ajax endpoint via GET and returning an HTML fragment

The following example returns a given user's latest status update formatted as an HTML fragment.

lateststatus.vm

#set ($userId = $core_v2_page.GetQueryStringValue('w_userId'))
#set($messages = $core_v2_statusMessage.List("%{ UserId = $userId, PageSize = 1 }"))
#foreach($message in $messages)
    <span class="status-message">$message.Body</span>
    <span class="status-date">$core_v2_language.FormatAgoDate($message.CreatedDate)</span>
#end

Client script which can call the custom endpoint. Note the use of GetExecutedFileUrl as well as the parameter prefix of "w_" to avoid collision with other query string parameters passed to the endpoint.

jQuery.telligent.evolution.get({
    url: '$core_v2_encoding.JavascriptEncode($core_v2_widget.GetExecutedFileUrl('lateststatus.vm'))',
    data: {
        w_userId: 1234
    },
    success: function(response){
        // add the response to the page
        jQuery('#element').html(response);
    }
});

Calling a custom Ajax endpoint via POST and returning JSON

This example allows for favoriting a group for a user via Ajax.  Favoriting is supported by the Platform API via Widget script extensions, but not via REST.   This custom Ajax endpoint accepts a group ID and favorite state via POST, processes the request against the Platform API, and returns a JSON response.

favorite.vm

#if ($core_v2_page.IsPost)
    #set($favorite = $core_v2_utility.ParseBool($core_v2_page.GetFormValue('favorite')))
    $core_v2_page.SetContentType('application/json')

    $core_v2_group.SetFavorite($core_v2_utility.ParseInt($core_v2_page.GetFormValue('groupId')), $favorite)
    {"favorite":#if($favorite) true#else false#end}
#end

Client script which can call the custom endpoint. Note the use of GetExecutedFileUrl

jQuery.telligent.evolution.post({
    url: '$core_v2_encoding.JavascriptEncode($core_v2_widget.GetExecutedFileUrl('favorite.vm'))',
    data: {
        favorite: true,
        groupId: 1234
    },
    dataType: 'json',
    success: function(r){
        console.log(r);
    }
});