JavaScript API Reference for Oracle ADF Faces

oracle.adf.view.js.base
Class AdfPage

org.ecmascript.object.Object
   |
   +--oracle.adf.view.js.base.AdfObject
         |
         +--oracle.adf.view.js.base.AdfPage

Direct Known Subclasses:

AdfDhtmlPage

public class AdfPage
extends AdfObject

ACTIVE_COMPONENT_PROPERTY

public static Object ACTIVE_COMPONENT_PROPERTY

_changedComponentCount

private Object _changedComponentCount

_changedComponents

private Object _changedComponents

CREATE_VIEW_PHASE

public static Object CREATE_VIEW_PHASE

Phase when initially creating the client view.

See also:

getPhase()

DELIVER_EVENTS_PHASE

public static Object DELIVER_EVENTS_PHASE

Phase during event delivery

See also:

getPhase()

EDITABLE_SUBTREE_PROPERTY

public static Object EDITABLE_SUBTREE_PROPERTY

Property name for the editable subtree property

See also:

getEditableSubtree()

setEditableSubtree(AdfUIComponent)

addPropertyChangeListener(Object, Function)

removePropertyChangeListener(Object, Function)

EDITED_COMPONENT_PROPERTY

public static Object EDITED_COMPONENT_PROPERTY

Property name for the current inline-edited component property

See also:

getEditedComponent()

setEditedComponent(AdfUIComponent, Event)

addPropertyChangeListener(Object, Function)

removePropertyChangeListener(Object, Function)

_FOR_CONTAINER_PREFIX

private static Object _FOR_CONTAINER_PREFIX

ID prefix that is also used on the server to identify a container for future message DOM.

_localeContext

private Object _localeContext

_lookAndFeel

private Object _lookAndFeel

_NEW_WINDOW_NAME

private static Object _NEW_WINDOW_NAME

PAGE

public static Object PAGE

Static reference to the page context Object for theis Rich Client Page. This variable is initialized in the Adfbootstrap process by calling

_phase

private Object _phase

SELECTED_EDITING_COMPONENTS_PROPERTY

public static Object SELECTED_EDITING_COMPONENTS_PROPERTY

Property name for the array of inline-selected editable components property

See also:

getSelectedEditingComponents()

setSelectedEditingComponents(Array<AdfUIComponent>)

addPropertyChangeListener(Object, Function)

removePropertyChangeListener(Object, Function)

UPDATE_VIEW_PHASE

public static Object UPDATE_VIEW_PHASE

DEPRECATED: this phase is not currently used or set.

WAITING_FOR_USER_INPUT_PHASE

public static Object WAITING_FOR_USER_INPUT_PHASE

Phase when waiting for user input

See also:

getPhase()

AdfPage

public AdfPage()

Abstract base Page Management class. Instances of this class are created by calling AdfLookAndFeel.createRichPage() on the appropriate AdfLookAndFeel subclass.

addBusyStateListener

public Object addBusyStateListener(Object instance,
                                   Function listener)

Adds a listener to be invoked whenever there is a busy state event. For example a component might be implemented with native machine code instead of web standards and would not be able to automatically convey to the user that the page is currently busy. Such a component would require special code for this purpose. Application developers should not need to call this method explicitly. Components which are interested in busy state events will automatically register themselves, typically in their InitDomElement peer implementation.

Parameters:

instance	-	the object to use as 'this' when invoking the handler
listener	-	the listener to be invoked if there is a busy state event, the first parameter will be an AdfBusyStateEvent object

Return:

Object

See also:

removeBusyStateListener(Object, Function)

addChangedComponent

public Object addChangedComponent(Object component)

Marks a component as having attribute changes that need to be synched to the server

Parameters:

component

Return:

Object

addComponents

public Object addComponents(Object components)

Add the list of components as varargs to be managed by the Page

Parameters:

components

Return:

Object

addMessage

public Object addMessage(String componentId,
                         AdfFacesMessage facesMessage,
                         Object toBeRemoved)

Adds a Message to AdfPage's message queue.

Parameters:

componentId	-	the id of the component to add this message to or null for a global message
facesMessage	-	the message
toBeRemoved

