18 Creating Custom MAF AMX UI Components

This chapter describes how to create custom MAF AMX UI components and specify them as part of the development environment.

This chapter includes the following sections:

18.1 Introduction to Creating Custom UI Components

Using a combination of JavaScript and APIs provided by MAF, you can create new, fully functional interactive UI components and add them to a tag library to be used in your MAF AMX application feature.

18.2 Using MAF APIs to Create Custom Components

MAF provides the following APIs for creating custom components:

Static APIs (see How to Use Static APIs)
AmxEvent Classes (see How to Use AmxEvent Classes)
TypeHandler (see How to Use the TypeHandler)
AmxNode (see How to Use the AmxNode)
AmxTag (see How to Use the AmxTag)
VisitContext (see How to Use the VisitContext)
AmxAttributeChange (see How to Use the AmxAttributeChange)
AmxDescendentChanges (see How to Use the AmxDescendentChanges)
AmxCollectionChange (see How to Use the AmxCollectionChange)
AmxNodeChangeResult (see How to Use the AmxNodeChangeResult)
AmxNodeStates (see How to Use the AmxNodeStates)
AmxNodeUpdateArguments (see How to Use the AmxNodeUpdateArguments)

18.2.1 How to Use Static APIs

Table 18-1 lists static APIs that you can use to create custom UI components.

Table 18-1 Static APIs

