In my earlier articles on animation, I discussed various slide, grow and flip transitions for items and containers. In this article I want to discuss a fade animation and specifically
the use of fades and auto-dismissal for informational dialogs. If you use a Mac, you may be familiar with Growl as a notification system, and
the nice way that messages that are informational just fade out after a few seconds. So in this blog entry I wanted to discuss how we could make an ADF popup behave in
the same way. This can be an effective way of communicating information to
the user without "getting in
the way" with modal alerts. This of course, has been done before, but everything I've seen previously requires something like JQuery to be in
the mix when we don't really need it to be.
The solution I've put together is nice and generic and will work with either <af:panelWindow> or <af:dialog> as a
the child of
the popup. In terms of usage it's pretty simple to use we just need to ensure that
the popup itself has clientComponent is set to true and includes
the animation JavaScript (animateFadingPopup) on a popupOpened event:
<af:popup id="pop1" clientComponent="true">
<af:panelWindow title="A Fading Message...">
...
</af:panelWindow>
<af:clientListener method="animateFadingPopup" type="popupOpened"/>
</af:popup>
The popup can be invoked in
the normal way using showPopupBehavior or JavaScript, no special code is required there.
As a further twist you can include an additional clientAttribute called preFadeDelay to define a delay before
the fade itself starts (the default is 5 seconds) . To set
the delay to just 2 seconds for example:
<af:popup ...>
...
<af:clientAttribute name="preFadeDelay" value="2"/>
<af:clientListener method="animateFadingPopup" type="popupOpened"/>
</af:popup>
The Animation Styles
As before, we have a couple of CSS Styles which define
the animation, I've put these into
the skin in my case, and, as in
the other articles, I've only defined
the transitions for WebKit browsers (Chrome, Safari) at
the moment. In this case,
the fade is timed at 5 seconds in duration.
.popupFadeReset {
opacity: 1;
}
.popupFadeAnimate {
opacity: 0;
-webkit-transition: opacity 5s ease-in-out;
}
As you can see here, we are achieving
the fade by simply setting
the CSS opacity property.
The JavaScript
The final part of
the puzzle is, of course,
the JavaScript, there are four functions, these are generic (apart from
the Style names which, if you've changed above, you'll need to reflect here):
The initial function invoked from
the popupOpened event, animateFadingPopup which starts a timer and provides
the initial delay before we start to fade
the popup.
The function that applies
the fade animation to
the popup - initiatePopupFade.
The callback function - closeFadedPopup used to
reset the style class and correctly hide
the popup so that it can be invoked again and again.
A utility function - findFadeContainer, which is responsible for locating
the correct child component of
the popup to actually apply
the style to.
Function - animateFadingPopup
This function, as stated is
the one hooked up to
the popupOpened event via a clientListener. Because of when
the code is called it does not actually matter how you launch
the popup, or if
the popup is re-used from multiple places. All usages will get
the fade behavior.
/**
* Client listener which will kick off
the animation to fade
the dialog and register
* a callback to correctly
reset the popup once
the animation is complete
* @param event
*/
function animateFadingPopup(event) {
var fadePopup = event.getSource();
var fadeCandidate = false;
//Ensure that
the popup is initially Opaque
//This handles
the situation where
the user has dismissed
//the popup whilst it was in
the process of fading
var fadeContainer = findFadeContainer(fadePopup);
if (fadeContainer != null) {
fadeCandidate = true;
fadeContainer.setStyleClass("popupFadeReset");
}
//Only continue if we can actually fade this popup
if (fadeCandidate) {
//See if a delay has been specified
var waitTimeSeconds = event.getSource().getProperty('preFadeDelay');
//Default to 5 seconds if not supplied
if (waitTimeSeconds == undefined) {
waitTimeSeconds = 5;
}
// Now call
the fade after
the specified time
var fadeFunction = function () {
initiatePopupFade(fadePopup);
};
var fadeDelayTimer = setTimeout(fadeFunction, (waitTimeSeconds * 1000));
}
}
The things to note about this function is
the initial check that we have to do to ensure that
the container is currently visible and
reset it's style to ensure that it is. This is to handle
the situation where
the popup has begun
the fade, and yet
the user has still explicitly dismissed
the popup before it's complete and in doing so has prevented
the callback function (described later) from executing. In this particular situation
the initial display of
the dialog will be (apparently) missing it's normal animation but at least it becomes visible to
the user (and most users will probably not notice this difference in any case).
You'll notice that
the style that we apply to
reset the opacity - popupFadeReset, is not applied to
the popup component itself but rather
the dialog or panelWindow
within it. More about that in
the description of
the next function findFadeContainer().
Finally, assuming that we have a suitable candidate for fading, a JavaScript timer is started using
the specified preFadeDelay wait time (or 5 seconds if that was not supplied). When this timer expires then
the main animation styleclass will be applied using the initiatePopupFade() function
Function - findFadeContainer
As a component,
the <af:popup> does not support styleClass attribute, so we can't apply
the animation style directly. Instead we have to look for
the container
within the popup which defines
the window object that can have a style attached. This is achieved by
the following code:
/**
*
The thing we actually fade will be
the only child
* of
the popup assuming that this is a dialog or window
* @param popup
* @return
the component, or null if this is not valid for fading
*/
function findFadeContainer(popup) {
var children = popup.getDescendantComponents();
var fadeContainer = children[0];
if (fadeContainer != undefined) {
var compType = fadeContainer.getComponentType();
if (compType == "oracle.adf.RichPanelWindow"
|| compType == "oracle.adf.RichDialog") {
return fadeContainer;
}
}
return null;
}
So what we do here is to grab
the first child component of
the popup and check its type. Here I decided to limit
the fade behaviour to only <af:dialog> and <af:panelWindow>. This was deliberate. If we apply
the fade to say an <af:noteWindow> you would see
the text inside
the balloon fade, but
the balloon itself would hang around until
the fade animation was over and then hide. It would of course be possible to make
the code smarter to walk up
the DOM tree to find
the correct <div> to apply
the style to in order to hide
the whole balloon, however, that means that this JavaScript would then need to have knowledge of
the generated DOM structure, something which may change from release to release, and certainly something to avoid. So, all in all, I think that this is an OK restriction and frankly it's windows and dialogs that I wanted to fade anyway, not balloons and menus. You could of course extend this technique and handle
the other types should you really want to.
One thing to note here is
the selection of
the first (children[0]) child of
the popup. It does not matter if there are non-visible children such as clientListener before
the <af:dialog> or <af:panelWindow>
within the popup, they are not included in this array, so picking
the first element in this way seems to be fine, no matter what
the underlying ordering is
within the JSF source. If you wanted a super-robust version of
the code you might want to iterate through
the children array of
the popup to check for
the right type, again it's up to you.
Function - initiatePopupFade
On to
the actual fading. This is actually very simple and at it's heart, just
the application of
the popupFadeAnimate style to
the correct component and then registering a callback to execute once
the fade is done.
/**
* Function which will kick off
the animation to fade
the dialog and register
* a callback to correctly
reset the popup once
the animation is complete
* @param popup
the popup we are animating
*/
function initiatePopupFade(popup) {
//Only continue if
the popup has not already been dismissed
if (popup.isPopupVisible()) {
//The skin styles that define
the animation
var fadeoutAnimationStyle = "popupFadeAnimate";
var fadeAnimationResetStyle = "popupFadeReset";
var fadeContainer = findFadeContainer(popup);
if (fadeContainer != null) {
var fadeContainerReal = AdfAgent.AGENT.getElementById(fadeContainer.getClientId());
//Define
the callback this will correctly
reset the popup once it's disappeared
var fadeCallbackFunction = function (event) {
closeFadedPopup(popup, fadeContainer, fadeAnimationResetStyle);
event.target.removeEventListener("webkitTransitionEnd", fadeCallbackFunction);
};
//Initiate
the fade
fadeContainer.setStyleClass(fadeoutAnimationStyle);
//Register
the callback to execute once fade is done
fadeContainerReal.addEventListener("webkitTransitionEnd", fadeCallbackFunction, false);
}
}
}
I've added some extra checks here though. First of all we only start
the whole process if
the popup is still visible. It may be that
the user has closed
the popup before
the delay timer has finished so there is no need to start animating in that case. Again we use
the findFadeContainer() function to locate
the correct component to apply
the style to, and additionally we grab
the DOM id that represents that container. This physical ID is required for
the registration of
the callback function. The closeFadedPopup() call is then registered on
the callback so as to correctly close
the now transparent (but still there) popup.
Function - closeFadedPopup
The final function just cleans things up:
/**
* Callback function to correctly cancel and
reset the style in
the popup
* @param popup id of
the popup so we can close it properly
* @param contatiner
the window / dialog
within the popup to actually style
* @param resetStyle
the syle that sets
the opacity back to solid
*/
function closeFadedPopup(popup, container, resetStyle) {
container.setStyleClass(resetStyle);
popup.cancel();
}
First of all we
reset the style to make
the popup contents opaque again and then we cancel
the popup. This will ensure that any of your user code that is waiting for a popup cancelled event will actually get
the event, additionally if you have done this as a modal window / dialog it will ensure that
the glasspane is dismissed and you can interact with
the UI again.
What's Next?
There are several ways in which this technique could be used, I've been working on a popup here, but you could apply
the same approach to in-line messages. As this code (in
the popup case) is generic it will make s pretty nice declarative component and maybe, if I get time, I'll look at constructing a formal Growl component using a combination of this technique, and active data push. Also, I'm sure
the above code can be improved a little too. Specifically things like registering a popup cancelled listener to handle
the style
reset so that we don't loose
the subtle animation that takes place when
the popup is opened in that situation where
the user has closed
the in-fade dialog.
