JavaScript Control Reference

Fundamentals

Your JavaScript control must include a few fundamentals, as follows.

Control Name

Your control name should match that defined in your C++ component's WCCcontrol structure.

  

  

The Structure of a JavaScript Control

All JavaScript controls share an overall html structure. They comprise an outer frame element, and an inner client element.

Frame Element:

Client Element:

You should only ever add child elements to the Client element (or its children), never to the Frame element.

  

  

JavaScript Control code structure

Most methods of a JavaScript control are added to the object's prototype. This helps reduce memory usage when lots of instances of the control are present (as may be the case with a re-useable component such as you are creating).

The standard way that we create a JS control is by creating a constructor function for the control (generally at the bottom of the file), and then create an Immediately Invoked Function Expression (IIFE) which creates the prototype for the control.

The prototype must inherit from the ctrl_base class (the base class for all JavaScript controls). This can be achieved by setting the prototype of your new control to be initially equal to a new instance of ctrl_base, then you can extend it.

The following gives a brief example of the structure:

ctrl_mycontrol.prototype = (function() {
 
    var ctrl = Object.create(ctrl_base.prototype); // The object which will become the prototype - inherited from the base class.
    var myConst = 123; // A constant value
 

    ctrl.publicMethod1 = function(p1) {
        // public methods which are inherited from the base class, and called by the JS Client framework will have 'this' set to the control instance.
        this.instVar = p1;
        privateMethod1.call(this, "abc"); // Make sure to use call() to pass the appropriate value for 'this'.
    };
 

    function privateMethod1(p1) {
      // Private method code.
    }
    return ctrl; // Return the prototype object.
 
})();
 
/**
* constructor for our control
* @constructor
*/
function ctrl_mycontrol()
{
    this.init_class_inst(); // initialize our class
}

    

    

Control Methods

Your control must also implement the following methods:

You will probably want to implement more Control Methods than these, and there are several optional ones available.

The most-used of these are already provided as stubs in the generic.js file, included in the SDK, so this is always a good starting point from which you can extend the functionality of your own control.

Loading Controls

In order for your control to work, you must tell the .htm page to load your .js file as a resource.

Alternatively, you may prefer to use your jsctempl.htm file from this same location, so whenever you generate a form's .htm file using Test Form, it will be created from this template.

image1

Do the same for any custom CSS files you are using for your control. Add these after all other CSS files except user.css, but before the <script> tags.

Themed Colors

With the introduction of theme colors to Studio 10.2 you can support these in your control.

C++ Component

When creating its innerHTML, your component should use the jsInsertColor() method to insert color properties for your control to use. This will insert the property value as an integer: either a Theme Color Constant or an explicit Omnis RGB Integer.

Example

jsInsertColor("data-mycolor", color, pInner); // inserts the value of color into the data-mycolor attribute in the controls HTML.

JS Control

Your JavaScript control should then be able to read this in and store it as an integer to work with the Theme related methods.

Example

let myColor = +this.clientElem.getAttribute("data-mycolor"); // coerce the value of "data-mycolor" into an integer to store in myColor.

Color properties that are set at runtime will be received from the server as integers in your control's setProperty() method.

Default Colors

Default property colors are all handled client-side. Your control inherits the DefaultColors property, which is an object that is used to determine the color to apply to certain elements (usually when its associated property is set to kColorDefault).

Use this in conjunction with ctrl_base.DEFAULT_COLOR_NAMES (see Constants) to access the correct member. You can override the properties here to change the default colors of your control.

Example

this.DefaultColors[ctrl_base.DEFAULT_COLOR_NAMES.BACKGROUND] = Theme.COLORS.primary // sets the default background color of your control to the primary color.

You can extend this further to add custom default colors to your control. You should create a new object of color names and add the equivalent members the DefaultColors property.

You will then be able to use this further on in your code when setting elements' colors to ensure they have the correct color when the property relating to it is set to kColorDefault.

Example

// Set up default colors
const MY_COLOR_NAMES = {
MY_COLOR: "MY_COLOR" // custom color name
};
this.DefaultColors[MY_COLOR_NAMES.MY_COLOR] = Theme.COLORS.secondary; // assigns secondary color as the default color when referencing MY_COLOR

// Assigning a color
const theme = this.getTheme(); // gets the Theme object
const myElem = document.getElementById("myElement");
myElem.style.backgroundColor = theme.getColorString(value, this.DefaultColors[MY_COLOR_NAMES.MY_COLOR]); // sets the backgroundColor of myElem to a color/theme color specified by 'value' or, if 'value' is kColorDefault uses the value held in this.DefaultColors.MY_COLOR

Text Color Handling

There is special handling for text colors to attempt to use the right default text color on top of the background color set.

For example, if you have set the background color of an element to secondary color, then when setting the text color, if its property is set to kColorDefault, it will use secondary text color.