Return Type	Function Name	Parameters	Description
`Function`	`adf.mf.api.amx.TypeHandler.register`	`String namespaceUrl,` `String tagName,` `adf.mf.api.amx.TypeHandler precreatedClass`	Registers a `TypeHandler` class with a tag namespace and name. Returns the registered `adf.mf.api.amx.TypeHandler` subclass so that prototype functions can be added. The `precreatedClass` is optional but can be used if you first create a class that inherits from `adf.mf.api.amx.TypeHandler`.
`void`	`adf.mf.api.amx.addBubbleEventListener`	`Node domNode,` `String eventType,` `Function listener,` `Object eventData`	Registers a bubble event listener (such as tap, taphold, keydown, touchstart, touchmove, touchend, focus, blur, resize, and so on). Note that web browsers do not support all event types on all DOM nodes (see the browser documentation for details). The `eventData` is optional and serves as extra data to be made available to the listener function.
`void`	`adf.mf.api.amx.removeBubbleEventListener`	`Node domNode,` `String eventType,` `Function listener`	Unregisters a bubble event listener that was added through `adf.mf.api.amx.addBubbleEventListener`. Note that the removal of the meta events tap and taphold will cause all touchstart and touchend listeners, including those of other meta events, to become removed from the element as opposed to only the specified listener being removed.
`void`	`adf.mf.api.amx.addDragListener`	`Node domNode,` `Object payload,` `Object eventData`	Allows an element to trigger MAF AMX drag events. The `Object` `payload` defines three member functions: `start`, `drag`, `end`. The first parameter of each function is the DOM event, the second parameter is a `dragExtra` `Object` with the following members: `eventSource`: the DOM event source. `pageX`: the `x` coordinate of the event. `pageY`: the `y` coordinate of the event. `startPageX`: the original `pageX`. `startPageY`: the original `pageY`. `deltaPageX`: the change in `pageX`. `deltaPageY`: the change in `pageY`. `originalAngle`: if defined, it is the original angle of the drag in degrees where 0 degrees is East, 90 is North, -90 is South, 180 is West. and the following modifiable member flags: `preventDefault` `stopPropagation` The `eventData` is optional and serves as extra data to be made available to the listener functions.
`void`	`adf.mf.api.amx.removeDomNode`	`Node domNode`	Removes a DOM node and its children, but prior to that removes event listeners added through `adf.mf.api.amx.addBubbleEventListener`.
void	`adf.mf.api.amx.emptyHtmlElement`	`Node domNode`	Empties an HTML element by removing children DOM nodes and calling `adf.mf.api.amx.removeDomNode` on each of the children nodes.
`void`	`adf.mf.api.amx.processAmxEvent`	`adf.mf.api.amx.AmxNode amxNode,` `String amxEventType,` `String attributeValueName,` `String newValue,` `AmxEvent amxEvent,` `Function finishedCallback`	Processes an `AmxEvent`. Change the value if `attributeValueName` is defined, process the appropriate `setPropertyListener` and `actionListener` subtags, and then process the `[amxEventType]Listener` attribute. If a finished callback is provided, it will be invoked once the event is processed.
`void`	`adf.mf.api.amx.acceptEvent`	None	Determines whether it is safe to proceed with invoking `adf.mf.api.amx.processAmxEvent` in order to avoid preparing anything you might need to pass into that function (for example, when in the middle of a page transition or in an environment such as a design-time preview).
`void`	`adf.mf.api.amx.invokeEl`	`String expression,` `Array<String> params,` `String returnType,` `Array<String> paramTypes,` `Function successCallback,` `Function failureCallback`	Represents a utility similar to `adf.mf.el.invoke()` for invoking an EL method, with a difference that it refrains from execution in environments such as design-time previews.
`void`	`adf.mf.api.amx.enableAmxEvent`	`adf.mf.api.amx.AmxNode amxNode,` `Node domNode,` `String eventType`	Allows a DOM node to trigger custom MAF AMX events such as `tapHold` and `swipe` for `amx:showPopupBehavior`, `amx:setPropertyListener`, and so on.
`void`	`adf.mf.api.amx.doNavigation`	`String outcome`	Tells the controller that there is an intention to perform navigation for a given outcome.
`void`	`adf.mf.api.amx.validate`	`Node domNode,` `Function successCallback`	Prevents an operation, such as navigation, when there are unsatisfied validators (required or `amx:validationBehavior`). The `successCallback` is invoked if allowed to proceed.
`void`	`adf.mf.api.amx.showLoadingIndicator`	`Number failSafeDuration,` Function failSafeClientHandler	Shows the busy indicator. The parameters: failSafeDuration: The approximate duration (non-negative integer in milliseconds) that MAF waits between showing and hiding the loading indicator (assuming some other trigger has not already shown the indicator). If this parameter is not specified or is set to `null`, then MAF uses the value of 10000 (10 seconds). failSafeClientHandler: The optional JavaScript function that is invoked when the `failSafeDuration` has been reached. This function can be used to decide how to proceed. This function must return a `String` defined by one of the following values: - `hide`: to hide the indicator as in the default fail-safe. - `repeat`: to restart the timer for another duration where the function may get invoked again. - `freeze`: to keep the indicator up and wait indefinitely; the page may become stuck in a frozen state until restarted. To prevent the indicator from being displayed for longer than necessary, hide it.
`void`	`adf.mf.api.amx.hideLoadingIndicator`	None	Hides one instance of the loading indicator.
`Object`	`adf.mf.api.amx.createIterator`	`Object dataItems`	Creates an iterator that supports either a JavaScript array of objects or iterator over a tree node iterator (collection model). Returns an iterator `Object` with `next`, `hasNext`, and `isTreeNodeIterator` functions where `next` returns undefined if no more objects are available.
`void`	`adf.mf.api.amx.bulkLoadProviders`	`Object treeNodeIterator,` `Number startingPoint,` `Number maximumNumberOfRowsToLoad,` `Function successCallback,` `Function failCallback`	Bulk-loads a set of data providers so they are cached and are locally accessible.
`String`	`adf.mf.api.amx.buildRelativePath`	`String url`	Builds the relative path based on the specified resource assuming it is relative to the current MAF AMX page. If there is a protocol on the resource, then it is assumed to be an absolute path and left unmodified.
`void`	`adf.mf.api.amx.markNodeForUpdate`	`adf.mf.api.amx.AmxNodeUpdateArguments args`	Function for `TypeHandler` instances to notify MAF of a state change to an `AmxNode` that requires the `AmxNode` hierarchy to be updated at that node and below. If a custom `createChildrenNodes` method exists on the `TypeHandler`, it is called again for these `AmxNode` instances. This allows `AmxNode` instances that stamp their children to add new stamps due to a user change. The `refresh` method is called on the `AmxNode` with the provided properties if the `AmxNode` is ready to render. If the `AmxNode` is not ready to render, MAF waits for any EL to be resolved and the `refresh` method is called once all the data are available.

Note:

Other public APIs are available in the adf.mf.el package for logging, translation, and data channel.

18.2.2 How to Use AmxEvent Classes

Table 18-2 lists AMXEvent classes that you can use when creating custom UI components.

Table 18-2 AMXEvent Classes