Return:

Object

addPartialTargets

public Object addPartialTargets(Object components)

Adds the components to the set of components that will be redrawn on the next communication with the server.

Parameters:

components

Return:

Object

addPropertyChangeListener

public Object addPropertyChangeListener(Object instance,
                                        Function listener)

Adds a PropertyChangeListener with the specified instance and listener function

Parameters:

instance	-	Object to use as "this" when calling the listener
listener	-	Function to call when an AdfDhtmlPage property changes

Return:

Object

See also:

EDITABLE_SUBTREE_PROPERTY

SELECTED_EDITING_COMPONENTS_PROPERTY

EDITED_COMPONENT_PROPERTY

announceToAssistiveTechnology

public Object announceToAssistiveTechnology(Object message,
                                            Object onlyIfChanged)

Issues an announcement for AT users using our "status" WAI-ARIA live region.

Parameters:

message	-	the message to announce
onlyIfChanged	-	an optional parameter that if true, causes the message to be announced only if the message is different from the previous status message. This provides a simple way to prune out duplicate messages (eg. a progressIndicator that has not progressed since the last update).

Return:

Object

checkUncommittedData

public Object checkUncommittedData()

Displays uncommitted data warning if <af:document> has uncommittedDataWarning="on", and the page contains uncommitted data (either on the client or on the server).

Return:

Object - true if the navigation should proceed, false otherwise

clearAllMessages

public Object clearAllMessages()

Clears all of the messages for a particular page.

Return:

Object

ClearChangesList

protected Object ClearChangesList()

Clears the list of components with changes that need to be synched to the server

Return:

Object

clearMessages

public Object clearMessages(String componentId)

Clears a messages for a particular component id. If component Id is null then the Global messages are cleared.

Parameters:

componentId

-

a componentId or null for global messages

Return:

Object

Dispose

protected Object Dispose()

Called to tear down the AdfPage instance

Return:

Object

doResizeNotify

public Object doResizeNotify(Object component)

Performs the resize notify traversal on the subtree rooted at the specified component.

Parameters:

component

Return:

Object

findComponent

public AdfUIComponent findComponent(String clientId)

Retrieves a component by its clientID. Page authors should rarely need to call this function and should usually call AdfPage.findComponentByAbsoluteId instead.

Because this function uses the clientId, which isn't guaranteed to be stable across runs, to locate the component, it should never be passed a hard-coded String. Rather, it is typically passed the clientId retrieved from a component instance.

The structure of the clientId passed to this function is identical to the structure passed to UIViewRoot.invokeOnComponent on the server.

Parameters:

clientId

-

Id of component instance to find on the page

Return:

AdfUIComponent - returns the component with the specified id, if any

See also:

findComponentByAbsoluteId(String)

findComponent(String)

findComponentByAbsoluteId

public AdfUIComponent findComponentByAbsoluteId(String absoluteId)

Search for and return the AdfUIComponent with an id that matches the specified absolute id expression. Since this function only accepts absolute expressions (scoped id expressions that contain the ids of all of the NamingContainers between the document root and the targeted component, separated by NamingContainer.SEPARATOR_CHAR), a leading colon is not used to identify the expression as an absolute expression.

This function should be used by page authors rather than AdfPage.findComponent since AdfPage.findComponent uses the clientId to identify the component. The clientId is implementation-dependent and could change if the component implementations change.

The structure of the absoluteId passed to this function is identical to the structure passed to UIViewRoot.findComponent on the server.

Parameters:

absoluteId

-

A non-null absolute search expression identifying the AdfUIComponent to be returned. The expression should contain the ids of all of the NamingContainers between the root of the page and the targeted component, separated by colons and ending with the id of the targeted component.

Return:

AdfUIComponent - the matching component instance, or undefined if no component matching that search expression exists

See also:

findComponent(String)

AdfUIComponent.findComponent(String, Boolean)

findComponentByAbsoluteLocator

public AdfUIComponent findComponentByAbsoluteLocator(String absoluteLocator)

Search for and return the AdfUIComponent with an id that matches the specified absolute locator expression.

