Appboard/2.6/builder/widgets/html widget/api

Revision as of 13:19, 4 August 2015 by imported>Jason.nicholls (→‎CustomWidget.js)


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.

Basic Control Flow

Widgets built with the HTML Widget API are effectively working with the Flex client and there is two-way communications. This means flex initiated calls out to javascript, and javascript initiated calls back to flex. When building a HTML Widget the following outlines the basic control flow:

  • initialization
    1. (flex) loads the HTML Widget in an iframe
    2. (flex) perform some initialization once iframe is loaded
    3. (html) register configuration and data collection callbacks
    4. (html) call CustomWidget.widgetInitialized
    5. (flex) call configuration callback with widget configuration
    6. (flex) call data collection callback
  • normal operations
    • (flex) call data collection callback based on:
      • if there is a polling interval, then every poll
      • if some client interaction has modified the data collection such as text-search, quick filters, and client or server-side filters.
    • (html) resize events: can happen due to resizing widgets, or the browser, or in some cases just because the flex client is hiding and showing the HTML iframe. This is really a function of the browser but it may be necessary to setup a callback for resize events to deal with these correctly (e.g. re-render the widget with the new dimensions).
    • (html) API calls depending on user interaction such as triggering actions, setting session variables, or in admin mode saving configuration.

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.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:[{},{}] }. Please note that AppBoard Date objects are converted into strings in the format YYYY-MM-DD HH:MM:SS - this is due to the JSON encoding not supporting a date format. If Javascript Date objects are desired then it is necessary to post-process the output and convert the strings. 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.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.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.isMaximized() - Returns true if the widget is currently maximized, otherwise false.
  • CustomWidget.setMaximized() - Set to true to maximize the widget, or false to restore the widget to the non-maximized state.
  • 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.
  • CustomWidget.getAvailableDataCollections() - When configuring a HTML Widget it is possible to expose additional Data Collections beyond the primary Data Collection. Calling this function returns a list of provisioned Data Collections. This is in the format of an array with name and uid pairs. The name is for display purposes only and if using the associated getDataCollectionByID API call then it expects the UID as a parameter.
  • CustomWidget.getDataCollectionByID(uid, callback) - This will request the Data Collection identified by uid to be fetched from the server and when complete the callback function is called with the resulting Data Collection in the same format as the primary Data Collection. Note this is a one-time action and not subject to subsequent callbacks based on poll period as is the case with the primary Data Collection. If the HTML Widget requires updates then it will need to handle this itself via timer or other triggering event.

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();
   }
Retrieved from "http://ab.edge-technologies.com/docs/index.php?title=Appboard/2.6/builder/widgets/html_widget/api&oldid=8304"