Class Name	Parameters	Description
`adf.mf.api.amx.ActionEvent`	None	An event triggering an outcome-based navigation. See also `oracle.adfmf.amx.event.ActionEvent` in .
`adf.mf.api.amx.MoveEvent`	`Object rowKeyMoved,` `Object rowKeyInsertedBefore`	An event for notifying that a specified row has been moved. It contains the key for the row that was moved along with the key for the row before which it was inserted. See also `oracle.adfmf.amx.event.MoveEvent` in .
`adf.mf.api.amx.SelectionEvent`	`Object oldRowKey,` `Array<Object> selectedRowKeys`	An event for changes of selection for a component. See also `oracle.adfmf.amx.event.SelectionEvent` in .
`adf.mf.api.amx.ValueChangeEvent`	`Object oldValue,` `Object newValue`	An event for changes of value for a component. See also `oracle.adfmf.amx.event.ValueChangeEvent` in .

18.2.3 How to Use the TypeHandler

Table 18-3 lists TypeHandler APIs that you can use to create custom UI components.

Table 18-3 TypeHandler APIs

Return Type	Function Name	Parameters	Description
`HTMLElement`	`render`	`adf.mf.api.amx.AmxNode amxNode,` `String id`	Creates an initial DOM structure and returns the root element of the structure. This member function is required and must be defined.
`void`	`init`	`HTMLElement rootElement,` `adf.mf.api.amx.AmxNode amxNode`	Represents the handler invoked after all `create` functions that belong to the set of components created with this component are invoked.
`void`	`postDisplay`	`HTMLElement rootElement,` `adf.mf.api.amx.AmxNode amxNode`	Represents the handler invoked after all `init` functions that belong to the set of components created with this component are invoked.
`Boolean`	`createChildrenNodes`	`adf.mf.api.amx.AmxNode amxNode`	Selectively adds `AmxNode` children for processing. Note that if one of the children is shown, the use of this function prevents processing of the other children. Should return `false` if MAF is to create the children nodes instead of the custom implementation. This function is optional.
`adf.mf.api.amx.AmxNodeChangeResult`	`updateChildren`	`adf.mf.api.amx.AmxNode amxNode,` `adf.mf.api.amx.AmxAttributeChange attributeChanges`	Represents a handler for one of the following: removing any old children and creating and adding any new children to the `AmxNode`. through the return value, declaring what `adf.mf.api.amx.AmxNodeChangeResult` action should be taken. This function is optional.
`adf.mf.api.amx.AmxNodeChangeResult`	`getDescendentChangeAction`	`adf.mf.api.amx.AmxNode amxNode,` `adf.mf.api.amx.AmxDescendentChanges descendentChanges`	Allows a type handler to customize the handling of changes to descendent `AmxNode` instances.
`void`	`refresh`	`adf.mf.api.amx.AmxAttributeChange attributeChanges,` `adf.mf.api.amx.AmxDescendentChanges descendentChanges`	Allows a type handler to selectively refresh the HTML in response to a change. This method is called after the `updateChildren` method. The `attributeChanges` defines the changed attributes. If `descendentChanges` is not `null`, it defines the changes for any descendent nodes that need to be refreshed.
`Boolean`	`isFlattenable`	None	Declares whether or not the `AmxNode` is flattenable.Note that a flattened AmxNode might not have any behavior related to rendering: a type handler for a flattened AmxNode can only control child node creation and visiting, but cannot influence rendering.
`Boolean`	`visit`	`adf.mf.api.amx.VisitContext visitContext,` `Function visitCallback`	Handles an `AmxNode` tree visitation starting from this `AmxNode`. The `visitCallback` function to invoke when visiting uses parameters `visitContext` and `AmxNode`. Returns whether or not the visitation is complete and should not continue.
`Boolean`	`visitChildren`	`adf.mf.api.amx.AmxNode amxNode,` `adf.mf.api.amx.VisitContext visitContext,` `Function visitCallback`	Handles an `AmxNode` tree visitation starting from the children of this `AmxNode`. The `visitCallback` function to invoke when visiting uses parameters `visitContext` and `AmxNode`. Returns whether or not the visitation is complete and should not continue.
`void`	`preDestroy`	`HTMLElement rootElement,` `adf.mf.api.amx.AmxNode amxNode`	Handles anything just before the current view is destroyed; when about to navigate to a new view. Typically used to save client state such as scroll positions (see `adf.mf.api.amx.setClientState`).
`void`	`destroy`	`HTMLElement rootElement,` `adf.mf.api.amx.AmxNode amxNode`	Handles anything after the new view is displayed and the old view is being removed.

