Interface: methods

componyx .UI .base.methods

Methods

addTemplate(id, content, cloneable, interpolate)

Adds (or removes) a template. Templates for data-items provide support for property interpolations. These interpolations are curly bracket formatted markers which are replaced with item property values during template rendering. Example: {text} will output the value of item.text, while {customProperty} will output the value of item.attributes.customProperty.

Parameters:

Name	Type	Description
`id`	String	Id of the template.
`content`	HTMLElement \| Array.<HTMLElement> \| DocumentFragment \| String	HTML string or element node array or element node. Pass null or empty string to remove the existing template.
`cloneable`	Boolean	Defines if the template can be cloned for multiple views. Defaults to true.
`interpolate`	Boolean	Defines if a search and replace action on the inner HTML of the template will be performed to set the corresponding value for a interpolation tag (e.g. {value}).

(protected) ajaxCall(method, data, events, callArgs)

Executes and XHR call. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`method`	String	The name of the method.
`data`	Object \| String	The data to send.
`events`	Object	An object holding event handlers for various XHR events.
`callArgs`	Array.<Object>	Arguments to pass to the global event handlers.

Properties:

Name	Type	Description
`events.onStart`	componyx.library.XhrCallback	Defines the callback function to call before the request.
`events.onComplete`	componyx.library.XhrCallback	Defines the callback function to call after the request.
`events.onSuccess`	componyx.library.XhrCallback	Defines the callback function to call when the request was successful.
`events.onError`	componyx.library.XhrCallback	the callback function to call when the HTTP request failed. (HTTP status >= 200 and < 300).
`events.onAbort`	componyx.library.XhrCallback	Defines the callback function to call when the request was aborted.
`events.onProgress`	componyx.library.XhrCallback	Defines the callback function to call when there is a change in the download progress.
`events.onUploadProgress`	componyx.library.XhrCallback	Defines the callback function to call when there is a change in the upload progress.
`events.onUploadError`	componyx.library.XhrCallback	Defines the callback function to call when the upload failed.

(protected) applyTemplate(element, templateId, values, matchHandler)

Applies the template content. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`element`	HTMLElement	The element to which the template content will be added.
`templateId`	String	The id of the template.
`values`	Array.<String>	Template replacement values.
`matchHandler`	function	Callback method for the template replacement values.

(protected) childReady()

Checks if all child components have been rendered and calls the component's postRender method when this is the case. This method should not be invoked by client code directly but only from inside component code. This method is used as a postRender callback for child components.

(protected) clone(source, parent, cloneTemplatesopt, cloneEventsopt, omitKeysopt)

Clones the source component. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Attributes	Default	Description
`source`	componyx.UI.base.Component			The source component.
`parent`	componyx.UI.base.Component			The parent component.
`cloneTemplates`	Boolean	<optional>	true	A value indicating if templates are cloned.
`cloneEvents`	Boolean	<optional>	true	A value indicating if events are cloned.
`omitKeys`	Object	<optional>	null	An object with keys to omit from cloning.

(protected) cloneEvents(source)

Clones component events. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`source`	componyx.UI.base.Events	The source events.

(protected) cloneProperties(properties)

Clones component properties. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`properties`	Object	The properties to clone.

(protected) collectTemplate(element)

Gets the template HTMLElement and stores it in the component's internal template cache. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`element`	HTMLElement	The template element.

(protected) collectTemplates(templateId) → {Array.<HTMLElement>}

Gets all the template HTMLElements for the component and stores them in the component's internal template cache. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`templateId`	String	The id of the template.

Returns:

A list of collected template elements.

Type: Array.<HTMLElement>

(protected) configureElement(defaultName)

Configures the component's element. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`defaultName`	String	The default name is used as default css class and when $UI.useCustomElementNames is enabled, as the element tag name prefixed by 'com'.

(protected) createElement(defaultName, tagName, customTagName)

Creates the component's element and handles updates. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`defaultName`	String	The default name is used as default css class and when $UI.useCustomElementNames is enabled, as the element tag name prefixed by 'com'.
`tagName`	String	The tag name of the component element.
`customTagName`	String	The tag name of the component element when $UI.useCustomElementNames is enabled and a different tag than the default name is desired.

(protected) createHiddenInput(sourceElementId, onChange, isHidden)

Creates a (hidden) input field to store the input value and syncs it with the component. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`sourceElementId`	String	The identifier of the source element.
`onChange`	function	The handler for the event which fires when the hidden input value changes.
`isHidden`	bool	A value indicating if it is a hidden input.

(protected) delegateFocusEvents(instance)

Delegates focus events on the current instance to the specified instance. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`instance`	componyx.UI.base.Component	The component instance to which the focus / blur events are delegated.

destroy(keepEvents, removeElement)

Destroys the component.

Parameters:

