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:

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:

  1. refresh: for redrawing pieces of the DOM structure (within the same view).

  2. 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

Object 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.

adf.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.

adf.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:

  1. 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).
  2. For each type handler, implement a rendering member function.
  3. Optionally, implement other functions.
  4. 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.

  5. 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.