18.2.4 How to Use the AmxNode

Table 18-4 lists AmxNode APIs that you can use to create custom UI components.

Table 18-4 AmxNode APIs

String	Function Name	Parameters	Description
`String`	`getId`	None	Gets the unique identifier for this `AmxNode`. This value contributes to the ID on the root DOM element.
`adf.mf.api.amx.AmxTag`	`getTag`	None	Gets the `AmxTag` that created this `AmxNode`.
`adf.mf.api.amx.TypeHandler`	`getTypeHandler`	None	Gets the `TypeHandler` object associated with this `AmxNode`.
`void`	`setClientState`	`Object payloadJsonObject`	Stores or replaces the client state for the specified `AmxNode` ID. Type handlers should call this function whenever a state change happens (for example, something that should be cached so that when the user navigates to a new page and then comes back, it would be restored like a scroll position). That said, it is not always feasible to detect when a state change happens so you may need to update the state for your component just before the view is going to be discarded. There are two possible scenarios for which you need to account: `refresh`: for redrawing pieces of the DOM structure (within the same view). `preDestroy`: for navigating to a new view and later navigating back. The `payloadJsonObject` is the client state data to store for the lifetime of this view instance.
`Object`	`getClientState`	None	Gets the `payloadJsonObject` that was previously stored through the `setClientState` function during this view instance (undefined if not available).
`void`	`setVolatileState`	`Object payloadJsonObject`	Stores or replaces the client state for the specified `AmxNode` ID. Type handlers should call this function whenever a volatile state change happens (for example, something that should be forgotten when navigating to a new MAF AMX page but should be kept in case a component is redrawn). The `payloadJsonObject` is the volatile state data to store until navigation occurs.
`Object`	`getVolatileState`	None	Gets the `payloadJsonObject` that was previously stored through the `setVolatileState` function since the last navigation (undefined if not available).
`Object`	`getConverter`	None	Get the converter, if applicable, for this `AmxNode`.
`void`	`setConverter`	`Object converter`	Set the converter for this `AmxNode`.
`String`	`storeModifyableEl`	`String nameOfTheAttribute`	For an attribute, creates and stores an EL expression that may be used to set EL values into the model. The value is context-insensitive and may be used to set a value at any time. Common use is to set a value based on user interaction. This function may be called by type handlers. Returns `null` if the subject attribute is not bound to an EL value.
`Object`	`getStampKey`	None	Gets the stamp key for the `AmxNode`. The stamp key identifies `AmxNode` instances that are produced inside of iterating containers. This is provided by the parent `AmxNode`. An example tag that uses stamp keys is the `amx:iterator` tag. Returns `null` if the `AmxNode` is not stamped.
`Array<String>`	`getDefinedAttributeNames`	None	Gets a list of the attribute names that have been defined for this node.
`Object`	`getAttribute`	`String name`	Gets an attribute value for the attribute of the given name. Return value may be `null`. Returns undefined if the attribute is not set or is not yet loaded.
`void`	`setAttributeResolvedValue`	`String name,` `Object value`	Used by the type handler or MAF to store the attribute value for an attribute onto the `AmxNode`. This function does not update the model.
`void`	`setAttribute`	`String name,` `String value`	Sets the value of an attribute on the model. This value is sent to the Java side to update the EL value. The value on the `AmxNode` is not updated by this call. Instead, it is expected that a data change event will update the `AmxNode`.
`Boolean`	`isAttributeDefined`	`String name`	Checks whether the attribute was defined by the user.
`adf.mf.api.amx.AmxNode`	`getParent`	None	Gets either the parent `AmxNode` or `null` if at the top level.
`void`	`addChild`	`adf.mf.api.amx.AmxNode child,` `String facetName`	Adds a child `AmxNode` to this `AmxNode`. The `facetName` should be `null` if the child does not belong in a facet.
`Boolean`	`removeChild`	`adf.mf.api.amx.AmxNode child`	Removes a child `AmxNode` from this `AmxNode`. Note that the child is removed from the hierarchy, but not the DOM for it. It is up to the caller to remove the DOM. This is to allow type handlers to handle animation and other transitions when DOM is replaced. Returns whether or not the child was found and removed.
`Boolean`	`replaceChild`	`adf.mf.api.amx.AmxNode oldChild,` `adf.mf.api.amx.AmxNode newChild`	Replaces an existing child with another child. Returns whether or not the old one was found and replaced.
`Array<adf.mf.api.amx.AmxNode>`	`getChildren`	`String facetName,` `Object stampKey`	Gets children `AmxNodes`. The two parameters are optional. The `facetName` can be `null` to get the non-facet children. Returns an empty array if no children exist or if there are no children for the given qualifiers.
`Map<String, Array<adf.mf.api.amx.AmxNode>>`	`getFacets`	`Object stampKey`	Gets all of the facets of the `AmxNode`. The `stampKey` is optional; if provided, it retrieves the facet `AmxNode` instances for a given stamp key.
`Boolean`	`visit`	`adf.mf.api.amx.VisitContext visitContext,` `Function visitCallback`	Performs a tree visitation starting from this `AmxNode`. The `visitCallback` function should accept the `visitContext` and the `AmxNode` as arguments. Returns whether or not the visitation is complete and should not continue.
`Boolean`	`visitChildren`	`adf.mf.api.amx.VisitContext visitContext,` `Function visitCallback`	Performs a tree visitation starting from the children of this `AmxNode`. The `visitCallback` function should accept the `visitContext` and the `AmxNode` as arguments. Returns whether the visitation is complete and should not continue.
`Boolean`	`visitStampedChildren`	`Object stampKey,` `Array<String> facetNamesToInclude,` `Function filterCallback,` `adf.mf.api.amx.VisitContext visitContext,` `Function visitCallback`	Convenience function for type handlers that stamp their children to visit the children `AmxNode` from inside of a custom `visitChildren` function. When `facetNamesToInclude` is empty, no facets are processed for this stamp. When `facetNamesToInclude` is `null`, all facets are processed for this stamp. The `filterCallback` may be `null`. The `filterCallback` must return a `Boolean` of `true`, meaning the tag will be used to create children, or `false`, meaning the tag will not be processed. The `visitCallback` should accept the `visitContext` and `AmxNode` as arguments. Returns whether or not the visitation is complete and should not continue.
`Array<adf.mf.api.amx.AmxNode>`	`getRenderedChildren`	`String facetName,` `Object stampKey`	Gets the rendered children of the `AmxNode`. The `facetName` indicates from which facet to retrieve the rendered children, or `null` for the non-facet children. If the `stampKey` is provided, it retrieves the children `AmxNode` instances for a given stamp key. Returns the children that should be rendered for the given stamp key. It flattens any components that can be flattened (flattenable) and does not return any non-rendered ones.
`Boolean`	`isFlattenable`	None	Determines whether or not the `AmxNode` is flattenable. Note that a flattened AmxNode might not have any behavior related to rendering: a type handler for a flattened AmxNode can only control child node creation and visiting, but cannot influence rendering.
`adf.mf.api.amx.AmxNodeStates`	`getState`	None	Gets the current state of the `AmxNode` (as a constant value from `adf.mf.api.amx.AmxNodeStates`).
`void`	`setState`	`state`	Moves the `adf.mf.api.amx.AmxNodeStates` state of the `AmxNode`. Should only be called by MAF or the `AmxNode`'s type handler.
`HTMLElement`	`render`	None	Renders the `AmxNode`. Returns the root element rendered or `null` if the child is not rendered or if there is no type handler for this `AmxNode`.
`Array<HTMLElement>`	`renderDescendants`	`String facetName,` `Object key`	Renders the subnodes of this `AmxNode` (if applicable, it flattens to the nearest descendant). If `facetName` is not `null`, it renders the children of that facet. If facetName is `null`, the non-facet children are rendered. The optional key is used for rendering the children `AmxNode` instances for that stamping key. Returns an array of the root elements for each `subNode`.
`void`	`rerender`	None	Rerenders the `AmxNode`.
`Boolean`	`isRendered`	None	Checks the state of the `AmxNode` to see whether or not it should be rendered. The `AmxNode` is considered to be renderable if it is in the `ABLE_TO_RENDER, RENDERED` or `PARTIALLY_RENDERED` state.
`void`	`refresh`	`adf.mf.api.amx.AmxAttributeChange attributeChanges,` `adf.mf.api.amx.AmxDescendentChanges descendentChanges`	Refreshes the DOM of an `AmxNode`. This method is called after the `updateChildren` method and should be implemented by type handlers that wish to update their DOM in response to a change.
`void`	`createStampedChildren`	O`bject stampKey,` `Array<String> facetNamesToInclude,` `Function filterCallback`	Convenience function for type handlers that stamp their children to create child `AmxNode` instances from inside of a custom `createChildrenNodes` function. This function creates children for any UI tags. If `facetNamesToInclude` is empty, the facets are not processed for this stamp. If `facetNamesToInclude` is `null`, all the facets are processed. If the `facetNamesToInclude` includes a `null` value inside the array, children for non-facet tags are created. The `filterCallback` is an optional function to filter the children that are created. The `filterCallback` function is invoked with the `AmxNode`, the `stampKey`, the child tag, and the facet name (or `null` for non-facets). The `filterCallback` function must return a `boolean`. If `true`, the tag is used to create children; if `false`, the tag is not processed.

