12 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:
12.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.
12.2 Using MAF APIs to Create Custom Components
MAF provides the following APIs for creating custom components:
-
Static APIs (see Section 12.2.1, "How to Use Static APIs")
-
AmxEventClasses (see Section 12.2.2, "How to Use AmxEvent Classes") -
TypeHandler(see Section 12.2.3, "How to Use the TypeHandler") -
AmxNode(see Section 12.2.4, "How to Use the AmxNode") -
AmxTag(see Section 12.2.5, "How to Use the AmxTag") -
VisitContext(see Section 12.2.6, "How to Use the VisitContext") -
AmxAttributeChange(see Section 12.2.7, "How to Use the AmxAttributeChange") -
AmxDescendentChanges(see Section 12.2.8, "How to Use the AmxDescendentChanges") -
AmxCollectionChange(see Section 12.2.9, "How to Use the AmxCollectionChange") -
AmxNodeChangeResult(see Section 12.2.10, "How to Use the AmxNodeChangeResult") -
AmxNodeStates(see Section 12.2.11, "How to Use the AmxNodeStates") -
AmxNodeUpdateArguments(see Section 12.2.12, "How to Use the AmxNodeUpdateArguments")
12.2.1 How to Use Static APIs
Table 12-1 lists static APIs that you can use to create custom UI components.
Table 12-1 Static APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
|
Registers a Returns the registered The |
|
|
|
|
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 |
|
|
|
|
Unregisters a bubble event listener that was added through 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. |
|
|
|
|
Allows an element to trigger MAF AMX drag events. The
and the following modifiable member flags:
The |
|
|
|
|
Removes a DOM node and its children, but prior to that removes event listeners added through |
|
void |
|
|
Empties an HTML element by removing children DOM nodes and calling |
|
|
|
|
Processes an Change the value if |
|
|
|
None |
Determines whether it is safe to proceed with invoking |
|
|
|
|
Represents a utility similar to |
|
|
|
|
Allows a DOM node to trigger custom MAF AMX events such as |
|
|
|
|
Tells the controller that there is an intention to perform navigation for a given outcome. |
|
|
|
|
Prevents an operation, such as navigation, when there are unsatisfied validators (required or The |
|
|
|
Function failSafeClientHandler |
Shows the busy indicator. The parameters:
To prevent the indicator from being displayed for longer than necessary, hide it. |
|
|
|
None |
Hides one instance of the loading indicator. |
|
|
|
|
Creates an iterator that supports either a JavaScript array of objects or iterator over a tree node iterator (collection model). Returns an iterator |
|
|
|
|
Bulk-loads a set of data providers so they are cached and are locally accessible. |
|
|
|
|
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. |
|
|
|
|
Function for If a custom |
Note:
Other public APIs are available in the adf.mf.el package for logging, translation, and data channel.
12.2.2 How to Use AmxEvent Classes
Table 12-2 lists AMXEvent classes that you can use when creating custom UI components.
Table 12-2 AMXEvent Classes
| Class Name | Parameters | Description |
|---|---|---|
|
|
None |
An event triggering an outcome-based navigation. See also |
|
|
|
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 |
|
|
|
An event for changes of selection for a component. See also |
|
|
|
An event for changes of value for a component. See also |
12.2.3 How to Use the TypeHandler
Table 12-3 lists TypeHandler APIs that you can use to create custom UI components.
Table 12-3 TypeHandler APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
|
Creates an initial DOM structure and returns the root element of the structure. This member function is required and must be defined. |
|
|
|
|
Represents the handler invoked after all |
|
|
|
|
Represents the handler invoked after all |
|
|
|
|
Selectively adds Should return This function is optional. |
|
|
|
|
Represents a handler for one of the following:
This function is optional. |
|
|
|
|
Allows a type handler to customize the handling of changes to descendent |
|
|
|
|
Allows a type handler to selectively refresh the HTML in response to a change. This method is called after the The |
|
|
|
None |
Declares whether or not the |
|
|
|
|
Handles an The |
|
|
|
|
Handles an The |
|
|
|
|
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 |
|
|
|
|
Handles anything after the new view is displayed and the old view is being removed. |
12.2.4 How to Use the AmxNode
Table 12-4 lists AmxNode APIs that you can use to create custom UI components.
Table 12-4 AmxNode APIs
| String | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Gets the unique identifier for this |
|
|
|
None |
Gets the |
|
|
|
None |
Gets the |
|
|
|
|
Stores or replaces the client state for the specified 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:
The |
|
|
|
None |
Gets the |
|
|
|
|
Stores or replaces the client state for the specified The |
|
|
|
None |
Gets the |
|
|
|
None |
Get the converter, if applicable, for this |
|
|
|
|
Set the converter for this |
|
|
|
|
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 |
|
|
|
None |
Gets the stamp key for the This is provided by the parent Returns |
|
|
|
None |
Gets a list of the attribute names that have been defined for this node. |
|
|
|
|
Gets an attribute value for the attribute of the given name. Return value may be Returns undefined if the attribute is not set or is not yet loaded. |
|
|
|
|
Used by the type handler or MAF to store the attribute value for an attribute onto the This function does not update the model. |
|
|
|
|
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 |
|
|
|
|
Checks whether the attribute was defined by the user. |
|
|
|
None |
Gets either the parent |
|
|
|
|
Adds a child The |
|
|
|
|
Removes a child 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. |
|
|
|
|
Replaces an existing child with another child. Returns whether or not the old one was found and replaced. |
|
|
|
|
Gets children The two parameters are optional. The Returns an empty array if no children exist or if there are no children for the given qualifiers. |
|
|
|
|
Gets all of the facets of the The |
|
|
|
|
Performs a tree visitation starting from this The Returns whether or not the visitation is complete and should not continue. |
|
|
|
|
Performs a tree visitation starting from the children of this The Returns whether the visitation is complete and should not continue. |
|
|
|
|
Convenience function for type handlers that stamp their children to visit the children When The The Returns whether or not the visitation is complete and should not continue. |
|
|
|
|
Gets the rendered children of the The If the 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. |
|
|
|
None |
Determines whether or not the 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. |
|
|
|
None |
Gets the current state of the |
|
|
|
|
Moves the |
|
|
|
None |
Renders the Returns the root element rendered or |
|
|
|
|
Renders the subnodes of this If The optional key is used for rendering the children Returns an array of the root elements for each |
|
|
|
None |
Rerenders the |
|
|
|
None |
Checks the state of the The |
|
|
|
|
Refreshes the DOM of an This method is called after the |
|
|
|
O
|
Convenience function for type handlers that stamp their children to create child This function creates children for any UI tags. If The |
12.2.5 How to Use the AmxTag
Table 12-5 lists AmxTag APIs that you can use to create custom UI components.
Table 12-5
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Gets the XML namespace URI for the tag. |
|
|
|
None |
Returns the tag name including the namespace as its prefix (not the local This is the full XML name such as |
|
|
|
None |
Gets the tag name. This is the local XML tag name without the prefix. |
|
a |
|
None |
Gets the parent tag or |
|
|
|
None |
Returns the text content of the tag. |
|
|
|
|
Recursively searches the tag hierarchy for tags with the given namespace and tag name. Returns the current tag if it matches. |
|
|
|
|
Gets the children of the tag. Provides for optional filtering of the children namespaces and tag names. If a namespace is |
|
|
|
None |
Get all of the children facet tags. This function is meant to assist the creation of the |
|
|
|
|
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 |
|
|
|
None |
Gets all children tags that are UI tags. This function is meant to assist in creation of the This function not return any facet tags. |
|
|
|
None |
Gets all of the attribute names for the attributes that are specified on the tag. |
|
|
|
|
Determines whether or not the given attribute is bound to an EL expression (as opposed to a static value). |
|
|
|
|
Gets the attribute value (may be an EL string) for the attribute of the given name. Returns undefined if the attribute is not specified. |
|
|
|
None |
Gets a key-value pair map of the attributes and their values. |
|
|
|
None |
Determines whether or not the node is a UI tag with a type handler and renders content. |
|
|
|
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 Returns an object with the name of the facet and the children tags of the facet. Returns |
|
|
|
|
Creates a new instance of an If the tag is a facet tag, the tag creates an This function does not initialize the |
|
|
|
None |
Gets the type handler for this tag. |
12.2.6 How to Use the VisitContext
Table 12-6 lists VisitContext APIs that you can use when creating custom UI components.
Table 12-6 VisitContext APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Determines whether or not all nodes should be visited. |
|
|
|
None |
Gets the nodes that should be walked during visitation. This list does not necessarily include the nodes that should be visited (callback invoked). |
|
|
|
None |
Get the list of nodes to visit. |
|
|
|
|
Determine which child AmxNode instances, including facets (if any), should be walked of the given parent Allows for type handlers to optimize how to walk the children if not all are being walked. May return |
12.2.7 How to Use the AmxAttributeChange
Table 12-7 lists AmxAttributeChange APIs that you can use when creating custom UI components.
Table 12-7 AmxAttributeChange APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Gets the names of the attributes that have been affected during the current change. |
|
|
|
|
Determines whether the attribute change is a collection change. |
|
|
|
|
Gets the collection model change information for an attribute. Returns null if no change object is available. |
|
|
|
|
Gets the value of the attribute before the change was made. |
|
|
|
|
Determines whether the attribute with the given name has changed. |
|
|
|
None |
Gets the number of attribute changes. |
12.2.8 How to Use the AmxDescendentChanges
Table 12-8 lists AmxAttributeChange APIs that you can use when creating custom UI components.
Table 12-8 AmxDescendentChanges APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Gets the unrendered changed descendent |
|
|
|
|
Gets the changes for a given AmxNode. |
|
|
|
|
Gets the state of the descendent AmxNode before the changes were applied. |
12.2.9 How to Use the AmxCollectionChange
Table 12-9 lists AmxCollectionChange APIs that you can use when creating custom UI components.
Table 12-9 AmxCollectionChange APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Determines whether or not the change to the collection may be itemized: the keys and elements on that collection were identified, so the |
|
|
|
None |
Gets either an array of keys that were created, or |
|
|
|
None |
Gets either an array of the keys that were removed, or null if the change cannot be itemized. |
|
|
|
None |
Gets either an array of the keys that were updated, or null if the change cannot be itemized. |
|
|
|
None |
Gets either an array of the keys that were dirtied, or null if the change cannot be itemized. |
12.2.10 How to Use the AmxNodeChangeResult
Table 12-10 lists AmxNodeChangeResult APIs that you can use when creating custom UI components.
Table 12-10 AmxNodeChangeResult APIs
| Members | Description |
|---|---|
|
|
Takes no action in response to an attribute change on a non-rendered descendent |
|
|
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 |
|
|
The AmxNode and its child AmxNode instances been updated by the type handler, but the DOM should only be recreated as there is no need to modify the |
|
|
The type handler cannot handle the change. The DOM, as well as the This value may only be returned from the |
12.2.11 How to Use the AmxNodeStates
Table 12-11 lists AmxNodeStates APIs that you can use when creating custom UI components.
Table 12-11 AmxNodeStates APIs
| Members | Description |
|---|---|
|
|
Initial state. The |
|
a |
EL-based attributes needed for rendering have not been fully loaded yet. |
|
|
EL attributes have been loaded, but the |
|
|
The EL is not fully loaded, but the |
|
|
The |
|
|
The AmxNode is not to be rendered. |
12.2.12 How to Use the AmxNodeUpdateArguments
Table 12-12 lists AmxNodeUpdateArguments APIs that you can use when creating custom UI components.
Table 12-12 AmxNodeUpdateArguments APIs
| Return Type | Function Name | Parameters | Description |
|---|---|---|---|
|
|
|
None |
Gets an array of affected |
|
|
|
|
Gets an object representing the affected attributes for a given AmxNode ID. |
|
|
|
|
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 |
|
|
|
|
Marks an attribute of an AmxNode as affected. |
|
|
|
|
Sets the collection changes for a given |
12.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 Section 12.2, "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.registerAPI (see Table 12-1, "Static APIs" and Example 12-1, "JavaScript File for Custom Components"). -
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 located in the
PublicSamples.zipfile within thejdev_install/jdeveloper/jdev/extensions/oracle.maf/Samplesdirectory on your development computer:-
custom.jsandcustom.cssfiles included in the MAF sample application called CompGallery. -
WorkBetter sample application contains a custom search component.
Alternatively, you can perfrom a design-time packaging.
-
-
For each MAF AMX page that uses one of the customs components, add an
xmlnsentry in theviewelement:xmlns:custom="http://xmlns.example.com/custom"
Example 12-1 shows a JavaScript file that declares custom components.
Example 12-1 JavaScript File for 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. The sample applications are located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.