To do this you need to resolve the background color first (as it may be set to kColorDefault), and then pass this color into getTextColorString() as its 'onColor'. See also resolveDefaultColor().

Example

const theme = this.getTheme(); // gets the Theme object
const myElem = document.getElementById("myElement");

const resolvedBackColor = this.resolveDefaultColor(backColor, ctrl_base.DEFAULT_COLOR_NAMES.BACKGROUND); // resolves the background color stored in backColor, in case it is set to kColorDefault.
myElem.style.color = theme.getTextColorString(value, resolvedBackColor, Theme.COLORS.primaryText) // sets the text color of the elem to the value, unless it is kColorDefault, then attempts to find the text color to sit on top of resolvedDefaultColor, otherwise it uses the default color specified in the third parameter, primaryText in this case.

   

 

Constants

Constants used throughout the JavaScript client are generally defined as part of an enumerated type.

Following are the base enumerated types you may need to make use of.

eAnums

eAnums

Attribute numbers, used for ascertaining the context of method calls.

Values

 

 

eBaseBorder

eBaseBorder

Set of border style constants.

Values

 

 

eBaseEvent

eBaseEvent

Standard events that are supported by the base class and that can be sent to the server.

Values

 

 

eBaseProperties

eBaseProperties

The group of constants describing the base properties. They correspond to the Omnis properties of the same name.

Values

 

eClientPlatforms

eClientPlatforms

enum of possible client platforms.

Values

 

 

eDateParts

eDateParts

The group of date part constants used in omnis_date methods.

Values

 

 

eDoMethodFlags

eDoMethodFlags

Set of flags which can be used when calling methods.

You should OR values together to set multiple flags. E.g. eDoMethodFlags.completionEvent | eDoMethodFlags.noOverlay.

Values

 

 

eOmnisDataSubTypes

eOmnisDataSubTypes

The group of values used to denote Omnis data subtypes.

Note that JavaScript is not strongly typed, so will not restrict data you enter to these types. If necessary, you should take care to ensure the data you enter matches these formats.

Values  
default = 0
Integer Subtypes intShort = 32
int32 = 0
int64 = 64
Number Subtypes numberShort = 32
numberRealDps = 31 (Logical & this with the required number of dps. E.g. eOmnisDataSubTypes.numberRealDps & 4 )
Character Subtypes characterSimple = 0
characterNational = 1
Date Subtypes date1900 = 0
date1980 = 1
date2000 = 2
dateTime1900 = 3
dateTime1980 = 4
dateTime2000 = 5
time = 6
dateTimeC = 7 (date time including a century)
timestamp = 1000 (full date time stamp) Values 1001-1030 can also be passed as an index into the date formats defined in #DFORMS.
List Subtypes listRow = 1 (If used with a type of fftList, the type will become row)

  

eOmnisDataTypes

eOmnisDataTypes

The group of constants describing the various Omnis data types.

Values

 

ctrl_base.DEFAULT_COLOR_NAMES

ctrl_base.DEFAULT_COLOR_NAMES

Set of keys to be used with the controls DefaultColors member.

Values

Info

Date Formatting

Areas of the JavaScript client allow you to specify formatting strings to determine how Date/time data should be displayed.

A date format string can make use of any of the following control characters:

Other characters will appear as-is.

E.g. "D/M/y H:N:S.s a" would display like:

"26/09/2014 17:30:05.012 pm"

 

Definitions

Color Pair

DEPRECATED in 10.2

Color Pairs are no longer needed (all browsers now support alpha), and they do not support Themed Colors. You should instead use RGB Integers or color constant values.

A Color Pair is a string defining a solid color and a color with alpha support.

Functionality within the JavaScript client makes use of these Color Pairs in order to support browsers which do not support RGBA colors.

The string must be formatted as the solid color, followed by the alpha color, separated by a semi colon:

"<solid color>;<alpha color>"

The solid color can have either the "#RRGGBB" format, or "rgb(r,g,b)" format.

The alpha color must have the "rgba(r,g,b,a)" format.

  

  

Omnis RGB Integer

Omnis RGB Integers are the standard way to represent colors in the JS Client.

They describe a color, with no alpha component. They are therefore 3 byte unsigned integers, and so have a maximum value of 16777215.

They are similar to a standard decimal color, but with the byte order reversed.

Therefore, reading the byte order from left to right.

RGB Integers with a negative value indicate that it represents a color constant, such as a themed color.

You can convert a CSS color string to an Omnis RGB Integer using the jOmnis.rgbFromCssColor() method.

