org.apache.myfaces.trinidad.context

## Class DialogService

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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DialogService()` Create an DialogService.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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-2016 The Apache Software Foundation. All Rights Reserved.