Tips & Tricks - Custom Table - JavaScript

The JavaScript API for free-form tables provides functions for reading values from free-form tables or controlling the appearance of free-form tables based on those values. With Velocity, it's very easy to make changes to custom tables at the time the page is rendered. Since these modifications take place on the server side, they should always be preferred over modifications made via JavaScript for security reasons. However, in some scenarios, using JavaScript (on the client side) is more appropriate—for example, when the goal is to achieve a clearer display and there are no security concerns. You can find the JavaScript API documentation here.

You can download the sample application here and import it as usual. Enable the advanced options so that all the dialog boxes mentioned in this example are accessible. Knowledge of JavaScript and application development is a plus for this position.

When you open the application in the "Applications" module, you'll find the "Numeric Value" input field on the input page. The table cell should be highlighted based on its numerical value.

There is also a view page with the "Title" and "Numeric Value" fields. The group containing the two fields has been assigned the "ButtonContainer" style class on the "View" tab. With other style classes, the color may not be displayed correctly.

The "All Entries" page contains the customizable table into which the view page is embedded. The following JavaScript is entered for this table:

            function colorTable(tableGUID, fieldGUID)
{
	var table = getElement(tableGUID); /*Free layout table  shapedtable*/
	var recs = table.oUp.getRecords();

	var control; //Initialize variables
	var myvalue;
	var hvalue;
	var mycolor;


	for (var i=0;i<recs.length;i++)
		{
			control = recs[i].getControl(fieldGUID);
			myvalue = getFloatByLocalString(control.getValue());

			hvalue = Math.round(myvalue / 100 * 120);
			mycolor = 'hsl('+hvalue+',100%,50%)';

			control.getHtml().css('backgroundColor', mycolor);
		}
	return true;
}

        

            function colorTable(tableGUID, fieldGUID)
        

This line creates a function named "colorTable" that takes as parameters the table's GUID and the GUID of the numeric view field—in this case, from the function call that we will define later.

            var table = getElement(tableGUID); /*Free layout table  shapedtable*/
        

Here, the table is assigned to a variable.

            var recs = table.oUp.getRecords();
        

The getRecords() function can be used to access the individual records in the table. All table rows are stored in the recs array.

            var control; //Initialize variables
var myvalue;
var hvalue;
var mycolor;

        

Variables that are to be used in the loop are initialized here.

            for (var i=0;i<recs.length;i++)
        

The array values are read in a loop. The variable `i` is used to iterate through the rows until the length of the array is reached.

            control = recs[i].getControl(fieldGUID);
        

The value of an application element can be retrieved by passing the variable `fieldGUID`—which is defined in this example as a parameter for the function—to the `getControl()` method and calling that method on the current record.

            myvalue = getFloatByLocalString(control.getValue());
        

Since the value of the control may be displayed with a decimal point or a decimal comma, depending on the portal settings, you should use the getFloatByLocalString() method of the HelperMain class to retrieve the value, to ensure that a numeric value that JavaScript can understand is returned.

            hvalue = Math.round(myvalue / 100 * 120);
mycolor = 'hsl('+hvalue+',100%,50%)';

        

To fill a cell with color based on a numerical value, the HSL color space is used, since changing a single value—the hue angle—allows you to create a simple gradient from red through yellow to green. In the HSL color space, the H value can range from 0 to 360. For the color green, the values may not exceed 120. To do this, the numeric value is divided by the maximum value of the numeric input field—100 in this example—and the result is multiplied by 120. Since the HSL system only accepts whole numbers, the calculated value is rounded. After that, the complete color value can be stored in the mycolor variable. The saturation is set to 100%, and the lightness to 50%. Finally, all that remains is to assign the color value to the control in the CSS.

Highlight a table cell

The following script line highlights the cell containing the numeric value:

            control.getHtml().css('backgroundColor', mycolor);
        

Highlight a table row

If you want to highlight the entire line, please replace the script line

            control.getHtml().css('backgroundColor', mycolor);
        

with the script line

            recs[i].getHtml().css('backgroundColor', mycolor);
        

Assign a script

The script is assigned to the table's onload event. The GUIDs of the free table for the numeric view field must be enclosed in quotation marks (in the order of the function parameters in the script) and separated by commas when specified here in the function call. You can find the GUIDs by pressing the F4 key when the respective element is selected on the workspace.