Appboard/2.4/builder/widgets/html widget/api

API Reference

The AppBoard HTML Widget API is a JavaScript wrapper that exposes features of the AppBoard SDK configuration, data and actions APIs to an external web component / application (JavaScript, HTML).

The API extends the capabilities of AppBoard to HTML5 applications and allows them to operate as any other AppBoard widget. Actions, data collections / data sources and configuration information may be shared across the API to provide full interaction between AppBoard and the developed HTML5 application. Thus, the API represents the extensibility of AppBoard with HTML5 capabilities that the web developer can create and deploy using the AppBoard Builder without the need for AppBoard code development.

The API requires that the application is deployed within the AppBoard security sandbox to allow for the overlay of user credentials and authentication through AppBoard and to ensure that the application does not expose the AppBoard runtime to common Internet security vulnerabilities.

Authentication

Authentication is handled within the AppBoard runtime and allows the HTML5 developer to take advantage of features such as configuration persistence, data access and actions that are applied to the user, role or domain. Therefore, any saved configuration data, actions or data collections are persisted within the AppBoard framework and exposed to the HTML5 application within the user’s context Users, Roles, Domains and Content Provisioning

Deployment Location and References

The deployment of an HTML5 widget within the AppBoard sandbox comprises of several requirements that must be fulfilled by the HTML5 widget developer / administrator.

• The widget must be deployed to the ..\server\webapps\enportal\framework\htmlwidgets\<system / custom>\<widget name>\ folder;

• The widget must use an index.html or index.htm file as the launching point. Note: If the <widget name> folder does not include an index.html or index.htm file, the builder will not register the widget within the menu selection when adding your widget to the Stacks & Boards;

• All widget artifacts such as images, JavaScript, PHP, HTML, CSS or other files must be referenced relative to the location within the AppBoard server. For example: src=/enportal/framework/htmlwidgets/system/myWidgetName/someJavaScriptFile.js

• Each widget must include the following JavaScript wrapper API files to access the AppBoard SDK:

<!-- include the Appboard SDK's Widget JavaScript -->
<script type="text/javascript" src="/enportal/visualizer/assets/js/widget.js"></script>
<!-- include the Appboard SDK's CustomWidget JavaScript -->
<script type="text/javascript" src="/enportal/visualizer/assets/js/CustomWidget.js"></script> 

• AppBoard will automatically pick up the widget reference, when using the AppBoard builder, after the widget is deployed within the AppBoard sandbox, and;

• The sandbox contains two sub-folders which act as deployment locations, system and custom.
  • custom – this is the recommended location for all custom \ customer developed HTML5 widgets. A widget that features the same name ..\<widget name>\ as a widget deployed to the ..\htmlwidgets\system folder will take precedence over the system folder widget.
  • system – this location is used by Edge to deploy example HTML5 widgets or HTML5 widgets that support AppBoard capabilities as deemed by Edge.

JavaScript Wrappers

The HTML Widget API consists of two JavaScript files that expose and allow for interaction with the AppBoard SDK.

CustomWidget.js

This JavaScript library is the harness between AppBoard and any HTML / JavaScript-based application (widget) that is added to AppBoard. The file contains callbacks and functions that are used for getting and setting configuration, determining a click action on an HTML element, and showing data updates when data changes in AppBoard. The following functions can be called / implemented within an HTML5 widget:

• CustomWidget.saveConfiguration(config) - Saves the HTML5 widget configuration data in the form of a simple JavaScript object: {'someParameterName':aVariable, 'anotherParameterName':anotherVariable}

function mySaveWidgetConfig(config)
{
    CustomWidget.saveConfiguration(config);
}

• CustomWidget.dataClicked(dataID) - Passes the value of the 'id' column of the data that was clicked within the HTML5 widget. Use this function to notify AppBoard that the user clicked / selected a row in the data collection. This will cause any configured click actions to fire in AppBoard.

function myRowClicked(rowID)
{
    CustomWidget.dataClicked(rowID);
} 

• CustomWidget.isEditMode – This flag is set by AppBoard when configuring the HTML5 widget from the builder. The ‘Options’ wizard has a setting which is used to set this flag. The HTML5 widget can interrogate this flag to allow for the setting of configuration or other write-based options within the HTML / JavaScript code.

• CustomWidget.widgetInitialized() – This function must be called when your HTML / JS / CSS has finished loading so that the Flex side of the HTML widget knows you are ready to receive data and configuration.

$(document).ready(widgetInit);
function widgetInit()
{
    CustomWidget.widgetInitialized();
} 

• CustomWidget.setConfigurationCallback(configurationUpdated) – Your HTML5 widget must register a function callback to handle your widget configuration. This configuration object will be a simple JavaScript object of key value pairs. The callback can be an empty function if no configuration is required.

function configurationUpdated(config)
{
    // handle your config data here
    if(config != null)
	widgetConfig = config;	
} 

• CustomWidget.setDataCollectionCallback(dataCollectionUpdated) – Your HTML5 widget must register a function callback to handle the data collection from Flex side of AppBoard. AppBoard will pass the widget a simple JavaScript object that looks like: { data:[{},{}], columns:[{},{}] } A data processing example:

function dataCollectionUpdated( data )
{
    var tbl_row = "";
    var columns = [];
    var tbl_head = "";
    if ( CustomWidget.isEditMode )
        {
            var editModeToolbar = "<div style='text-align:right;' id='toolbar'>
<button onclick='toggleConfigEditor();'>Edit Configuration</button></div>";
            $('#editModeDiv').html( editModeToolbar );
        }
	
    $.each(data.columns, function() {
        	tbl_row += "<th>"+this.displayName+"</th>";
        	columns.push( this.name );
    })
        
    tbl_head = "<tr>"+tbl_row+"</tr>";
    $("#coolTable thead").html(tbl_head);
		
    var tbl_body = "";
    $.each(data.data, function() {
        tbl_row = "";
        for (var i=0;i<columns.length;i++)
    {
    tbl_row += "<td>"+ this[columns[i]] +"</td>";
    }
    tbl_body += "<tr onclick='rowClicked(\"" + this['id'] + "\");'>"+tbl_row+"</tr>";                 
    })
    $("#coolTable tbody").html(tbl_body);
} 

Widget.js

This JavaScript library is the reference to the AppBoard object. The HTML5 widget will not call the functions within this library.