Appboard/2.6/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 [INSTALL_HOME]\server\webapps\enportal\framework\htmlwidgets\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:

[javascript,N] <script type="text/javascript" src="/enportal/visualizer/assets/js/widget.js"></script> <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}

[javascript,N] function mySaveWidgetConfig(config) {

   CustomWidget.saveConfiguration(config);

}

• CustomWidget.dataClicked(dataID, columnName) - Passes the value of the 'id' column of the data that was clicked within the HTML5 widget, and optionally the columnName. 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.

[javascript,N] function myRowClicked(rowID, columnName) {

   CustomWidget.dataClicked(rowID, columnName);

}

• 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. For instance, the following (using JQuery) would be a way to notify Appboard that your HTML Widget has initialized.

[javascript,N] $(document).ready(widgetInit); function widgetInit() {

   // setup callbacks
   CustomWidget.setConfigurationCallback(configurationUpdated);
   CustomWidget.setDataCollectionCallback(dataCollectionUpdated);

   // ready
   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.

[javascript,N] 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:[{},{}] }. The example callback function below builds a table from the data collection passed in.

[javascript,N] function dataCollectionUpdated( data ) {

   var tbl_row = "";
   var columns = [];
   var tbl_head = "";
   if ( CustomWidget.isEditMode )
   {

var editModeToolbar = "

<button onclick='toggleConfigEditor();'>Edit Configuration</button>

";

       $('#editModeDiv').html( editModeToolbar );
   }

   $.each(data.columns, function() {

tbl_row += ""+this.displayName+"";

       columns.push( this.name );
   })
       

tbl_head = ""+tbl_row+""; $("#coolTable thead").html(tbl_head); var tbl_body = ""; $.each(data.data, function() { tbl_row = ""; for (var i=0;i<columns.length;i++) { tbl_row += ""+ this[columns[i]] +"";

       }

tbl_body += ""+tbl_row+""; }) $("#coolTable tbody").html(tbl_body); }

• CustomWidget.getThemeName() - Returns a string with the currently selected AppBoard theme. This could be used to make style decisions based on the theme.

• CustomWidget.getUUID() - Returns the AppBoard UUID for this widget instance. This unique identifier is the same regardless of the client and should not change.

• CustomWidget.getID() - Returns the ID for this widget instance. This value may change client-to-client and even between reloads. It is useful to identify the iframe the widget is loaded in which will have the iframe ID of iframe_appboard_[getID]0, for example iframe_appboard_A70.

• CustomWidget.setSessionVar(varName, varValue) – Your HTML5 form widget must call this function to save updates to the client's custom context variables. Note: They will not be saved to the server until CustomWidget.saveSessionVars() is called.

• CustomWidget.saveSessionVars() – Your HTML5 form widget must call this function in the doApply() function if you have called setSessionVar(varName, varValue) one or more times and need the modifications saved in the client's custom context variables to be saved to the server and to have the actions configured on the widget to be triggered. When actions are triggered as this is done without the normal context of a specific row of data the special id of -1111 is used. This allows regular action filtering to determine which actions to fire.

Widget.js

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

Examples

Form Input to change Session Variables

While the HTML Widget API can be used to develop new visualizations, it can also be used to capture user input in order to provide new user interaction over the built-in widgets. This example builds expressions to filter the data displayed in other widgets and does this by setting session variables used in the queries driving the other widgets.

1. Access the AppBoard Builder.
2. Create Session Variables: Navigate to the 'System Administration' -> 'Session Variables' utility. Select 'Manage Variables' button and create two session variables: startDate and dateRangeFilter; make sure both have the option 'Server use Only' unchecked.
   • startDate default value: ${shim:now.offset(-5,'day').format('yyyy-MM-dd')}
   • dateRangeFilter default value: event_time >= '${shim:now.offset(-5,'day').format('yyyy-MM-dd')}'.
3. Create Data Source: Navigate to 'Data Sources' mode of AppBoard Builder. Create a new SQL Datasource that will query an events table; this example is referencing an events table that has the columns: 'event_id', 'event_name', 'event_time'. We are going to register two queries. So we select the 'Add' button; enter a name for this 'tutorial.sessionvar'; select an adapter type 'Database', and type 'Database Query' and then select Add Data Source. After entering valid connection info we select next. Add two Entities: 'EventsAfterDate' and 'EventsByDateRange': using these SQL queries:
   • for 'EventsAfterDate': select event_id,event_name,event_time from events where event_time >= '${shim:session.var.get('startDate')}' order by event_time desc
   • for 'EventsByDateRange': select event_id,event_name,event_time from events where '${shim:session.var.get('dateRangeFilter')}' order by event_time desc
4. Save the new data source.
5. Create a new Board with 3 widgets: 1) Your custom HTML Widget, 2) DataGrid (configured to display EventsAfterDate), and 3) DataGrid (configured to display EventsByDateRange)
6. Create actions on your custom HTML Widget so that on selection it will trigger Data Collection Refresh actions on the EventsAfterDate and EventsByDateRange data collections.
7. Make sure you custom widget HTML form has the following doApply code to apply the entered start date:

[javascript,N]

   function doApply() {
       // Update the session variables: startDate dateRangeFilter
       CustomWidget.setSessionVar("startDate", $('#start').val());
       CustomWidget.setSessionVar("dateRangeFilter", "event_time >= '"+$('#start').val()+"'");
       CustomWidget.saveSessionVars();
   }