Languages :

English • Français

The BlueXML Datagrid Framework (or "BlueXML Datatable Framework") provides BxDS products with the ability to switch the tabular data display at will and in an easy way. We will illustrate its setup and use on this page.

Conventions

• The framework is accessible through a URL that depends on the installation.
• Interaction with the framework is done by specifying parameters in the URL. Each parameter is prefixed with an ampersand sign (&) and separated from its value with an equal sign (=). For instance, giving the value "mywidget" to parameter viewType is specified by "&viewTpe=mywidget".
• Parameter values are not enclosed, neither in quotes (") nor in commas (').
• The parameters section in a URL is introduced by a question mark (?) that substitutes itself to the first '&'. Thus, the parameters string appended to the framework URL is: "?viewTpe=dhtmlx&width=500px".
• Each new widget must provide a JavaScript file that contains elements necessary for handling the widget. The default name for the file is ViewDataGrid_xxx.js where "xxx" is the name chosen to refer to the widget.
• The widget may also have its own stylesheet file. If so, the default name for the stylesheet file is ViewDataGrid_xxx.css.
• ViewDataGrid_xxx defines a package name but also defines the namespace in the JavaScript file.

List of currently supported parameters

The BlueXML Datagrid Framework accepts the following case-sensitive and order-independent parameters, with zero or one instance of each:

• viewType: selects the widget that will handle the data display. Current values are (remove quotes): "dhtmlx", "dojo". If viewType is absent, the framework uses the default widget that has been configured.
• dir: specifies the path to a directory where the JavaScript and/or CSS files may be found. The value must be a valid URL with no trailing slash sign (/).
• package: specifies the base of the filenames (i.e. without any extension). This parameter is necessary if the files do not follow the default name pattern (see the Conventions section on this page).
• jsfile: specifies the complete name (base and extension, but no path) to the JavaScript file. When combined with dir, this parameter must define the complete access path to the file.
• cssfile: similar to jsfile, specifies the complete name to the CSS stylesheet file. This parameter too must define a complete path. However, the stylesheet file is optional.

How to register an additional widget

As stated earlier, an additional widget is provided in a JavaScript file whose name defaults to ViewDataGrid_xxx.js where xxx stands for the name of the widget. For instance, if "dojo" were chosen as the name for the Dojo 1.2.3 DataGrid, we would have:

• package name: ViewDataGrid_dojo
• JS filename: ViewDataGrid_dojo.js
• CSS filename: ViewDataGrid_dojo.css

Thus, selecting this widget would be done by adding "viewType=dojo" (quotes not included) to the parameters. However, note that using another version of Dojo DataGrid would require a different selection name.

When registering (or using) a widget with the BlueXML DataGrid Framework you need to follow these steps:

• choose a name for the package you want to use. The name is specified using parameter package. If the package name has the format ViewDataGrid_xxx, parameter package becomes optional provided that viewType is given. Parameter package is still needed even if parameter jsfile is given.
• choose a directory where you make the package available. The directory is a valid URL with no trailing slash sign ('/') that is transmitted to the framework using parameter dir. If the package is in the default folder, you don't need to specify the parameter.
• if the widget needs additional stylesheet(s), specify the CSS file with parameter cssfile. In case of styles defined in multiple files, use "@import" directives to include them in you cssfile. If the file is named ViewDataGrid_xxx.css, there's no need to specify cssfile. The same applies if no specific stylesheet is needed.
• if the JS file is not named ViewDataGrid_xxx.js, indicate the correct name with parameter jsfile.
• jsfile must include a function named "initializeFromKerBlueMD". The single argument to the function is a JSON object that describes the data fields (name, type and other properties) and datasource (server, query, etc.). The function must return an instance of the appropriate widget. Of course, the instance must be created and properly configured.
• in case auxiliary script files are needed, the FreeMarker Template file (its name and location is installation-specific) must be modified. Inclusion of the script files must be a section guarded by a name test (i.e. enclosed between the line <#if gridtype=="your_widget_name"> and the line </#if>). This allows the HTML page that is generated to skip the script files that are not needed for a specific widget.

Example

Suppose we intend to add the Yahoo UI datatable widget to an existing BlueXML DataGrid Framework. First, we need to choose a package name: "yui". Subsequently, the filenames are ViewDataGrid_yui.js and ViewDataGrid_yui.css. With our package stored on a service server at http://www.wss.com/BDF/yui, we have to set parameter dir to that URL.

The list of parameters is:

?viewType=yui&dir=http://www.wss.com/BDF/yui

However, most packages cannot be self contained. Hence, the need to modify the template file datatable.get.html.ftl. In the case of "yui", this means including at least the YUI base files. So we will add a section of <script> tags to the template file after the <body> tag. The section is guarded by a comparison with the widget name as follows:

<#if gridtype=="yui">
  <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/element/element-beta-min.js"></script>
  <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/datasource/datasource-min.js"></script>
  ...
</#if>