Parameters:

absoluteLocator

-

an implementation-agnostic String identifier. Provided primarily for test automation users. For most components, absoluteLocator will be same as absoluteId, except in the case of stamping components like table. For stamped components the syntax of the locator will be containing stamp key in square brackets([]). For example if a component in the table row has client Id as NC1:C2:tableId:6:componentId then absolute locator will be NC1:C2:tableId[stampKey]:componentId and absolute id will be NC1:C2:tableId:componentId .

Return:

AdfUIComponent - the matching component instance, or undefined if no component matching that absolute locator exists

getActiveComponent

public AdfUIComponent getActiveComponent()

Returns the AdfUIComponent with the current keyboard focus

Return:

AdfUIComponent - The focused AdfUIComponent, if any

See also:

ACTIVE_COMPONENT_PROPERTY

getActiveComponentId

public Object getActiveComponentId()

Returns the id of the currently active component on the page.

Return:

Object

getAllMessages

public Object getAllMessages()

Return an object containing all messages keyed by componentID and containing an array of FacesMessages. Messages for non-visible and non-existing components will not be returned

Return:

Object - an object containing arrays of FacesMessages which are keyed by componentId.

getBaseResourceUrl

public Object getBaseResourceUrl()

Gets the base URL for resources.

Deprecated: this relies on client-side url manipulation which will not work in a portal environment. This should not be used. Instead, url's should be created and encoded on the server.

Return:

Object

GetChangedComponents

protected Object GetChangedComponents()

Returns an Object containing keys mapping from the clientIds of the changed components to their instances

Return:

Object

getClientIdsWithMessages

public Array getClientIdsWithMessages(String rootId)

Return an array of the client identifiers for which at least one FacesMessage has been queued. If there are no such client identifiers, an empty array is returned. If any messages have been queued that were not associated with any specific client identifier, a null value will be included in the array of values.

ids for non-visible and non-existing components will not be returned

It is possible to only search for client ids with messages within a subtree by passing in a rootId. When a rootId is passed in a null value will not be included for messages not associated with any specific client identifier.

Parameters:

rootId

-

a componentId for the root of a subtree under which to search. If no rootId is passed in then all client id's with messages will be returned.

Return:

Array - array of client identifiers for which at least one FacesMessage has been queued

getDefaultMessageHandlerComponentId

public String getDefaultMessageHandlerComponentId()

Retrieves the component ID that is the default message handler (for global messages).

Return:

String - the ID of the component that handles the global messages

getDnDContext

public Object getDnDContext()

Returns the current Drag and Drop context, associated with the page, or null if no Drag and Drop context is available.

Return:

Object

getEditableSubtree

public AdfUIComponent getEditableSubtree()

Returns the root of the component subtree that inline-editing is allowed on

Return:

AdfUIComponent - null

getEditedComponent

public AdfUIComponent getEditedComponent()

Returns the current component being edited.

Return:

AdfUIComponent - null

See also:

setEditedComponent(AdfUIComponent, Event)

getFailedConnectionText

public Object getFailedConnectionText()

Gets the text to display in an alert if the XMLHttpRequest fails.

Return:

Object

getLocaleContext

public Object getLocaleContext()

Retrieves the locale context associated with this AdfPage. Provides utilities such as bi-directional management and other i18n support.

Return:

Object

getLookAndFeel

public Object getLookAndFeel()

Returns the LookAndFeel that this page is displaying

Return:

Object

getMessageHandlerSlaveComponentId

public String getMessageHandlerSlaveComponentId()

Retrieves the component ID that is the slave to the default message handler (provides configuration attributes that the default handler can consume).

Return:

String - the ID of the component that provides attributes to the messages handler

getMessages

public Array getMessages(Object componentId)

Get FacesMessage objects associated with a particular component. If componentId is null then the system-wide messages will be returned.

Parameters:

componentId

Return:

Array - an array of FacesMessages for the particular component or undefinied if there are no messages.

getPageProperty

public Object getPageProperty(Object propertyName)

