org.apache.myfaces.trinidad.context
Class DialogService

java.lang.Object
  extended by org.apache.myfaces.trinidad.context.DialogService

public abstract class DialogService
extends Object

The DialogService API defines a number of APIs that are needed to implement Apache Trinidad dialogs, but will only rarely be called by page authors. They are instead intended for developers of controller frameworks and component developers.


Field Summary
static String DIALOG_NAVIGATION_PREFIX_PARAM_NAME
          Configuration parameter for setting the prefix used in dialog navigation.
static String DISABLE_DIALOG_OUTCOMES_PARAM_NAME
          Configuration parameter for setting the prefix used in dialog navigation.
 
Constructor Summary
protected DialogService()
          Create an DialogService.
 
Method Summary
 javax.faces.component.UIComponent getCurrentLaunchSource()
          Returns the value last set by setCurrentLaunchSource(javax.faces.component.UIComponent).
 String getDialogNavigationPrefix()
          Returns the prefix that, when used for navigational outcomes, will trigger the dialog framework.
abstract  ReturnEvent getReturnEvent(javax.faces.component.UIComponent source)
          Creates a ReturnEvent for a component.
abstract  void launchDialog(javax.faces.component.UIViewRoot dialogRoot, Map<String,Object> dialogParameters, javax.faces.component.UIComponent source, boolean useWindow, Map<String,Object> windowProperties)
          Launches a dialog without pushing a process scope.
abstract  javax.faces.component.UIViewRoot peekView()
          Returns the UIViewRoot that is topmost on the stack, of pushed view, without popping it.
abstract  void popView(boolean navigateToPopped)
          Pop a UIViewRoot from a stack.
abstract  void pushView(javax.faces.component.UIViewRoot viewRoot)
          Push a UIViewRoot onto a stack in preparation for navigating to a subflow.
abstract  void queueLaunchEvent(javax.faces.component.UIViewRoot dialogRoot)
          Queues a LaunchEvent that will result in a dialog being started, using current launch source as the source for launching the dialogRoot parameter.
abstract  void queueReturnEvent(Object returnValue, Map<Object,Object> returnParams)
          Queues a ReturnEvent, using current launch source as the source for launching the dialogRoot parameter.
abstract  boolean returnFromDialog(Object returnValue, Map<Object,Object> returnParameters)
          Returns from a dialog without popping a process scope.
 void setCurrentLaunchSource(javax.faces.component.UIComponent component)
          A component that is delivering an ActionEvent to the default ActionListener should call this method to allow a NavigationHandler to properly launch a dialog, and should reset the value to null afterwards.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DIALOG_NAVIGATION_PREFIX_PARAM_NAME

public static final String DIALOG_NAVIGATION_PREFIX_PARAM_NAME
Configuration parameter for setting the prefix used in dialog navigation.

See Also:
Constant Field Values

DISABLE_DIALOG_OUTCOMES_PARAM_NAME

public static final String DISABLE_DIALOG_OUTCOMES_PARAM_NAME
Configuration parameter for setting the prefix used in dialog navigation. This can either be set as a WEB-INF/web.xml or programatically set as a ServletContext attribute.

See Also:
Constant Field Values
Constructor Detail

DialogService

protected DialogService()
Create an DialogService.

Method Detail

pushView

public abstract void pushView(javax.faces.component.UIViewRoot viewRoot)
Push a UIViewRoot onto a stack in preparation for navigating to a subflow.


popView

public abstract void popView(boolean navigateToPopped)
Pop a UIViewRoot from a stack. If navigateToPopped is true, this method may result in calls to FacesContext.renderResponse() or even FacesContext.responseComplete().

Parameters:
navigateToPopped - If true, navigate to the view popped of the stack with FacesContext.setViewRoot(). If false, simply drop the view.

peekView

public abstract javax.faces.component.UIViewRoot peekView()
Returns the UIViewRoot that is topmost on the stack, of pushed view, without popping it.


getReturnEvent

public abstract ReturnEvent getReturnEvent(javax.faces.component.UIComponent source)
Creates a ReturnEvent for a component. This method will generally be called from a Renderer's or UIComponent's decode() method if there is any possibility that it launched a dialog on a prior request. There is no requirement that the component directly supports ReturnListener; decode() can simply use the return value and discard the event.

This method will return null in the case where no dialog had been launched with this component as the source. If it returns a non-null event, the component or renderer should not process the request any further in decode(), but simply process the ReturnEvent, either by using its return value or queueing it for delivery.

Parameters:
source - the component that may have launched a dialog
Returns:
a ReturnEvent containing the return value from the dialog.

getCurrentLaunchSource

public javax.faces.component.UIComponent getCurrentLaunchSource()
Returns the value last set by setCurrentLaunchSource(javax.faces.component.UIComponent). =-=AEW Make this abstract?


setCurrentLaunchSource

public void setCurrentLaunchSource(javax.faces.component.UIComponent component)
A component that is delivering an ActionEvent to the default ActionListener should call this method to allow a NavigationHandler to properly launch a dialog, and should reset the value to null afterwards. =-=AEW Make this abstract?


launchDialog

public abstract void launchDialog(javax.faces.component.UIViewRoot dialogRoot,
                                  Map<String,Object> dialogParameters,
                                  javax.faces.component.UIComponent source,
                                  boolean useWindow,
                                  Map<String,Object> windowProperties)
Launches a dialog without pushing a process scope. This method should only be used by controller framework code; all others should use RequestContext.launchDialog(). The process scope must be pushed before calling this method.


returnFromDialog

public abstract boolean returnFromDialog(Object returnValue,
                                         Map<Object,Object> returnParameters)
Returns from a dialog without popping a process scope. This method should only be used by controller framework code; all others should use RequestContext.returnFromDialog(). The process scope must be popped after calling this method.

Returns:
true if pages accessing that dialog are necessarily permanently inaccessible. For example, a dialog displayed in a popup window is inacessible once the window has closed, but a dialog displayed within the same window might be reached by the back button.

queueLaunchEvent

public abstract void queueLaunchEvent(javax.faces.component.UIViewRoot dialogRoot)
Queues a LaunchEvent that will result in a dialog being started, using current launch source as the source for launching the dialogRoot parameter. The process scope must be pushed before calling this method. If getCurrentLaunchSource() returns null, a basic dialog will be started without using a window or passing any additional parameters. Developers should not call FacesContext.setViewRoot() when using this method.


queueReturnEvent

public abstract void queueReturnEvent(Object returnValue,
                                      Map<Object,Object> returnParams)
Queues a ReturnEvent, using current launch source as the source for launching the dialogRoot parameter. This method should be used by a NavigationHandler that can identify a return value from a dialog without actually launching the dialog.


getDialogNavigationPrefix

public String getDialogNavigationPrefix()
Returns the prefix that, when used for navigational outcomes, will trigger the dialog framework.



Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.