Types of Inline Popups

There are several types of inline popups that provide different user experiences. The following matrix compares the properties of the inline popups.

<af:popup id="inlineSelector">
  Hello World!
</af:popup>
                         

<af:popup id="noteWindow">
  <af:noteWindow>
    Hello World!
  </af:noteWindow>
</af:popup>
                         

<af:popup id="dialog">
  <af:dialog title="test">
    <af:inputText text="Say" value="Hello World!"/>
  </af:dialog>
</af:popup>

<af:popup id="panelWindow">
  <af:panelWindow title="test">
    <af:inputText text="Say" value="Hello World!"/>
  </af:panelWindow>
</af:popup>
                         

<af:popup id="popupMenu">
  <af:menu>
    <af:commandMenuItem text="Item 1"/>
    <af:commandMenuItem text="Item 2"/>
    <af:commandMenuItem text="Item 3"/>  
  </af:menu>
</af:popup>
                         

Delivering the Content to the Client

The popup component is a container that contains a page fragment. The page fragment is hidden by default and requires a client action or event in order to be shown. The popup conditionally determines when markup is sent to the client by its contentDelivery property. The default content delivery is lazy. This means the content of the popup is not delivered to the client until shown the first time.

• lazy -- the default strategy described above. The content isn't loaded until you show the popup once, but then is cached.

• immediate -- load the content onto the page immediately, so it displays as rapidly as possible. Use this for popups that are certain to be used by all users every time they use this page.

• lazyUncached -- the content isn't loaded until you show the popup, and then is re-fetched every subsequent time you show the popup. Use this strategy if the popup shows data that can become stale.

The popup's content delivery options are often misinterpreted. The content delivery defines when the markup is delivered to the client browser. The popup component doesn't try to intelligently manage a sub view of components like the af:region component. It assumes the sub component tree that represents its content has already been built.

Controlling Aspects of Auto-dismissal

By default, an inline popup will auto-dismiss when the markup that defines it has been replaced. This behavior is controlled by the autoCancel property. There are several scenarios that might cause implicit auto-dismissal of inline popups.

• Uses of full submit command components. Full submit commands cause the entire document to be reloaded versus a partial submit command that results in partial content delivery.
• The popup component or parent of the popup component has been added as a partial target.
• The popup is contained within a component that toggles disclosed. A af:showDetailItem in a af:panelTabbed is an example.
• An inline popup is shown and a failover occurs. During a failover, the entire document is replaced.

For these scenarios, if the autoCancel property is set to enabled, the popup in question will not restore visibility. It will implicitly auto-dismiss.

However, if the autoCancel property is disabled, the popup will restore visibility instead of auto-dismissing. The popup must be explicitly dismissed by one of the expected/assumed dismissal behaviors for the type of popup or programmatically handled. See the next section on displaying and hiding popups.

Displaying/Hiding Popups

The inline popup is client centric meaning that its states and behaviors are based on client events and actions. The client popup component has operations for showing and dismissing the popup. Beside JavaScript extension points, there are declarative and assumed behaviors.

<af:outputText id="text" value="hover over this text with the mouse to launch a note window">
  <af:showPopupBehavior popupId="noteWindow" triggerType="mouseHover" alignId="text"/> 
</af:outputText>
                 

...
...                    
<af:resource type="javascript">
  function showPopup(event) 
  {
    event.cancel();
    var source = event.getSource();
    var popupId = "popup";
    var popup = AdfPage.PAGE.findComponentByAbsoluteId(popupId);
         
    if (!popup.isPopupVisible())
    {   
      var hints = {};
      hints[AdfRichPopup.HINT_LAUNCH_ID] = source.getClientId();
      hints[AdfRichPopup.HINT_ALIGN_ID] = source.getClientId(); 
      hints[AdfRichPopup.HINT_ALIGN] = AdfRichPopup.ALIGN_AFTER_START;
           
      popup.show(hints);
    }
  }

  function hidePopup(event) 
  {
    event.cancel();
    var source = event.getSource();
    var popupId = source.getProperty("popupId");
    var isCanceled = source.getProperty("isCanceled");
                 
    var popup = AdfPage.PAGE.findComponentByAbsoluteId(popupId);
         
    if (popup.isPopupVisible())
    {                 
      if (isCanceled)
        popup.cancel();
      else
        popup.hide();
    }
  }