Similarly, you can convert an Omnis RGB Integer to a CSS color string using <theme>.getColorString() (or <theme>.getTextColorString() if it's intended for use as a text color).

 

Number Formatting

Areas of the JavaScript client allow you to specify formatting strings to determine how numeric data should be displayed.

See the Number Formatting section of the Creating Web & Mobile Apps document (under "JavaScript Component Properties").

 

 

JavaScript Structures

omnis_cols

An omnis_cols is an object which represents a list's columns group (equivalent to $cols).

 

omnis_cols()

omnis_cols(pList)

Constructor for an omnis_cols object.

Parameters:

Returns:

Example

var myCols = new omnis_cols(myList.getListdata());

 

$add()

$add(pName, pType, pSubType, pLen)

Adds a new column onto the end of the list's columns.

Parameters:

Alternatively, you can instead just pass an array, the first element of which is the name of an Omnis Instance variable, and the column will be defined from the instance variable's definition.

Returns:

Example

var newCol = myCols.$add("Age", eOmnisDataTypes.fftInteger, eOmnisDataSubTypes.intShort, 0);

 

$count()

$count()

Returns the number of columns.

Parameters:

Returns:

Example

var colCount = myCols.$count();

 

getCanAssign( )

getCanAssign(pColumn, pPropNumber)

Returns whether the specified property can be changed for the specified column.

Parameters:

Returns:

Example

var canAssign = myCols.getCanAssign("Quantity", eBaseProperties.name); // checks whether we can change the name of the Quantity column.

  

getProperty( )

getProperty(pColumn, pPropNumber)

Gets a property from a column.

Parameters:

Returns:

Example

var colName = myCols.getProperty(3, eBaseProperties.name); // Get column 3's name

 

getValue()

getValue(pName)

Gets a column by name or column number.

Parameters:

Returns:

Example

var col3 = myCols.getValue(3);

 

setPropCli( )

setPropCli(pColumn, pPropNumber, pPropValue)

Sets a property of a column to the specified value.

Parameters:

Returns:

Example

var success = myCols.setPropCli("Quantity", eBaseProperties.name, "Amount"); // Rename the Quantities column to "Amount".

$addafter()

$addafter(pAfterCol, pName, pType, pSubType, pLen)

Adds a new column after the specified column.

Parameters:

Alternatively, you can instead just pass an array, followed by pAfterCol. The second element of the array should be the name of an Omnis Instance variable, and the column will be defined from the instance variable's definition.

Returns:

Example

var newCol = myCols.$addafter(2, "NewCol", eOmnisDataTypes.fftCharacter, eOmnisDataSubTypes.characterSimple, 1000); // Add "NewCol" as column 3.
// Or...
var newCol = myCols.$addafter(["","iVar1"],2); // Add column defined from instance variable iVar1 as column 3

 

$addbefore()

$addbefore(pBeforeCol, pName, pType, pSubType, pLen)

Adds a new column before the specified column.

Parameters:

Returns:

Example

var newCol = myCols.$addbefore(2, "NewCol", eOmnisDataTypes.fftCharacter, eOmnisDataSubTypes.characterSimple, 1000); // Add "NewCol" as column 1.
// Or...
var newCol = myCols.$addbefore(["","iVar1"],2); // Add column defined from instance variable iVar1 as column 31

 

$remove()

$remove(pCol)

Removes a column from the list.

Parameters:

Returns:

Example

mCols.$remove(3); // Remove column 3 from the list.

  

omnis_date

This object represents an Omnis Date, and provides various methods for date operations.

An omnis_date instance has the following properties:

 

 

omnis_date()

omnis_date(pValue)

Constructor. Creates a new omnis_date object.

Parameters:

Returns:

Example

var rightNow = new omnis_date(null);

 

 

equals()

equals(pOmnisDate)

Compares this omnis_date instance to another.

Parameters:

Returns:

Example

var identical = myDate.equals(myOtherDate);

 

 

toJavaScriptDate()

toJavaScriptDate()

Returns the date specified by the omnis_date instance as a standard JavaScript Date object

Parameters:

Returns:

Example

var jsDate = myDate.toJavaScriptDate();

 

 

getHasTime()

getHasTime(pOmnisDate) Static function

Returns whether the passed omnis_date instance has a time component.

This is a static function, and does not require an omnis_date instance to call it.

Parameters:

Returns:

Example

var myDate = new omnis_date(null);
omnis_date.getHasTime(myDate);

 

add()

add(pPart, pAmount)

Adds pAmount units to the date's component specified by pPart.

Does not modify the original omnis_date, but returns a new instance with the modifications.

Parameters:

Returns:

Example

var myDate = new omnis_date(null);
myDate = myDate.add(eDateParts.kDay, 10); // Add 10 days to myDate

 

getFormat()

getFormat()

Gets the format string for this date, based on its subtype (subtype only applies if it's an Omnis instance variable).

Parameters:

Returns:

Example

var fmtString = myDate.getFormat();

 

 

omnis_list

The omnis_list is the client-side representation of an Omnis list or row variable.

 

 

omnis_list()

omnis_list(pOmnisList)

Constructor for an omnis_list object.

Parameters:

Returns:

Example:

var myList = new omnis_list(null);
var myListCopy = new omnis_list(myList.getListData());

 

 

getChar()

getChar(pCol, pRowNumber, pZeroEmpty)

Returns character data for the specified column and row.

Parameters:

Returns:

Example:

var qntString = myList.getChar("quantity", 2, true);

 

 

getData( )

getData(pCol, pRowNumber)

Returns the data in the cell specified by the column and row.

Parameters:

Returns:

Example:

var name = myList.getData("Name", 2);

 

 

setData()

setData(pCol, pRowNumber, pNewData)

Sets the data in the specified row and column.

Parameters:

Returns:

Example:

var success = myList.setData("Name", 2, "Bert");

 

search(pCol, pSearchValue, pSetCurrentRow, pSelectMatches, pDeSelectNonMatches)

Searches a column in the list and returns the first matching row.

Parameters:

Returns:

Example:

var bertsRowNum = myList.search("Name", "Bert", false, false, false);

 

getRowSelectionState()

getRowSelectionState(pRowNumber)

Gets the selection state for the specified row.

Parameters:

Returns:

Example:

var isSelected = myList.getRowSelectionState(3);

 

 

setRowSelectionState()

setRowSelectionState(pRowNumber, pNewSelectionState)

Sets the selection state for the specified row.

Parameters:

Returns:

Example:

var success = myList.setRowSelectionState(3, 1); // Select row 3

 

 

setRowSelectionStateAllRows()

setRowSelectionStateAllRows(pNewSelectionState)

Sets the selection state for all rows in a list.

Parameters:

Returns:

Example:

myList.setRowSelectionStateAllRows(0); // De-select all rows

 

 

getCurrentRow()

getCurrentRow()

Returns the current row number for the list.

Parameters:

Returns:

Example:

var curLine = myList.getCurrentRow();

 

setCurrentRow()

setCurrentRow(pNewCurrentRow)

Sets the current line in the list.

Parameters:

Returns:

Example:

var success = myList.setCurrentRow(3);

 

getRowCount()

getRowCount()

Gets the number of rows in the list.

Parameters:

Returns:

Example:

var rowCount = myList.getRowCount();

 

getColumnCount()

getColumnCount()

Gets the number of columns in the list.

Parameters:

Returns:

Example:

var colCount = myList.getColumnCount();

 

addRow()

addRow(pBeforeRowNumber, pColumnCount)

Adds an empty row to the list.

Note that you can only add a row to a list (not a row).

Parameters:

Returns:

Example:

var newRowNum = myList.addRow(3,2);

 

deleteRows()

deleteRows(pActionOrRow)

Deletes the specified rows from the list.

Parameters:

Returns:

Example:

var deletedCount = myList.deleteRows(eListDeleteRow.Selected); // Delete all selected rows.

 

 

findColumn()

findColumn(pCol, pBeginsWith)

Gets the specified column's column number in the list or row.

Parameters:

Returns:

Example:

var nameCol = myList.findColumn("Name", false);

 

getRowArray()

getRowArray(pRowNumber)

Returns a row's data as an array. Each element of the array being a column of the row.

Parameters:

Returns:

Example:

var myData = myList.getRowArray(3);
var colTwoValue = myData[1];

 

getListData()

getListData()

Returns the raw list data (an omnis_raw_list object), from the list. This is needed to pass into many of the row/col methods.

Parameters:

Returns:

Example

var rawList = myList.getListData();

 

omnis_list_col

This object represents a single column in a list.

Most column actions are performed using the omnis_cols object. However, the omnis_cols methods often involve passing instances of this object around.

var myCols = new omnis_cols(myList.getListData());
var myCol = myCols.getValue(3); // Get the third column in the list.

 

 

$clear()

$clear()

Clears all values in this column.

Parameters:

Returns:

Example

var success = myCol.$clear();

 

 

$count( )

$count(pSelOnly)

Returns the number of (optionally selected) rows in the column.

Parameters:

Returns:

Example

int selectedRows = myCol.$count(true);

 

$removeduplicates()

$removeduplicates(pSortNow, pIgnoreCase)

Removes any rows which have duplicate values in this column.

Duplicates are removed from the bottom up.

Parameters:

Returns:

Example

var removedLines = myCol.$removeduplicates(true, true);

 

omnis_raw_list

The omnis_raw_list object is a component of the omnis_list object.

The omnis_raw_list functions are not exposed as part of this API, as you should use the higher-level methods available from the omnis_list object.

The omnis_list wrapper of an omnis_raw_list can be obtained from the omnis_raw_list's __list property.