18.2.5 How to Use the AmxTag

Table 18-5 lists AmxTag APIs that you can use to create custom UI components.

Table 18-5

Return Type	Function Name	Parameters	Description
`String`	`getNamespace`	None	Gets the XML namespace URI for the tag.
`String`	`getNsPrefixedName`	None	Returns the tag name including the namespace as its prefix (not the local `xmlns` prefix). This is the full XML name such as `"http://xmlns.example.com/custom:custom"`.
`String`	`getName`	None	Gets the tag name. This is the local XML tag name without the prefix.
a`df.mf.api.amx.AmxTag`	`getParent`	None	Gets the parent tag or `null` if it is the top-level tag.
`String`	`getTextContent`	None	Returns the text content of the tag.
`Array<adf.mf.api.amx.AmxTag>`	`findTags`	`String namespace,` `String tagName`	Recursively searches the tag hierarchy for tags with the given namespace and tag name. Returns the current tag if it matches.
`Array<adf.mf.api.amx.AmxTag>`	`getChildren`	`String namespace,` `String tagName`	Gets the children of the tag. Provides for optional filtering of the children namespaces and tag names. If a namespace is `null`, all the children are returned. If `tagName` is `null`, the children are not filtered by tag name.
`Array<adf.mf.api.amx.AmxTag>`	`getChildrenFacetTags`	None	Get all of the children facet tags. This function is meant to assist the creation of the `AmxNode` process.
`adf.mf.api.amx.AmxTag`	`getChildFacetTag`	`String name`	Gets the facet tag with the given name. This function is meant to assist the code if the presence of a facet changes the behavior of a type handler. Returns `null` if the facet is not found.
`Array<adf.mf.api.amx.AmxTag>`	`getChildrenUITags`	None	Gets all children tags that are UI tags. This function is meant to assist in creation of the `AmxNode` process. This function not return any facet tags.
`Array<String>`	`getAttributeNames`	None	Gets all of the attribute names for the attributes that are specified on the tag.
`Boolean`	`isAttributeElBound`	`String name`	Determines whether or not the given attribute is bound to an EL expression (as opposed to a static value).
`String`	`getAttribute`	`String name`	Gets the attribute value (may be an EL string) for the attribute of the given name. Returns undefined if the attribute is not specified.
`Map<String, String>`	`getAttributes`	None	Gets a key-value pair map of the attributes and their values.
`Boolean`	`isUITag`	None	Determines whether or not the node is a UI tag with a type handler and renders content.
`Object{name:string, children:Array<adf.mf.api.amx.AmxTag>}`	`getFacet`	None	Gets the tags for the children of this facet and the name of the facet if this tag is a facet tag. This is a convenience function for building the `AmxNode` tree. Returns an object with the name of the facet and the children tags of the facet. Returns `null` if the tag is not an `amx:facet` tag.
`adf.mf.api.amx.AmxNode`	`buildAmxNode`	`adf.mf.api.amx.AmxNode parentNode,` `Object stampKey`	Creates a new instance of an `AmxNode` for this tag given the stamp ID. If the tag is a facet tag, the tag creates an `AmxNode` for the child tag. This function does not initialize the `AmxNode`. Instead, it returns either an uninitialized `AmxNode` or `null` for non-UI tags.
`adf.mf.api.amx.TypeHandler`	`getTypeHandler`	None	Gets the type handler for this tag.