</af:resource>
...
...
<af:form&gt;
 <af:popup id="popup">
    Hello World!
 </af:popup>
 
 <af:outputText value="Show Popup">
   <af:clientListener method="showPopup" type="mouseOver"/>
 </af:outputText>
 <br/><br/><br/><br/>
 <af:outputText value="Hide Popup">
  <af:clientListener method="hidePopup" type="mouseOver"/>
  <af:clientAttribute name="popupId" value="popup"/>
 </af:outputText>
 <af:outputText value="Cancel Popup">
  <af:clientListener method="hidePopup" type="mouseOver"/>
  <af:clientAttribute name="popupId" value="popup"/>
  <af:clientAttribute name="isCanceled" value="true"/>
 </af:outputText>

</af:form>
...
...

...
...                       
<af:form>
   <af:popup id="popup" binding="#{testBean.popup}">
     <af:panelWindow title="Test">
       <af:button text="Hide" partialSubmit="true" actionListener="#{testBean.hidePopupActionListener}"/>
       <af:button text="Cancel" partialSubmit="true" actionListener="#{testBean.cancelPopupActionListener}"/>
     </af:panelWindow>
   </af:popup>
   <af:button text="Show" partialSubmit="true" actionListener="#{testBean.showPopupActionListener}"/>
</af:form>
...
...
public void showPopupActionListener(ActionEvent event) 
{
  UIComponent source = (UIComponent) event.getSource();
  // get the popup component - see binding="#{testBean.popup}" in the tag source
  RichPopup popup = getPopup();
  RichPopup.PopupHints hints = new RichPopup.PopupHints();
  hints.add(RichPopup.PopupHints.HintTypes.HINT_ALIGN_ID, source)
      .add(RichPopup.PopupHints.HintTypes.HINT_LAUNCH_ID, source)
      .add(RichPopup.PopupHints.HintTypes.HINT_ALIGN, 
           RichPopup.PopupHints.AlignTypes.ALIGN_AFTER_END);
  popup.show(hints);
}
public void hidePopupActionListener(ActionEvent event) 
{
  FacesContext context = FacesContext.getCurrentInstance();
  // get the popup component - see binding="#{testBean.popup}" in the tag source
  RichPopup popup = getPopup();
  popup.hide();
}
public void cancelPopupActionListener(ActionEvent event) 
{
  FacesContext context = FacesContext.getCurrentInstance();
  // get the popup component - see binding="#{testBean.popup}" in the tag source
  RichPopup popup = getPopup();
  popup.cancel();
}

Client-only Popup Events

Besides the operations, the inline popup has several client events. Most of the client events do not have corresponding faces events or server-side listeners. However, the popupCanceled event does provide a corresponding server-side event. These events can be exploited using the clientListener tag and custom JavaScript functions.

1. popupOpening: A client only event that can be canceled. If this event is canceled in a client-side listener, the popup will not be shown.

2. popupOpened: This event is fired after the popup becomes visible. This event could be used to create custom rules for overriding default focus within the popup.

3. popupCanceled: The canceled event is fired when a popup is unexpectedly dismissed by auto-dismissal or by explicitly invoking the popup client component's cancel method.

4. popupClosed: The closed event is a client only event fired when the popup is hidden.

Not all inline popup's provide server-side counter parts for all client events. However, custom client event listeners can invoke JavaScript that raises a CustomEvent that is handled by a af:serverListener.

...
...
<af:resource type="javascript">
  function popupClosedListener(event) 
  {
    var source = event.getSource();
    var popupId = source.getClientId();
         
    var params = {};
    params['popupId'] = popupId;
    var type = "serverPopupClosed";
    var immediate = true;

    AdfCustomEvent.queue(source, type, params, immediate);
  }
</af:resource>
<af:form>
  <af:popup >
    <af:dialog title="Test">
      <f:verbatim>Hello World</f:verbatim>
    </af:dialog>
    <af:clientListener method="popupClosedListener" type="popupClosed"/>
    <af:serverListener type="serverPopupClosed" method="#{testBean.serverPopupClosedListener}"/>
  </af:popup>

  <af:button text="show">
    <af:showPopupBehavior popupId="popup"/>
  </af:button>        
