Oracle Blog

Development Tools, Frameworks and more...

CSS Animations - The Panel Flip

In the my final (for now) discussion on CSS3 animations with ADF Faces Rich Client UI I wanted to discuss the most complex, but fundamentally useful (from a technique perspective) of the three animations shown in the introduction posting. The first two animations that I showcased were simply triggered by the browser's inherent mouse-over functionality. I didn't actually need to do anything to make the animation happen apart from assigning the correct styleClass to the panel or button. In this final animation I'm triggering the animation from code and what's more I'm actually chaining together two animations with a server side call made in the middle. To break it down here's the logical flow:

Initiate a rotation of 90 degrees --> Change the contents of the panel --> Return rotation to 0 degrees.

So the question is, how do we chain all of these actions together, given that the initial rotation will itself take a certain amount of time (2 seconds)? Well, to handle this we have to write a little bit of JavaScript that will first of all set the styleClass to provide the first 90deg animation and also register a listener function which will execute once the rotation is finished. This callback function then executes the Server code we need and then kicks off the reverse animation.

The Animations

So first of all, the two styles that define the animations. This should be fairly obvious and understandable by now:

The JSF components

In this example I'm using a switcher which is controlled by a managed bean called uiManager. This switcher will either display the panelHeader that contains the inputForm or the comments screen. Contrary to your expectation though, it's not these panels managed by the switcher that we'll actually be animating, but rather a parent of the switcher, another panelGroupLayout. So the hierarchy looks a like this:

Panel group layout that will be animated

Decorative box that will apparently rotate

Panel group layout that will be refreshed to show the change in contents

Notice that the outer panelGroupLayout id="flip" has a binding to a backing bean for the page, this is so we can get the correct clientId back for it (look back at my Visual Notifications During Long Running Transactions article for details of this technique). The inner pgl, id="refresh", also has a binding to the backing bean which we will use later in the serverListener to force a refresh on that panel and the switcher inside it.

Within each of the switcher "panels" is a button (not shown above) that will actually trigger the animation. Here's the code for the button on the A-Side:

The code for the B-Side button is identical. To break that down we have three things of interest:

A clientAttribute that is used to send the client id of the panel that we want to spin to JavaScript

A clientListener to actually wire up a JavaScript event to the button press

A serverListener which identifies the server side method that will be called half way through the animation to tell the switcher to change contents.

So let's look at each of those:

The Client Attribute

The client attribute is bound to the page backing bean where there is a simple function that asks the panel that will be "flipped" for it's client ID, in this case the flipPanel variable contains the reference to the RichPanelGroupLayout which is bound to that outer panel:

/**
* Gets the correct client component ID for this panel in the context in which the
* panel is placed. This provides a safe way of getting the client ID if the component
* is embedded in a region or similar where the computed path may change depending on the use.
* @return clientID for use in JavaScript
*/
public String getFlipClientId() {
return flipPanel.getClientId(FacesContext.getCurrentInstance());
}

The JavaScript

The clientListener on the button calls the animateFlipPanel method. This is stored in a .js file referenced using the <af:resource> tag in the metaContainer facet of the document:

function animateFlipPanel(event) {
//Get the ID of the panel to flip.
//This has been passed in via the clientAttribute
var fpId = event.getSource().getProperty('flipPanel');
//Grab a reference to this button that raised the
//event. we need this to register the callback against
var raisingComponent = event.getSource();
//First animation sends us to 90deg
var transition = "rotateOut";
flipPanel = AdfPage.PAGE.findComponentByAbsoluteId(fpId);
initiateClientFlip(raisingComponent, flipPanel, transition);
}

And here's the method that assigns the animation:

/**
* Kick off the animation - rotate the panel to 90 degrees which will make it
* disappear as it's sideways on to us.
* Then register the callback to rotate back once the animation is finished
* @param raisingComponent - the button that kicked things off
* @param flipPanel - the PGL to animate (assign style to)
* @param transition - the style to apply
*/

function initiateClientFlip(raisingComponent, flipPanel, transition) {
//Set the style to animate the rotation
flipPanel.setStyleClass(transition);
/* Setup a callback to reverse the animation once the transition is finished.
* Note that we remove the transition listener once it's executed so that
* it is not called by the flipBack transition as well
* Note also that we have to attach the listener to the underlying DOM object
*/
// Get the DOM object that represents this panelGroupLayout
var flipPanelReal = AdfAgent.AGENT.getElementById(flipPanel.getClientId());
//Define the callback
var reverseTransition = "rotateReturn"
var flipBackFunction = function (event)
{animateFlipBack(raisingComponent, flipPanel, reverseTransition);
event.target.removeEventListener("webkitTransitionEnd",flipBackFunction);};
// Add the transition listener to queue up both the animation back
// and the server side change which will apparently flip the
// contents of the panel
flipPanelReal.addEventListener("webkitTransitionEnd", flipBackFunction,false);
}

So the actual animation part of the above code is trivial, we just set the new style to kick that off. The exciting part comes in the definition of the eventListener (webkitTransitionEnd) which is set up to execute once the animation has finished. Like everything that I have covered in this short series, the code here is webkit (Chrome & Safari) specific. Similar events exist both in generic terms for the future and in specific versions for FireFox and IE.

And finally the animateFlipBack() function and a convenience method that it uses:

/**
* Once the initial animation is done this method is invoked to change the contents of the panel and then
* animate back to the starting point giving the illusion of a full 180 degree flip
* @param raisingComponent - reference to the button so we can invoke the serverListener
* @param flipPanel - pgl to animate
* @param reverseTransition - animation style
*/
function animateFlipBack(raisingComponent, flipPanel, reverseTransition) {
// Call the event on the server which will cause the switcher to
// change it's contents and issue a PPR event
raiseServerFlipEvent(raisingComponent);
//Now start the return animation
flipPanel.setStyleClass(reverseTransition);
}
/**
* Simple function to queue up the server side event on the button that
* instigated the flip. This event does not need to send a payload
* @param raisingComponent - the button
*/
function raiseServerFlipEvent(raisingComponent){
var flipEvent = new AdfCustomEvent(raisingComponent,"flipEvent",{},false);
flipEvent.queue(true);
}

The serverListener

The role of the serverListener code is to toggle the facet that the switcher is currently displaying and then force the panel containing the switcher to refresh with a PPR event:

This function as you can see is a toggle based on the current value stored in the uiManager. The UIManager itself is a session scoped bean that just holds the current side value. It is injected into this backing bean using a managed property in the managed bean definition. The function getRefreshPanel() returns a reference to the pgl that surrounds the switcher (id="refresh" in the hierarchy above).

Wrap Up

The technique that I've discussed within this article may seem a little complex but in fact it's all quite logical and can be quite easily extended and made generic. You can see how more complex animations may be achieved by stringing together a whole sequence of callbacks to execute after the previous animation has completed and how you can wire in server side calls into the mix.

About

Duncan has been around Oracle technology way too long but occasionally has interesting things to say.
He works in the Development Tools Division at Oracle, but you guessed that right? In his spare time he contributes to the Hudson CI Server Project at Eclipse

Note that comments on this blog are moderated so (1) There may be a delay before it gets published (2) I reserve the right to ignore silly questions and comment spam is not tolerated - it gets deleted so don't even bother, we all have better things to do with our lives.However, don't be put off, I want to hear what you have to say!