ORACLE ADF - Putting It Together

Regions can be incorporated into ADF Faces popup content to support tasks requiring complex navigation through a series of pages. Another important benefit of including regions within ADF Faces popups is content reuse. These great benefits make ADF Faces popups containing regions a commonly used application development pattern.

Incorporating regions into <af:popup> content can seem similar to incorporating regions into a page, especially since an <af:popup> is actually considered part of a page. However, there are some important differences to keep in mind. Many of these differences are the result of <af:popup> behavior being mainly client-side only. When a user discloses an <af:popup>, JavaScript on the client unhides the <af:popup> created previously when the page was initially displayed. When the <af:popup> is dismissed, JavaScipt on the client simply hides the <af:popup> again. By default in both cases, no event or request is sent to the server to refresh the region content or retrieve data based on the current application state. If the <af:popup> is displayed a second time, it simply redisplays the <af:popup> content remaining from the previous disclosure.

The default behavior limitations of <af:popup> content can be overcome quite easily though. To help describe the required development approach, I've created an Embeding Regions Inside PopUp Windows pattern document available on OTN. The pattern document also provides a link to download a sample application. Just follow the simple approach to ensure region content within an <af:popup> is newly refreshed for each launch of the <af:popup>. Soon you'll be seeing regions popping up all over!

There are often cases when a page requires some type of interaction with one or more of its regions. If the interaction depends on application data being shared between the two, typically either input parameters or a <data-control-scope> of "shared" is utilized by the region. If only a small payload of application data is to be shared without restarting the region, contextual framework events can be used. But, when a page must initiate control flow navigation within one of its regions the best approach is to utilize the queueActionEventInRegion(...) method located within the oracle.adf.view.rich.component.rich.fragment.RichRegion class.

To help describe the required development approach, I've created a Initiate Control Flow Within Region From Its Parent Page pattern document available on OTN. It contains a link to download a sample application. The pattern document and sample application also describe how to use region capabilities to enable/disable buttons on the parent page based on the current state of the region. Just follow the recommended development approach. It's easy to navigate your way through it. :)

Regions and dynamic regions are initially refreshed in the ADF Lifecycle prepareModel phase when the binding container of the containing page is refreshed. On subsequent requests, the region or dynamic region will be refreshed during the ADF Lifecycle prepareRender phase depending on its taskFlow binding Refresh and RefreshCondition attributes and parameter values. Task flow definitions associated with dynamic regions are only switched during the ADF Lifecycle prepareRender phase.

For further information on ADF region taskFlow binding Refresh and RefreshCondition attributes, refer to the Fusion Developer’s Guide for ORACLE ADF section 17.1.7 “What You May Need to Know About Refreshing an ADF Region”.

There might be times when ADF Region content should not be displayed on a runtime page. Instead, the page should appear blank where the region was previously located. This is really easy to implement, but it’s not really the region that’s “empty”. It’s actually the task flow definition associated with the region that’s “empty”. But, no need to go to the trouble of creating metadata for a task flow definition containing a view activity associated with a blank page. All you need to do is just set the region or dynamic region taskFlow binding taskFlowId=””. The open-quote closed-quote convention MUST be used as defined by ADF Controller. Setting the taskFlowId to “null” or using parse commands will not work.

This same “empty” task flow approach is often used when region content is hidden and shown as part of an ADF Faces popup or panelTab. It’s important to swap an “empty” task flow into a dynamic region when it’s hidden from view. This ensures memory and recourses for the associated task flow definition are allocated and released appropriately.

For example, the following Java class can be used to swap an “empty” task flow into a dynamic region contained within an ADF Faces popup. Note two VERY IMPORTANT things about the code sample: 1) getDynamicTaskFlowId() returns a String, not a TaskFlowId (currently there is not a formalized TaskFlowId="") 2) the parse() command will NOT work for "".

public class popupDynamicRegion {

private String taskFlowId = "";
private String popupTaskFlowId = "/WEB-INF/employee-update.xml#employee-update";
private String emptyTaskFlowId = "";

public PopupDynamicRegion() {
}

public String getDynamicTaskFlowId() {
if (taskFlowId != null)
return taskFlowId;
else
return getEmptyTaskFlowId();
}

public String getEmptyTaskFlowId() {
return emptyTaskFlowId;
}

public void swapEmptyTaskFlow(ClientEvent event) {
setDynamicTaskFlowId("");

// if event delivery set to immediate="true", short-circuit to renderResponse.
// Forcing an empty taskflow releases the bindings and view port.
Boolean immediate = (Boolean)event.getParameters().get("immediate");
if (immediate != null && immediate) {
FacesContext context = FacesContext.getCurrentInstance();
context.renderResponse();
}

String popupId = (String)event.getParameters().get("popupId");
System.out.println("**** Swapping Empty Taskflow on popupClosed for " +
popupId + " ****");
}

public void setDynamicTaskFlowId(String newTaskFlowId) {
taskFlowId = newTaskFlowId;

// For HA Applications
//if (taskFlowId != null)
//{
// ControllerContext.getInstance().markScopeDirty(pageFlowScope);
//}
}
}

ADF Regions provide a great deal of application flexibility. Yet, when implementing ADF Regions that same flexibility often leaves the pensive developer wondering how best to share data or initiate navigation. Many different technologies come together to provide these types of application interactions for ADF Regions. Which one best fits what your trying to accomplish? Input parameters? Shared Data Controls? Contextual Framework Events? To help decipher through the appropriate approach to choose, I've created an ADF Region Interaction pattern document available on OTN. It describes each of the different ADF Region interaction development approaches and their recommended uses. Examples are also provided to help demonstrate each of the concepts.

So think globally and interact "regionally"! ;)