</af:form>
...
...
public void serverPopupClosedListener(ClientEvent event)
{
  String popupId = (String) event.getParameters().get("popupId");
  System.out.print("Popup Closed: " + popupId);
}                 

Server-side Popup Events

The PopupFetchEvent is one of two server-side popup events but doesn't have a corresponding client event. The popup fetch event is invoked during content delivery. This means that the event will only queue for popups that have a contentDelivery type of lazy or lazyUncached. Another caveat is that the event will only work when the launch id is set. This is automatically handled by the af:showPopupBehavior but must be provided as a popup hint if programmatically shown.

The popup has two properties and a listener that work with this PopupFetchEvent event. The eventContext property is used to establish the currency that the popupFetchListener is invoked in. This is a similar concept seen with stamped components such as the af:table component. In fact, this property allows creating a shared popup instance launched from a component within a af:table using the af:showPopupBehavior tag. The launcher component is placed in context and an instance made available using the popup's launcherVar property.

Besides the popupFetchListener, the af:setPropertyListener can be used to move a value from one place to another when the PopupFetchEvent is queued.

<af:popup id="noteWindow" contentDelivery="lazyUncached" eventContext="launcher" launcerVar="source">
  <af:noteWindow>
    <af:outputText value="#{testBean.fullName}"/>
  </af:noteWindow>
  <af:setPropertyListener from="#{source.attributes.fullName}" to="#{testBean.fullName}" type="popupFetch"/>
</af:popup>
<af:table var="person" value="#{testBean.people}">
  <af:column id="firstName">
    <f:facet name="header">
      <af:outputText value="First Name"/>
    </f:facet>
    <af:link text="#{person.firstName}">
      <af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/>
      <af:clientAttribute name="fullName" value="#{person.fullName}"/>
    </af:link>
  </af:column>
</af:table>
                

The PopupCanceledEvent is the second type of server-side event. Unlike the PopupFetchEvent, it has a corresponding client event. The canceled event is fired when the popup is unexpectedly closed by auto-dismissal or by calling the cancel method on the client component. Pressing the escape key will also cancel the popup.

The af:dialog and af:panelWindow extend this notion of unexpected dismissal to the cancel button and close icon. For these components, selecting the cancel button (af:dialog only) or close icon will raise the canceled event.

The PopupCanceledEvent event has optimized event delivery meaning that it will not propagate to the server unless there are server listeners registered for this event. The canceled event is immediate but it will prevent processing of the reset of the lifecycle on the popup's children whereby ignoring any submitted values and bypassing validation. This event is also flagged as discrete. Discrete events are sent to the server isolated in a single request. They are never combined with multiple events in a single server request.

<af:popup contentDelivery="lazyUncached" eventContext="launcher"
          launcherVar="source" id="popupRegion1" 
          popupCanceledListener="#{pageFlowScope.PopupDynamicRegionBean.swapEmptyTaskFlow}">
  <af:setPropertyListener from="#{source.attributes.employee}"
                          type="popupFetch" to="#{pageFlowScope.employeeId}"/>
  <af:setPropertyListener from="#{pageFlowScope.PopupDynamicRegionBean.popupTaskFlowId}"
                          to="#{pageFlowScope.PopupDynamicRegionBean.dynamicTaskFlowId}"
                          type="popupFetch"/>
  <af:panelWindow title="Employee Popup" id="window">
    <af:region value="#{bindings.dynamicRegion1.regionModel}"
                       id="dynam1"
                       regionNavigationListener="#{pageFlowScope.PopupDynamicRegionBean.navigationListener}"/>
   </af:panelWindow>
</af:popup>
...
...
<af:column>
  <af:button text="Update" partialSubmit="true"
             clientComponent="true" id="updateEmployee">
    <af:clientAttribute name="employee" value="#{row.Empno}"/>
    <af:showPopupBehavior popupId="::popupRegion1"/>
  </af:button>
</af:column>
...
...
public void swapEmptyTaskFlow(PopupCanceledEvent event) 
{
  setDynamicTaskFlowId("");
}