Gets the value of a page property. These properties are scoped to the page for the application's use. For almost all uses, this api should be use in preference to using native host objects as the relationship between and lifetimes of AdfPages and native host objects such as a browser's DOM window object aren't guaranteed.

Parameters:

propertyName

Return:

Object - The value of this property or undefined if this property isn't set

See also:

setPageProperty(Object, Object)

getPhase

public Object getPhase()

Returns the current phase of the AdfPage lifecycle. Either

1. AdfPage.CREATE_VIEW_PHASE when initially creating the client view
2. AdfPage.DELIVER_EVENTS_PHASE during event devlivery
3. AdfPage.WAITING_FOR_USER_INPUT_PHASE when waiting for user interaction

Return:

Object - the current phase

getResourceURL

public Object getResourceURL(Object path)

Returns the resource URL for the given path. Note: Resource paths starting with "/" are relative to the base resource url, resource paths starting with "//" are absolute and all other resource paths are not changed.

Parameters:

path

Return:

Object

getResponseIdentifier

public Object getResponseIdentifier()

Returns an identifier for the previous response if one is available. Depending on how the system is configured, this may return null or an identifier that doesn't exactly match the identifier used by the middle tier.

Return:

Object - An identifier for the previous response, if available

getRootClientId

public String getRootClientId()

Returns the value of the rootClientId, if set

Return:

String - value of the page's root client id

getSelectedEditingComponents

public Array<AdfUIComponent> getSelectedEditingComponents()

Returns the array of AdfUIComponents currently selected for inline editing, or null if no AdfUIComponents are selected.

Return:

Array<AdfUIComponent> - null

See also:

setSelectedEditingComponents(Array<AdfUIComponent>)

getEditableSubtree()

setEditableSubtree(AdfUIComponent)

getSessionIdentifier

public Object getSessionIdentifier()

Returns an identifier for the current middle-tier session if one is available. Depending on how the system is configured, this may return null or an identifier that doesn't exactly match the identifier used by the middle tier.

Return:

Object - An identifier for this user session, if available

getTwoDigitYearStart

public Object getTwoDigitYearStart()

Returns the year offset for parsing years with only two digits. while converting strings to Date object.

Return:

Object

getTzOffsetMinutes

public Object getTzOffsetMinutes()

get the tzOffset in minutes for the current date on the server. This is needed to show the timeZone set on the server, and not the time zone on the browser.

Return:

Object

hasMessages

public Boolean hasMessages(String componentId)

Returns true if this particular component has messages or false if it does not.

Parameters:

componentId

-

a componentId or null for global messages

Return:

Boolean - true if messages are present and false if not

Init

protected Object Init(Object lookAndFeel)

Initializes the instance. Subclasses of AdfObject must call their superclass' Init

Parameters:

lookAndFeel

Return:

Object

Overrides:

AdfObject.Init()

isAnimationEnabled

public Boolean isAnimationEnabled()

Tests if animation is enabled for the page.

Return:

Boolean - true if animationis enabled, false if not.

isPortlet

public Boolean isPortlet()

Returns whether or not this Page is in a Portlet context based on an internal flag.

Return:

Boolean - true if we are within a portlet context

isScreenReaderMode

public Boolean isScreenReaderMode()

Tests whether the page is running in screen reader mode.

Return:

Boolean - true if running in screen reader mode, false if not.

isSynchronizedWithServer

public Boolean isSynchronizedWithServer()

The logic for checking for completion of a full page postback has been combining with the logic to check for a partial page postback. The following conditions indicate the page has completed a request to the server:

1. Make sure we are not in the critical section of redistributing native events to component events.
2. Checks the pre-server queue (initial queue) to make sure it is empty. In some cases, client only events queue events that propagates to the server.
3. Make sure that the data transfer server is in a ready state and that we are not waiting on a data streaming request that would occur on the initial page load of a full submit or during ppr navigation.
4. Checking to see that the page was fully loaded. This check only applies to a full page postback when it is called from isPageFullyLoaded. For a pure PPR request, this flag will be set during the initial page load. Full page postback also toggle off this flag to indicate we are waiting on a new document.
5. Checking to make sure that our event queues are empty and that all pending requests have been processed including the active data service channel.
6. Check to see if we are actively processing the event queue. The _inDeliverQueuedServerEvents flag indicates when we are folding together a PPR request or processing the response.
7. If a full-page postback that expects a response has been issued, make sure that we are not waiting for the document to unload.