Name	Type	Default	Description
`keepEvents`	Boolean		A value indicating if component events should be kept.
`removeElement`	Boolean	true	A value indicating if the corresponding HTML Element should be removed.

(protected) getCssClass(classOption, cssClassValue) → {String}

Gets the css class for the specified class option value: the value of the matching cssClass property on the component when set, otherwise the default value. Example: for the key 'BUILD_PANE' the property 'cssClassBuildPane' is checked.

Parameters:

Name	Type	Description
`classOption`	Object	The class option object of the component.
`cssClassValue`	String	The default css class (a value of the class option object).

Returns:

The resolved css class.

Type: String

(protected) getSourceElement(elementId)

Gets the source element. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`elementId`	String	The identifier of the source element.

(protected) getTemplateContent() → {DocumentFragment}

Gets the template content for the specified template id. This method should not be invoked by client code directly but only from inside component code.

Returns:

The template content.

Type: DocumentFragment

(protected) getThemeCSS()

Returns the CSS class string for the component's theme. This method should not be invoked by client code directly but only from inside component code.

hasTemplate(templateId) → {Boolean}

Checks if the template with the specified template id exists.

Parameters:

Name	Type	Description
`templateId`	String	The id of the template.

Returns:

True if the template is present, otherwise false.

Type: Boolean

hide()

Hides the component.

(protected) initRenderPhase(resourceHandler, defaultName, hasTheme)

Initializes the render phase for the component. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`resourceHandler`	function	The callback method for registering script and css resources.
`defaultName`	String	The default name is used as default css class and when $UI.useCustomElementNames is enabled, as the element tag name prefixed by 'cui'.
`hasTheme`	Boolean	A value indicating if the component has a CSS theme.

(protected) invokePreRender() → {boolean}

Invokes pre-render actions and fires the onPreRender event. This method should not be invoked by client code directly but only from inside component code.

Returns:

A value indicating if the render should be canceled.

Type: boolean

move(container, beforeopt)

Moves the component to a new position within the DOM.

Parameters:

Name	Type	Attributes	Description
`container`	HTMLElement		The new container element.
`before`	HTMLElement	<optional>	The new before element.

(protected) mutationCallback(mutations, observer)

Handles attribute mutations, updates corresponding properties, and triggers a single render after all mutations are processed.

Parameters:

Name	Type	Description
`mutations`	Array.<MutationRecord>	An array of mutation records containing details of the observed attribute changes.
`observer`	MutationObserver	The MutationObserver instance that is observing changes to the DOM.

(protected) onBlur(instanceopt)

Checks the blur state of the component and fires the blur event accordingly. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Attributes	Description
`instance`	componyx.UI.base.Component	<optional>	A component for which to check the blur state.

(protected) onFocus(instanceopt)

Checks the focus state of the component and fires the focus event accordingly. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Attributes	Description
`instance`	componyx.UI.base.Component	<optional>	A component for which to check the focus state.

(protected) postBack(arg, formId)

Executes a form post-back. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`arg`	String	The postback argument.
`formId`	String	The id of the form.

(protected) postRender()

Executes the post render procedure. This method should not be invoked by client code directly but only from inside component code.

(protected) registerResources(resourceHandler, callback)

Registers required resources (CSS and JS) for the component. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`resourceHandler`	function	The callback method for fetching resources.
`callback`	function	The callback to call after resources are loaded.

render(resourceHandler, defaultName, hasTheme, tagName, customTagName)

Renders the component.

Parameters:

Name	Type	Description
`resourceHandler`	function	The callback method for registering script and css resources.
`defaultName`	String	The default name is used as default css class and when $UI.useCustomElementNames is enabled, as the element tag name prefixed by 'com'.
`hasTheme`	Boolean	A value indicating if the component has a CSS theme.
`tagName`	String	The tag name of the component element.
`customTagName`	String	The tag name of the component element when $UI.useCustomElementNames is enabled and a different tag than the default name is desired.

(protected) renderChildren()

Calls the render method on all child components. This method should not be invoked by client code directly but only from inside component code.

(protected) setPostBackArgs(frm, arg)

Sets the postback arguments. This method should not be invoked by client code directly but only from inside component code.

Parameters:

Name	Type	Description
`frm`	HTMLElement	The form element.
`arg`	String	The postback argument.

(protected) setupMutationObserver()

Sets up the mutation observer to track attribute changes and DOM element removal. This method should not be invoked by client code directly but only from inside component code.

show()

Shows the component.

toggle()

Hides the component when it's showing, otherwise it shows the component.

(static) suppressNextChangeEvent(action)

Suppresses any change events fired by the underlying input element during the execution of the provided action. Use this when programmatically setting a component value to prevent the change event from propagating as a user interaction. The suppression is automatically lifted after the action completes, even if it throws.