Scriptable Reports

ControlHost

The interface used by custom controls to interact with the report.
Containment

Members

(readonly, nullable) configuration :JSON

The authored configuration JSON. This can be used to parameterize a control. If there's no configuration authored, this will be null.
Type:
Example

Allow the author to pass in the parameter name to set

var sParameterName = oControlHost.configuration.parameter;

(readonly) container :HTMLElement

The container HTML element the control draws itself into.
Type:
  • HTMLElement
Example
oControlHost.container.innerHTML = sHtml;

(readonly) control :CustomControl

The public control interface.
Type:

(readonly) isDestroyed :Boolean

The destroyed state of the control. true if the control has been destroyed and false if the control has not been destroyed. This is useful to check at the completion of an asynchronous operation to ensure that the control hasn't been destroyed before continuing.
Type:
  • Boolean

(readonly) isVisible :Boolean

The visibility state of the control. true if the control is visible and false if the control is not visible.
Type:
  • Boolean

loadingText :String

Sets the text displayed until the control's draw method is called. This is useful if an asynchronous initialize method is required.
Type:
  • String
Example
oControlHost.loadingText = "Loading...";

(readonly) locale :String

Get the locale.
Type:
  • String
Example
elButton.textContent = ( oControlHost.locale.indexOf( "de" ) == 0 ) ? "Anwenden" : "Apply";

(readonly) page :Page

The page containing the control.
Type:
Example
var oControl = oControlHost.page.getControlByName( "Control1" );

Methods

back()

Go back one prompt page.

cancel()

Cancel report execution.

finish()

Submit parameter values and skip all remaining optional prompts and prompt pages.

generateUniqueID()

Generate a unique HTML ID. This ID can be used to safely insert HTML requiring IDs during a draw.
Warning:
The generated ID's uniqueness is based on the current IDs in the document. Calling this function multiple times will generate the same ID if an element using the previously generated ID has not been inserted into the document.
2
Examples
MyControl.prototype.draw = function( oControlHost )
{
	oControlHost.container.innerHTML = '<div id="' + oControlHost.generateUniqueID() + '"></div>';
};

How to generate a unique ID prior to version 2

MyControl.prototype.generateUniqueID = function( sBase )
{
	var sID = v_sBase;
	d = document;
	var i = 1;
	while ( d.getElementById( sID ) )
	{
		sID = sBase + i++;
	}
	return sID;
};

getParameter(sParameter) → (nullable) {Array.<Parameter>|Array.<RangeParameter>}

Called to get the current value of a parameter. Useful for selecting the initial values of a custom control. If the parameter doesn't exist, null is returned.
Parameters:
Name Type Description
sParameter String The parameter name.
Returns:
A parameter.
Type
Array.<Parameter> | Array.<RangeParameter>

next()

Submit parameter values and go to the next prompt page.

refresh()

Refresh the report
4

reprompt()

If the report contains prompt pages, the first prompt page is displayed. Otherwise, if the report doesn't contain prompt pages, this will re-prompt for values.

run()

Run the report
4

validStateChanged()

Called to notify the ControlHost that the valid state of the control has changed.

valueChanged()

Called to notify the ControlHost that a value has change.
Example
C_HtmlSelect.prototype.onSelectChange = function( oControlHost )
{
	oControlHost.valueChanged();
};