18.2.6 How to Use the VisitContext

Table 18-6 lists VisitContext APIs that you can use when creating custom UI components.

Table 18-6 VisitContext APIs

Return Type	Function Name	Parameters	Description
`Boolean`	`isVisitAll`	None	Determines whether or not all nodes should be visited.
`Array<adf.mf.api.amx.AmxNode>`	`getNodesToWalk`	None	Gets the nodes that should be walked during visitation. This list does not necessarily include the nodes that should be visited (callback invoked).
`Array<adf.mf.api.amx.AmxNode>`	`getNodesToVisit`	None	Get the list of nodes to visit.
`Array<adf.mf.api.amx.AmxNode>`	`getChildrenToWalk`	`adf.mf.api.amx.AmxNode parentAmxNode`	Determine which child AmxNode instances, including facets (if any), should be walked of the given parent `AmxNode`. Allows for type handlers to optimize how to walk the children if not all are being walked. May return `null`.

18.2.7 How to Use the AmxAttributeChange

Table 18-7 lists AmxAttributeChange APIs that you can use when creating custom UI components.

Table 18-7 AmxAttributeChange APIs

Return Type	Function Name	Parameters	Description
`Array<String>`	`getChangedAttributeNames`	None	Gets the names of the attributes that have been affected during the current change.
`Boolean`	`isCollectionChange`	`String name`	Determines whether the attribute change is a collection change.
`adf.mf.api.amx.AmxCollectionChange`	`getCollectionChange`	`String name`	Gets the collection model change information for an attribute. Returns null if no change object is available.
`String`	`getOldValue`	`String name`	Gets the value of the attribute before the change was made.
`Boolean`	`hasChanged`	`String name`	Determines whether the attribute with the given name has changed.
`Number`	`getSize`	None	Gets the number of attribute changes.