Return:

Boolean - null true if the client has no outstanding state to synchronize with the server. This function is used by automated testing tools in order to wait until the client has been appropriately updated.

launchHelpWindow

public Object launchHelpWindow(String url)

Method that will launch the help window given a url.

Parameters:

url

-

to display in the help window

Return:

Object

localNavigate

public Object localNavigate(String uri)

Issue a GET request for a local page and perform a page transition. This method is supported only for pages within the same web application. If PPR Navigation is enabled, this method loads the page via PPR.

Parameters:

uri

-

for the new page

Return:

Object

queueEventToServer

public Object queueEventToServer(Object event)

Parameters:

event

Return:

Object

registerLoadingComponent

public Object registerLoadingComponent(AdfUIComponent component)

Registers a component that isn't fully loaded on creation with the framework. This allows automated testing tools to wait until the component is ready before interacting with it. AdfUIComponent instances may only be registered once.

Parameters:

component

-

AdfUIComponent instance to register.

Return:

Object

See also:

unregisterLoadingComponent(AdfUIComponent)

registerResizeNotifyComponent

public Object registerResizeNotifyComponent(Object component)

Register a component to recieve resize notification when the browser window is resized. The component's resizeNotify() method will be called when the resize occurs. Application developers should not need to call this method explicitly. Components which are interested in resize events will automatically register themselves.

Parameters:

component

Return:

Object

removeBusyStateListener

public Object removeBusyStateListener(Object instance,
                                      Function listener)

Removes a listener so that it will no longer be invoked whenever there is a busy state event. Application developers should not need to call this method explicitly. Components which are interested in busy state events will automatically unregister themselves, typically in their ComponentRemoved peer implementation.

Parameters:

instance	-	the object registered to be used as 'this' when invoking the listener
listener	-	the previously-registered listener to no longer invoke when there is a busy state event

Return:

Object

See also:

addBusyStateListener(Object, Function)

removeChangedComponent

public Object removeChangedComponent(Object component)

Removes a component from the list of components with attribute changes needing to be synched to the server

Parameters:

component

Return:

Object

removePropertyChangeListener

public Object removePropertyChangeListener(Object instance,
                                           Function listener)

Removes a PropertyChangeListener with the specified instance and listener function

Parameters:

instance	-	Object used as "this" when calling the listener
listener	-	Function to call when an AdfDhtmlPage property changes

Return:

Object

setBaseResourceUrl

public Object setBaseResourceUrl(Object baseResourceUrl)

Sets the base URL for resources.

Parameters:

baseResourceUrl

Return:

Object

setDefaultMessageHandlerComponentId

public Object setDefaultMessageHandlerComponentId(String id,
                                                  String slaveId)

Sets the component id for global messages. Whenever page-level messages are added to the queue the component corresponding to this component id will be notified.

Parameters:

id	-	the ID of the component that handles the global messages
slaveId	-	the ID of the component that serves attributes to the handler

Return:

Object

setEditableSubtree

public Object setEditableSubtree(AdfUIComponent newEditableSubtree)

Sets the root of the component subtree that inline-editing is allowed on. When the inline editing root is changed, all selected elements no longer included in the subtree will be removed from the selection.

Parameters:

newEditableSubtree

Return:

Object

See also:

getSelectedEditingComponents()

setSelectedEditingComponents(Array<AdfUIComponent>)

setEditableSubtreeFilter

public Object setEditableSubtreeFilter(Function callback,
                                       Object context)

Sets the filter applied to all components in the editable subtree. The subtree component and each of its component children will be passed to the callback function, if any, to determine whether the component is

• AdfRichInlineEditor.FILTER_UNSELECTABLE
• AdfRichInlineEditor.FILTER_SELECTABLE
• AdfRichInlineEditor.FILTER_EDITABLE

If no callback is provided, all components are considered editable.

