Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 Custom Controls : Component Interface

Component Interface
The initialize() method for the ControlWrapper receives an object of type Component. This provides an interface that the ControlWrapper can use to obtain information and configuration from the form layer, and to also raise events back to the form so they can trigger rules defined in the form model.
The Component object provides the following APIs:
generateId()
This method generates an identifier that is unique on this page. It allocates IDs to the HTML Elements created within the ControlWrapper.
 
A ControlWrapper would want to use this method if it generates any DOM nodes in the HTML that need to be directly referenced using ID. Using this method will ensure that the ID used will not be in conflict with other IDs on the page.
Method Argument
suffix (optional)
Method Return Value
getControl()
This method returns the Form-level Control that corresponds the custom control instance. This provides access to all the getter methods that are available on the control object in a form-level action script. It also provides the getter and setter methods for all the custom properties.
Method Return Value
getFactory()
This method returns the factory object that is available within Form action scripts. This will allow wrappers to create new objects as part of their functionality. This object will expose factories that are in the library project as well as those available from the Forms project using the custom control and any in referenced projects, recursively.
Method Return Value
getForm()
This method returns the Form that contains the custom component.
Method Return Value
getHintId()
This method returns the ID of the DOM node which renders the standard, form-supplied hint for this control. It is useful in situations where the hint needs to be referenced for accessibility purposes. For example: by using the ID in corresponding ARIA attributes on the control widgets.
Method Return Value
getLabelId()
This method returns the ID of the DOM node which renders the standard, form-supplied label for this control. It is useful in situations where the label needs to be referenced for accessibility purposes. For example: by using the ID in corresponding ARIA attributes on the control widgets.
Method Return Value
getLocale()
This method returns the String representation of the locale in which the control should be rendered.
Method Return Value
getParentNode()
This method returns the parent DOM node into which this control should render its contents.
Method Return Value
getPresentationURL()
This method returns the base URL of the Presentation Resources folder of the project, in which a custom control is defined.
For example, if a project contains myimage.gif located at project/Presentation Resources/images, you can compute the URL of this image using:
var mypath = component.getPresentationURL() + "/images/myimage.gif";
Method Return Value
getResources()
This method returns an object that provides access to all localized resource bundles defined at the library level and the component level for this particular Component. Resources are accessed using the resource name and individual keys. For example: for a resource with name resource.myName created at the library or at the component level that has a key called myLabelKey in it, its value can be retrieved using:
      var resources = component.getResources();
      var myLabel = resources.myName.myLabelKey;
The resources returned correspond to the locale in effect for the form when rendered.
Method Return Value
getValidationMessageIds()
This method returns an array of DOM identifiers which represents any validation messages currently in effect for this control. There is one ID for each message pane in the form. Useful in situations where the messages need to be referenced for accessibility purposes. If null, then there are currently no validation errors reported against this control. If the array is non-null but empty, this signifies that there are errors, but no messages are displayed because the Form does not contain a Messages pane.
Method Return Value
raiseEvent()
This method is invoked by the ControlWrapper when it needs to propagate an event back to the Form layer. Most controls should raise at least the update event in order to notify the form layer that the control value has changed. It is not necessary to raise an update event when updating the attribute value of a complex object or updating the list for a multi-valued complex type. The BOM JavaScript representations of these objects handle the updates internally.
Method Arguments
eventName: Name of the event as configured in the component metadata. This name should correspond to one of the events specified as supported by the component type. Built-in events include close, doubleclick, enter, exit, localize, open, select, submit, and update.
eventValue: Object that differs depending on the event being raised. For update events, this is the new value. Other events do not need an eventValue. Any custom-defined events ignore the eventValue.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved