Scriptable Reports

CustomControlModule

The interface implemented by custom control modules. The file is referenced using the "Module path" property of a Custom Control. The module instance can be accessed using the instance member of a CustomControl. For an explanation of when events are called, see Order of Events. See Communicating Between Custom Controls for examples of how instances of custom controls can communicate with each other.
Containment

Examples

Download

define( function() {
"use strict";

function BasicControl()
{
};

BasicControl.prototype.draw = function( oControlHost )
{
	oControlHost.container.innerHTML = "Hello";
};

return BasicControl;
});

Download

define( function() {
"use strict";

function AdvancedControl()
{
};

AdvancedControl.prototype.initialize = function( oControlHost, fnDoneInitializing )
{
	fnDoneInitializing();
};

AdvancedControl.prototype.destroy = function( oControlHost )
{
};

AdvancedControl.prototype.draw = function( oControlHost )
{
	oControlHost.container.innerHTML = "Hello";
};

AdvancedControl.prototype.show = function( oControlHost )
{
};

AdvancedControl.prototype.hide = function( oControlHost )
{
};

AdvancedControl.prototype.isInValidState = function( oControlHost )
{
};

AdvancedControl.prototype.getParameters = function( oControlHost )
{
};

AdvancedControl.prototype.setData = function( oControlHost, oDataStore )
{
};

return AdvancedControl;
});

Methods

destroy(oControlHost)

The control is being destroyed so do any necessary cleanup. This method is optional.
Parameters:
Name Type Description
oControlHost ControlHost The control host.

draw(oControlHost)

Draw the control. This method is optional if the control has no UI.
Parameters:
Name Type Description
oControlHost ControlHost The control host.
Example
MyControl.prototype.draw = function( oControlHost )
{
	oControlHost.container.innerHTML = "Hello";
};

getParameters(oControlHost) → (nullable) {Array.<Parameter>|Array.<RangeParameter>}

Called by the ControlHost to get the current values to use for parameters fulfilled by the control. This method is optional.
Parameters:
Name Type Description
oControlHost ControlHost The control host.
Returns:
An array of parameters.
Type
Array.<Parameter> | Array.<RangeParameter>
Example
C_HtmlSelect.prototype.getParameters = function( oControlHost )
{
	if ( this.m_sel.selectedIndex < 1 )
	{
		return null;
	}
	var sValue = this.m_sel.options[this.m_sel.selectedIndex].value;
	return [{
		"parameter": "parameter1",
		"values": [{ "use" : sValue }]
	}];
};

hide(oControlHost)

Called when the control is being hidden (not displayed). This method is optional.
Parameters:
Name Type Description
oControlHost ControlHost The control host.

initialize(oControlHost, fnDoneInitializing)

Initialize the control. This method is optional. If this method is implemented, fnDoneInitializing must be called when done initializing.
Parameters:
Name Type Description
oControlHost ControlHost The control host.
fnDoneInitializing function The callback function to tell the control host when the initialization has completed.
Example

Asynchronous initialization

MyControl.prototype.initialize = function( oControlHost, fnDoneInitializing )
{
	requirejs( ["Module"], this.dependenciesLoaded.bind( this, fnDoneInitializing ) )
};

MyControl.prototype.dependenciesLoaded = function( fnDoneInitializing, oModule )
{

	fnDoneInitializing();
};

isInValidState(oControlHost) → {Boolean}

The valid state of the control. This method is optional. This is used to determine things like enabling "Next" and "Finish" prompt buttons.
Parameters:
Name Type Description
oControlHost ControlHost The control host.
Returns:
true if the control is in a valid state and false otherwise.
Type
Boolean
Example
C_HtmlSelect.prototype.isInValidState = function( oControlHost )
{
	return ( this.m_sel.selectedIndex > 0 );
};

setData(oControlHost, oDataStore)

Called to pass authored data into the control. This method is optional.
Parameters:
Name Type Description
oControlHost ControlHost The control host.
oDataStore DataStore The data as a data store.
Examples

Keep a single data store to use later when drawing

MyControl.prototype.setData = function( oControlHost, oDataStore )
{
	this.m_oDataStore = oDataStore;
};

Keep multiple data stores by index to use later when drawing

MyControl.prototype.setData = function( oControlHost, oDataStore )
{
	this.m_aDataStore[oDataStore.index] = oDataStore;
};

Keep multiple data stores by name to use later when drawing

MyControl.prototype.setData = function( oControlHost, oDataStore )
{
	this.m_oDataStores[oDataStore.name] = oDataStore;
};

show(oControlHost)

Called when the control is being shown (displayed). This method is optional.
Parameters:
Name Type Description
oControlHost ControlHost The control host.