Integrating yFiles AJAX and ICEfaces

Introduction

There are two possibilities to integrate yFiles AJAX and ICEfaces. In the simple case, there is no interaction between yFiles AJAX widgets and facelet components. In this case you can integrate e.g. a graph canvas into a facelet as you would integrate it into any HTML page. The simple.xhtml resource attached to this article is an example for this kind of simple integration.

The rest of this article deals with the case, where interaction between a yFiles AJAX graph canvas with other components of an ICEfaces facelet should be possible.

Prerequisites

The following software was used for testing this demo.

• Java Runtime Environment (JRE) 7
• yFiles AJAX 2.0
• Eclipse 3.7.2 (Indigo) for Java EE Development
• ICEfaces 3.0.1 and the Eclipse plugins for ICEfaces
• Tomcat 7.0

Setup

1. Open Eclipse.
2. Select File >> New >> Project... from the main menu.
3. On the Select a Wizard page select the Web >> Dynamic Web Project wizard and click the Next > button.
4. On the Dynamic Web Project page choose a project name, e.g. "yFiles AJAX JSF", choose or create a Target Runtime and choose the "ICEfaces 3 Default Project Configuration". Click the Next > button.
5. On the Java page just click the Next > button.
6. On the Web Module page enter the desired context root (e.g. "yfiles-ajax-jsf") and keep the default value for the content directory (WebContent). Do not select "Generate web.xml deployment descriptor". Click the Next > button.
   
7. On the JSF Capabilities page click the small download button to the right of the JSF implementation library selection window. Choose the JSF 2 implementation from "ICEsoft Technologies". (Alternatively, you can create a user library that contains the ICEfaces javax.faces.jar). Click the Ok button. Click the Finish button.
8. Click the top level folder of the new project in the Project Explorer and select File >> Import... from the main menu.
9. On the Select page select General >> Archive File and click the Next > button.
10. Select the yfiles-ajax-icefaces.zip archive (attached to this article as a resource) as the source and select the Eclipse project folder as the target folder. Optionally, you can check "Overwrite existing resources without warning" in the Options section. Click Finish.
11. The following resources and libraries need to be copied from the yFiles AJAX distribution to the Eclipse project:
    

    Source	Target Location
    lib/javascript, lib/resources	WebContent
    demos/web-content/resources/graphs	WebContent/resources
    lib/java	WebContent/WEB-INF/lib

    Additionally, copy your yFiles AJAX license file (yfiles-ajax-license.xml) to the WebContent/WEB-INF directory of the Eclipse project.
12. In the project properties go to the Java Build Path settings page. In the Order and Export tab, click "Select All" to make sure that all required libraries are deployed to the server.
13. Create and start a Server for the Eclipse Project in the "Servers" view, and navigate to the root of the web application (e.g. http://localhost:8080/yfiles-ajax-jsf/)

Remarks

• The WebContent/WEB-INF/tags/yfiles-ajax_taglib.xml file defines a custom taglib with just one new tag <yworks:graphCanvas> for embedding a yFiles AJAX GraphCanvas widget into an ICEfaces facelet.
• The new tag is handled by the com.yworks.yfiles.jsf.components.GraphCanvas component and the com.yworks.yfiles.jsf.renderers.GraphCanvasRenderer renderer. Moreover there is a bean com.yworks.yfiles.jsf.managedbeans.GraphCanvasBean which can be used as a managed bean to enable value bindings and thus glueing other components in a facelet to the graph canvas.
• The WebContent/WEB-INF/faces-config.xml file does not contain any configuration settings, because the JSF component, renderer and bean are configured using Annotations instead (see e.g. the @FacesComponent) Annotation of the GraphCanvas class.
• The WebContent/WEB-INF/web.xml file configures the taglib. Moreover, it configures the servlets for ICEfaces and yFiles AJAX.
• The WebContent/javascript directory contains the Javascript code for the client side of yFiles AJAX.
• The WebContent/resources directory contains the graphs, which can be loaded into a yFiles AJAX graph canvas and other resources like style sheets.
• The WebContent/index.xhtml file is a facelet which uses the new <yworks:graphCanvas> tag in conjunction with a managed GraphCanvasBean.
• The GraphCanvas component supports two attributes, zoom and graphName. The zoom attribute demonstrates how events are communicated from the yFiles AJAX graph canvas widget to the surrounding facelet. If you zoom in or out with the mouse wheel, the changed zoom value is passed via partial submit to the server side. At the server side, the new zoom is set in the managed bean. In the next render phase, the changed zoom value gets to the outputText component, because it is bound to the zoom attribute of the managed bean.
• The graphName attribute demonstrates how to talk to the graph canvas widget from the facelet. There is a selectOneMenu component, which contains the names of graphs which can be displayed. The graph names are provided by the managed bean. If the user selects a graph, the new value for the graph name is transferred to the managed bean. In the next render phase, the GraphCanvasRenderer transfers the new graph name to the client side, where Javascript glue code takes care of updating the graph canvas widget.
• The <yworks:graphCanvas> tag has to be used inside an <ice:form> component with partial submit. The id attribute has to be set. All facelets containing a graph canvas and the canvas.html file have to reside in the WebContent directory.