18.2.8 How to Use the AmxDescendentChanges

Table 18-8 lists AmxAttributeChange APIs that you can use when creating custom UI components.

Table 18-8 AmxDescendentChanges APIs

Return Type	Function Name	Parameters	Description
`Array<adf.mf.api.amx.AmxNode>`	`getAffectedNodes`	None	Gets the unrendered changed descendent `AmxNode` instances.
`adf.mf.api.amx.AmxAttributeChange`	`getChanges`	`adf.mf.api.amx.AmxNode amxNode`	Gets the changes for a given AmxNode.
`adf.mf.api.amx.AmxNodeStates`	`getPreviousNodeState`	`adf.mf.api.amx.AmxNode amxNode`	Gets the state of the descendent AmxNode before the changes were applied.

18.2.9 How to Use the AmxCollectionChange

Table 18-9 lists AmxCollectionChange APIs that you can use when creating custom UI components.

Table 18-9 AmxCollectionChange APIs

Return Type	Function Name	Parameters	Description
`Boolean`	`isItemized`	None	Determines whether or not the change to the collection may be itemized: the keys and elements on that collection were identified, so the `TypeHandler` can update just the appropriate items as opposed to rerendering the entire list from scratch.
`Array<String>`	`getCreatedKeys`	None	Gets either an array of keys that were created, or `null` if the change cannot be itemized.
`Array<String>`	`getDeletedKeys`	None	Gets either an array of the keys that were removed, or null if the change cannot be itemized.
`Array<String>`	`getUpdatedKeys`	None	Gets either an array of the keys that were updated, or null if the change cannot be itemized.
`Array<String>`	`getDirtiedKeys`	None	Gets either an array of the keys that were dirtied, or null if the change cannot be itemized.

18.2.10 How to Use the AmxNodeChangeResult

Table 18-10 lists AmxNodeChangeResult APIs that you can use when creating custom UI components.

Table 18-10 AmxNodeChangeResult APIs

Members	Description
`adf.mf.api.amx.AmxNodeChangeResult["NONE"]`	Takes no action in response to an attribute change on a non-rendered descendent `AmxNode`.
`adf.mf.api.amx.AmxNodeChangeResult["REFRESH"]`	The attribute and its child AmxNode instances have been updated by the type handler and the DOM will be updated by the type handler's `refresh` function.
`adf.mf.api.amx.AmxNodeChangeResult["RERENDER"]`	The AmxNode and its child AmxNode instances have been updated by the type handler, but the DOM should only be recreated as there is no need to modify the `AmxNode` hierarchy so the `refresh` function will not be called on the type handler.
`adf.mf.api.amx.AmxNodeChangeResult["REPLACE"]`	The type handler cannot handle the change. The DOM, as well as the `AmxNode` hierarchy should be recreated. This value may only be returned from the `updateChildren` method on a type handler and cannot be returned from the `getDescendentChangeAction` method.