Parameters:

callback	-	Callback function of the form int(component), returning the AdfRichInlineEditor.FILTER_ constant determining the editability of the component.
context

Return:

Object

See also:

setEditableSubtree(AdfUIComponent)

setEditedComponent

public Object setEditedComponent(AdfUIComponent newEditedComponent,
                                 Event event)

Attempts to start editing on the specified component with an option DOM event as the editing trigger. Calling this method has the following effects:

1. If component is not part of the editable subtree, nothing will happen
2. If the component is not part of the current selection, it will be added to the selection
3. If the component allows inline editing, the inline editor for the property of the component indicated by the DOM event will be initiated.

Parameters:

newEditedComponent	-	Component to start editing
event	-	DOM Event used to start editing on this component

Return:

Object

See also:

getEditableSubtree()

setEditableSubtree(AdfUIComponent)

setFailedConnectionText

public Object setFailedConnectionText(Object text)

Sets the text to display in an alert if the XMLHttpRequest data transfer fails.

Parameters:

text

Return:

Object

setHelpWindowName

public Object setHelpWindowName(String windowName)

Method that will set the help window name. This is used when the help icon is pressed to determine the window name so that if there is already a help window that window is used (and a new one isn't created).

Parameters:

windowName

-

The name of the help window

Return:

Object

setPageProperty

public Object setPageProperty(Object propertyName,
                              Object propertyValue)

Sets the value of a page property. These properties are scoped to the page for the application's use. For almost all uses, this api should be use in preference to using native host objects as the relationship between and lifetimes of AdfPages and native host objects such as a browser's DOM window object aren't guaranteed.

Parameters:

propertyName
propertyValue

Return:

Object

See also:

getPageProperty(Object)

SetPhase

protected Object SetPhase(Object phase)

Called by subclasses to change the current lifecycle phase

Parameters:

phase

Return:

Object

setSelectedEditingComponents

public Object setSelectedEditingComponents(Array<AdfUIComponent> newSelection)

Sets the array of AdfUIComponents for inline selection. Only components within the editable subtree will actually be selected. When the selection is changed, editing will be stopped on the current edited component if it is no longer part of the selection.

Parameters:

newSelection

Return:

Object

See also:

getEditableSubtree()

setEditableSubtree(AdfUIComponent)

getEditedComponent()

setEditedComponent(AdfUIComponent, Event)

setTwoDigitYearStart

public Object setTwoDigitYearStart(Object twoDigitYearStart)

Sets the year offset for parsing years with only two digits.

Parameters:

twoDigitYearStart

Return:

Object

setTzOffsetMinutes

public Object setTzOffsetMinutes(Object tzOffsetMinutes)

set the tzOffset in minutes for the current date on the server.

Parameters:

tzOffsetMinutes

Return:

Object

shouldTracePPRRequestId

public Object shouldTracePPRRequestId()

Checks whether we should trace request id on PPR request or not. Default is false. It is controlled by parameter oracle.adf.view.rich.REQUEST_ID_TRACING.

Return:

Object - a flag indicating whether or not to trace request id on PPR request.

showMessages

public Object showMessages(String componentId)

Displays the messages to the user.

Parameters:

componentId

-

a specific component client ID whose message should be shown or null if all messages should be shown

Return:

Object

showPageProcessingIndicator

public Object showPageProcessingIndicator(Object show)

Parameters:

show

Return:

Object

unregisterLoadingComponent

public Object unregisterLoadingComponent(AdfUIComponent component)

Unregisters a component registered with registerLoadingComponent. Components should be unregistered when fully loaded and must be unregistered when removed. For coding convenience, it is not an error to unregister a component that was never registered.

Parameters:

component

-

AdfUIComponent instance to unregister.

Return:

Object

See also:

registerLoadingComponent(AdfUIComponent)

unregisterResizeNotifyComponent

public Object unregisterResizeNotifyComponent(Object component)

Unregister a component so that it will no longer receive resize notifications. Application developers should not need to call this method explicitly. Components which are interested in resize events will automatically unregister themselves as necessary.

Parameters:

component

Return:

Object