Custom Widget Types

Custom widget types for SemwidgJS can be easily created and integrated. Creating a custom widget type consists of four steps:

Defining the (additional) properties the widget type shoud have,
Let the custom widget type inherit all functions from the widget base class,
Override its _buildHtml() function,
Register the new widget type with SemwidgJS.

All of the built-in widget types of SemwidgJS are created that way, too.

Example

Shown below is the source code of an extended version of the built-in SwImage widget type that adds a caption text to the image:

SemwidgJS.SwImageWithCaption = function() {

   this._addProperties([
      ['alt', 'query', 'Specifies an alternate text for this image.'],
      ['caption', 'query', 'Caption text for this image.']
   ]);

};

This part defines the additional properties that shoud be useable with the custom widget type. Each widget type has several properties by default that are described in the documentation. A property definition consists of three values: the name, the property type, and a short description that will be, for instance, used by SemwidgED to show a user the purpose of a property.
SemwidgJS.SwImageWithCaption.prototype = new SemwidgJS.SwWidget();

This line lets the custom widget type inherit all functions from the widget base class.
SemwidgJS.SwImageWithCaption.prototype._buildHtml = function() {

   var html = '';

   html += '<figure>'

   html += '<img ';
   html += this._getDefaultHtmlAttributes();
   if (!SemwidgJS.Util.String.isEmpty(this.getValue())) {
      html += 'src="' + this.getValueDefaultValue() + '" ';
   }
   if (!SemwidgJS.Util.String.isEmpty(this.getAlt())) {
      html += 'alt="' + this.getAltDefaultValue() + '" ';
   }
   html += '>';

   html += '<figcaption>' + this.getCaptionDefaultValue() + '<figcaption>';

   html += '</figure>'

   this._setHtml(html);
};

This part the HTML output of the widget is defined. This function is automatically executed every time the widget receives new data from a SPARQL endpoint or if its property values are altered. The basic widget class provides several auxillary functions like _getDefaultHtmlAttributes() that combines the values for the properties styleclass, style, title. In addition, the SemwidgJS frameworks creates several functions for each property of type query to get its result data. The whole data can be retrieved via 'get'+Name+'AllValues()' (e.g: getValueAllValues(), getAltAllValues(), getCaptionAllValues() etc.) and then be searched for the desired values. Alternatively the function 'get'+Name+'DefaultValue()' can be used to retrieve the last element's value of the first result set. When the result is seen as a table, this would be the value of the most upper right table cell. In most cases this is the desired value. Values of properties that are not of type query or the query string itself can be retrieved by the function 'get'+Name+'()'.
SemwidgJS.WidgetProvider.registerWidgetType('SemwidgJS.SwImageWithCaption');

This line registers the new widget type with the widget provider of SemwidgJS using the name of the widget class as parameter. When creating a widget instances of this type in HTML, only the part after the last dot of the class name is required (e.g: <div data-sw-widget="SwImageWithCaption" …).

Usage

To use the new custom widget type within a website, its source code must be embedded. Since SemwidgJS's registerWidgetType() function is called, it is important to embed it after SemwidgJS. After that, instances of this widget type can be created as usual.