Interface: ControlHost

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:

JSON

Example

Allow the author to pass in the parameter name to set

let { parameter } = oControlHost.configuration;

(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:

CustomControl

(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:

Page

Example

const oControl = oControlHost.page.getControlByName( "Control1" );

Methods

back()

Go back one prompt page.

NOTE:
This function is not supported in a saved output report. See Application#isSavedOutput

cancel()

Cancel report execution.

NOTE:
This function is not supported in a saved output report. See Application#isSavedOutput

finish()

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

NOTE:
This function is not supported in a saved output report. See Application#isSavedOutput

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.

Since: Version 2

Examples

class CustomControl
{
	draw( oControlHost )
	{
		oControlHost.container.innerHTML = `<div id="${oControlHost.generateUniqueID()}"></div>`;
	}
}

Generating a unique ID prior to Version 2

generateUniqueID( sBase )
{
	const d = document;
	let sID = v_sBase;
	let 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.

NOTE:
This function is not supported in a saved output report. See Application#isSavedOutput

refresh()

Refresh the report

Since: Version 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.

NOTE:
This function is not supported in a saved output report. See Application#isSavedOutput

run()

Run the report

Since: Version 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

class CustomControl
{
	...
	onSelectChange( oControlHost )
	{
		oControlHost.valueChanged();
	}
}