Javascript and Ajax

General guidelines

The following is a list of guidelines for working with Javascript within scripted widgets.

If more than a few lines, places the Javascript in an external script file and link to it using $core_widget.GetFileUrl('FILENAME').
Always register script blocks using the #registerEndOfPageHtml directive (see below).
Avoid using context variables. Prior to 6.0, context variables were used to store the configuration data associated to an instance of a widget's context. This is variable was declared in the global scope and was not directly referenced after its initial access. Instead, pass the configuration data to the external script directly. For an example, see the UserActivityMessageList widget.
Place JavaScript within a vendor-specific namespace extending jQuery. For example, core widgets JavaScript is placed within the jQuery.telligent.evolution.widgets namespace within a class named according to the instance identifier of the widget. For example, the My Stuff (internally called User Activity Message List) widget's JavaScript is located in $.telligent.evolution.widgets.userActivityMessageList.
Only expose necessary methods publicly.

Registering script blocks

To facilitate registering <script></script> blocks at the bottom of the page to increase rendering speed and improve SEO, the #registerEndOfPageHtml directive was added. Its syntax is:

#registerEndOfPageHtml(uniqueRegistrationKey)
  Markup To render at the end of the page. 
#end

The markup block within the directive will be rendered at the end of the rendered HTML page.

A few notes about this directive:

In preview mode, markup will be rendered inline instead of at the bottom of the page. This ensures that the JavaScript will be properly rendered to the client when editing pages.
The uniqueRegistrationKey is optional. For scripts that should always be registered (for example, scripts that configure the current instance of a widget), the directive can be called without the parameter. If the parameter is specified, the block will only be rendered once for the given key, even if multiple widgets attempt to register HTML using the same key.

For example, this is a script component of an assumed widget called myWidget stored within a widget attachment as ui.js.

(function($){

// namespace client code to avoid collisions
$.myNameSpace.myWidget = {
  register: function(options) {
    // initialize client script using passed options
  };
}

})(jQuery);

The script attachment can then be referenced and called with the following:

#registerEndOfPageHtml('myNameSpace.myWidget')
  <script type="text/javascript" src="$core_v2_encoding.HtmlAttributeEncode($core_v2_widget.GetFileUrl('ui.js'))"></script>
#end

#registerEndOfPageHtml()    
  <script type="text/javascript">
    jQuery(document).ready(function(){   
      jQuery.myNameSpace.myWidget.register({
        key1: 'value1',
        key2: 'value2'
      });
    }); 
  </script>
#end

Note that when registering HTML via the #registerEndOfPageHtml() directive, the registration occurs when executed. If the widget is later not rendered (either by not rendering any content or by calling $core_widget.Hide()), the HTML reigstered to be rendered at the end of the page will still render. It is important to call $core_widget.Hide() before any end-of-page HTML registration is performed.

Ajax

Evolution includes custom extensions to jQuery's Ajax API to facilitate interactions with REST and callbacks to Evolution. These functions work the same as jQuery.ajax() but set meaningful defaults and support URL templating:

jQuery.telligent.evolution.get(options)
jQuery.telligent.evolution.post(options)
jQuery.telligent.evolution.put(options)
jQuery.telligent.evolution.del(options)

When using these functions, the values passed through the data parameter that are identified within the provided url are replaced. Any data values not found in the url are passed either as query string data (for the get method) or POST data (for post, put, and del methods). For example, the {GroupId} and {UserId} parameters in the url will be replaced with the values defined in the data parameter:

jQuery.telligent.evolution.del({
 url: jQuery.telligent.evolution.site.getBaseUrl() + 'api.ashx/v2/groups/{GroupId}/members/users/{UserId}.json', 
 data: { GroupId:5, UserId:2107 }, 
 success: function(response) { console.log(response); } 
});

Developer Space