18.2.11 How to Use the AmxNodeStates

Table 18-11 lists AmxNodeStates APIs that you can use when creating custom UI components.

Table 18-11 AmxNodeStates APIs

Members	Description
`adf.mf.api.amx.AmxNodeStates["INITIAL"]`	Initial state. The `AmxNode` has been created but not populated.
a`df.mf.api.amx.AmxNodeStates["WAITING_ON_EL_EVALUATION"]`	EL-based attributes needed for rendering have not been fully loaded yet.
`adf.mf.api.amx.AmxNodeStates["ABLE_TO_RENDER"]`	EL attributes have been loaded, but the `AmxNode` has not yet been rendered.
`adf.mf.api.amx.AmxNodeStates["PARTIALLY_RENDERED"]`	The EL is not fully loaded, but the `AmxNode` has partially rendered itself (reserved for future use).
`adf.mf.api.amx.AmxNodeStates["RENDERED"]`	The `AmxNode` has been fully rendered.
`adf.mf.api.amx.AmxNodeStates["UNRENDERED"]`	The AmxNode is not to be rendered.

18.2.12 How to Use the AmxNodeUpdateArguments

Table 18-12 lists AmxNodeUpdateArguments APIs that you can use when creating custom UI components.

Table 18-12 AmxNodeUpdateArguments APIs

Return Type	Function Name	Parameters	Description
`Array<adf.mf.api.amx.AmxNode>`	`getAffectedNodes`	None	Gets an array of affected `AmxNode` instances.
`Map<String,Boolean>`	`getAffectedAttributes`	`String amxNodeId`	Gets an object representing the affected attributes for a given AmxNode ID.
`Map<String,adf.mf.api.amx.AmxCollectionChange>`	`getCollectionChanges`	`String amxNodeId`	Gets the collection changes for a given AmxNode and property. The returned map is keyed by attribute name. Returns undefined if there are no changes for the `AmxNode`.
`void`	`setAffectedAttribute`	`adf.mf.api.amx.AmxNode amxNode,` `String attributeName`	Marks an attribute of an AmxNode as affected.
`void`	`setCollectionChanges`	`String amxNodeId,` `String attributeName,` `adf.mf.api.amx.AmxCollectionChange collectionChanges`	Sets the collection changes for a given `AmxNode`'s attribute.

18.3 Creating Custom Components

You can create a custom UI component through the use of JavaScript and MAF APIs. This component's JavaScript file can be added to your project through the application feature-level includes. When you add your custom tag library, it is entered into the Components window's list of tag libraries and, when this library is selected, your custom component becomes available in the Components window, with its attributes displayed in the Properties window.

Before you begin

Familiarize yourself with APIs described in Using MAF APIs to Create Custom Components.

To create a custom component:

Produce a JavaScript file that registers a tag namespace and series of one or more type handlers using the adf.mf.api.amx.TypeHandler.register API (see Table 18-1 and the example later in this section).
For each type handler, implement a rendering member function.
Optionally, implement other functions.
Attach one or more of your JavaScript and CSS files to the MAF AMX application feature. For examples, see the following sample applications available from File > New > MAF Examples:
- custom.js and custom.css files included in the MAF sample application called CompGallery.
- WorkBetter sample application contains a custom search component.
Alternatively, you can perform a design-time packaging.
For each MAF AMX page that uses one of the customs components, add an xmlns entry in the view element:
```
xmlns:custom="http://xmlns.example.com/custom"
```

This example shows a JavaScript file that declares custom components.

(function() {
   // TypeHandler for custom "x" elements
   var x = adf.mf.api.amx.TypeHandler.register("http://xmlns.example.com/custom",                                                "x");
   x.prototype.render = function(amxNode) {
      var rootElement = document.createElement("div");
      rootElement.appendChild(document.createTextNode("Hello World"));
      return rootElement;
   };

   // TypeHandler for custom "y" elements
   var y = adf.mf.api.amx.TypeHandler.register("http://xmlns.example.com/custom",
                                               "y");

   y.prototype.render = function(amxNode) {
      var rootElement = document.createElement("div");
      rootElement.appendChild(document.createTextNode("Goodbye World"));
      return rootElement;
   };

})();

For examples of how to create custom UI components, see the custom.amx, customOther.amx, exampleEvents.amx, and exampleList.amx files included in the MAF sample application called CompGallery. This sample application is available from File > New > MAF Examples.