This document explains how to install and use yFiles AJAX.

yFiles AJAX Readme

Contents of this file

Contents of this Distribution

README.html This file
SOFTWARE_LICENSE_AGREEMENT.html Software License Agreement
CHANGES_yFilesAJAX.html Changes between different yFiles AJAX versions
CHANGES_yFilesJAVA.html Changes between different yFiles for Java versions
3rdPartyLicenses/ Licenses for third party software included in this distribution of yFiles AJAX. See Third Party License Terms
lib Source code and resources for yFiles AJAX
  java Java jar files for the yFiles AJAX server functionality
javascript A Dojo build containing the yFiles AJAX client-side components
resources Resources used by the yFiles AJAX client-side components
web.xml A deployment descriptor for the yFiles AJAX server-side components
demos Source code and resources for the yFiles AJAX demo applications
  src Java sources for the server functionality of the yFiles AJAX demo applications
src-jee6 Additional Java demo sources that use functionality of the the Servlet Specification 3.0 API
web-content Client-side content of the yFiles AJAX demo applications
build.xml Ant script for recompiling the demo applications and for creating the web application .war file
doc yFiles AJAX documentation
  index.html Index of the available yFiles AJAX documentation
client-api yFiles AJAX JavaScript API documentation
devguide yFiles AJAX Developer's Guide
server-api API documentation of the yFiles AJAX server library
tutorials yFiles AJAX tutorials
web-api Documentation of the yFiles AJAX web application interface
yfiles-for-java Documentation, demo sources and tutorials of the bundled yFiles for Java distribution

Prerequisites for the Installation



Third Party License Terms

Licenses for third party software included in this distribution of yFiles AJAX:

Third party software used by the yFiles AJAX and yFiles for Java libraries

Third party software used by ySVG

The yFiles SVG extension package (ySVG) uses the freely available SVG toolkit Batik 1.7. The Apache Software License applies to Batik.

yGuard (Java bytecode obfuscator) uses the following third party software

Running the yFiles AJAX Demo Web Application

Using Ant

The web application archive (war) can be created conveniently using the Ant build script included in this distribution (demos/build.xml).

To compile the Java sources that are part of the yFiles AJAX demo applications, a J2EE implementation library (servlet-api.jar) is required. The J2EE implementation is specific for the servlet container and can usually be found in the servlet container's lib folder.

In order to make the servlet api implementation available for compilation, either

To create the demo web application, a valid yFiles AJAX license (yfiles-ajax-license.xml) has to be available in the root folder of the yFiles AJAX distribution.

To create the web application using the Ant build script (demos/build.xml), just invoke the webapp target.

ant webapp

If the servlet-api.jar conforms to the J2EE Servlet Specification 3.0 (or higher), you can enable the jee6 property, in order to enable demo features that are not available in older Servlet Specifications:

ant -Djee6=true webapp

To display additional details about the available properties of the build script, use the help target.

The Ant script will create the yFiles AJAX web application archive (yfiles-ajax.war) in the root directory of the distribution. The war file can then be deployed to your servlet container and launched.

Using an IDE

This section explains the directory layout and configuration for an IDE project that allows to run and debug the yFiles AJAX demos as a web application.

Note that there are specific step-by-step guides available for Eclipse and Netbeans.

The yFiles AJAX demos can be deployed as a web application which consists of client-side content (HTML, JavaScript, images, cascading style sheets), as well as server-side Java code and libraries. The directory layout of the yFiles AJAX distribution strives for a clear separation of the core library and the demo resources. The resulting structure is not suitable for a deployed web application. Current IDEs support to restructure the content of a web application during deployment. You can either use this feature (i.e. configure the deployment assembly in the case of Eclipse) or you can create a new directory structure and copy the bits and pieces from the distribution to suitable locations in the new structure. In both cases the same mapping applies.

yFiles AJAX Web Application Structure

As illustrated by the color mappings in the image above, the following directories of the yFiles AJAX distribution contain client-side content that has to be copied to a different location in your web application.

In addition,

The following table summarizes the mapping from the directory layout of the yFiles AJAX distribution to the directory layout of a deployed web application for the yFiles AJAX demos.

yFiles AJAX Distribution

Web Application

/demos/web-content/ /
/demos/src (Java source code)
/demos/src-jee6 (Servlet Spec 3 Java sources)
/WEB-INF/classes (class files for the Java sources)
/lib/java /WEB-INF/lib
/lib/javascript /javascript
/lib/resources /resources
/yfiles-ajax-license.xml /WEB-INF/yfiles-ajax-license.xml

Creating an Eclipse project for the yFiles AJAX demo web application

This section explains how to setup a "Dynamic Web Project" for running and debugging the yFiles AJAX demo web application in Eclipse. To configure a project in a different IDE, the previous section describes the general directory layout of a yFiles AJAX demo application project. A step-by-step guide for Netbeans is also available.

Note that this section focuses on setting up a project for debugging the server-side part of a yFiles AJAX web application. It does not cover how to set up client-side debugging in a IDE.

The guide uses the "Eclipse IDE for Java EE Developers" (Helios Service Release 1). The configuration process can be different for other Eclipse releases.

  1. Create a new "Dynamic Web Project" in Eclipse.
    Create a Dynamic Web Project
  2. Configure the Dynamic Web Project:

    1. Project-Name: yfiles-ajax.
    2. Contents: select the root folder of the yFiles AJAX distribution.
    3. Target Runtime: Configure the Servlet Container, choosing its installation directory.
    4. Hit "Next" to configure the web module.
    Configure the Dynamic Web Project
  3. Configure the Java source path

    1. Remove the default "src" entry.
    2. Enter "demos/src" as the Java source directory.
    3. If your Servlet Container supports (at least) the Java Servlet Specification 3.0, you can also add "demos/src-jee6" as an additional Java source directory.
    4. Hit "Next" (the output path can be left unchanged).
    Configure the Java source path
  4. Configure the Web Module:

    1. Context-Root: yfiles-ajax.
    2. Content Directory: demos/web-content.
    3. If the dialog asks whether a default deployment descriptor (web.xml) should be created, make sure that this option is disabled.
    4. Hit "Finish".
    Configure the web module
  5. Add the yFiles AJAX, yFiles for Java and ySVG libraries to the build path:

    1. In the project properties windows, select "Java Build Path".
    2. In the "Libraries" tab, select "Add JARs…". and select the yfiles-ajax.jar, y.jar, ysvg.jar and batik.jar from the lib/java subdirectory.
    Add Java libraries
  6. Configure the deployment assembly:

    As we have selected demos/web-content as a content folder when creating the project, the contents of this folder will already be correctly mapped to the deployment assembly. Also, the output of compiling the Java sources in demos/src will be correctly copied to WEB-INF/classes. Now, we still need to add the client-side library resources and the Java libraries that are required for running yFiles AJAX applications to the deployment assembly:

    1. In the project properties windows, select "Deployment Assembly".
    2. Click "Add…".
    3. Choose "Folder".
    4. Select the lib/resources folder.
    5. Choose "Add…", "Folder" again, and select the lib/javascript folder.
    6. Enter "resources" and "javascript" as the respective deploy paths.
    7. Now, choose "Add…", "Java Build Path Entries", and select the yfiles-ajax.jar, y.jar, ysvg.jar and batik.jar that have been added to the build path in the previous step.

    Add library resources

    Please verify that the deployment assembly mappings exactly match the configuration shown in the screenshot.

  7. Create a new server configuration:

    In the "Servers" view, create a server for running/debugging the yFiles AJAX applications.
    Create a server
  8. Choose the server type
    Choose the server type
  9. Simply add the yfiles-ajax module to the configured modules of the server.
    Add the module
  10. The yFiles AJAX license file (yfiles-ajax-license.xml) has to be located in the WEB-INF folder of the web application. Because the complete demos/web-content directory is already deployed to the web application, the license file can just be copied to demos/web-content/WEB-INF.
    As an alternative to the license file deployment, the xml license data can also be specified programmatically using the static method BaseServlet#registerLicense(String). Note that if this approach is used for providing the license information, the registerLicense call needs to be executed before any servlet requests are handled by the BaseServlet or any derived Servlets.
  11. You can now run/debug the server in Eclipse, accessing the yFiles AJAX web applications on localhost
    (e.g. http://localhost:8080/yfiles-ajax/).

Using the yFiles AJAX library

The yFiles AJAX client- and server-side libraries and resources that are required for using yFiles AJAX in a web application project can be found in the lib folder of the distribution:

To use yFiles AJAX functionality in a web application, the yFiles AJAX license file (yfiles-ajax-license.xml) has to be deployed to the WEB-INF folder of the web application. As an alternative to the license file deployment, the xml license data can also be specified programmatically. Please see the corresponding section of the developer's guide for details.

Also, the yFiles for Java library (y.jar) contained in an evaluation distribution is only valid for the evaluation period. Therefore, when a yFiles AJAX evaluation license is replaced, the y.jar also has to be replaced with the one contained in the corresponding yFiles AJAX distribution.

For details on using yFiles AJAX in a web application, please see the corresponding section of the yFiles AJAX Developer's Guide.


The yFiles AJAX distribution contains the following redistributables.

This jar file contains the server side classes for yFiles AJAX.
The yFiles for Java class library.
lib/javascript/dojo/yfiles-ajax.js, lib/javascript/dojo/nls/yfiles-ajax*.js
These are the files produced by a custom layered Dojo build for the client side functionality of yFiles AJAX.

These are the Redistributables as mentioned in Section 2 in the Software License Agreement.


The server side of yFiles AJAX is based on yFiles for Java. Moreover, yFiles for Java can be used for implementing custom server-side actions. The yFiles AJAX Developer's Guide contains an overview of the components in a web application using yFiles AJAX. It describes the client side components and how yFiles for Java is used for the server side.

yFiles AJAX

yFiles AJAX 2.1 Developer's Guide

yFiles AJAX Tutorials Documentation

yFiles AJAX Web Application Interface Documentation

yFiles AJAX 2.1 Client API Documentation

yFiles AJAX 2.1 Server API Documentation

yFiles for Java

yFiles for Java Developer's Guide

yFiles for Java 2.10 API Documentation

yFiles for Java Demos and Sample Code

yFiles for Java Tutorial

yWorks Knowledge Base

The yWorks Knowledge Base contains information about specific topics for all of our products (troubleshooting, tips and tricks, answers to frequently asked questions).

Migration Guide

Migrating from yFiles AJAX 2.0 to yFiles AJAX 2.1

With yFiles AJAX 2.1, the Dojo version was upgraded from 1.6 to 1.8.3. Since version 1.7, dojo uses a modern architecture that changed some of the most basic concepts. Although the Dojo releases are mainly backwards compatible, the yFiles AJAX demo sources and client-side library resources were already adapted to the new concepts for the most part. Also, all demo sources were adapted to HTML5 standards.

For details on the migrating process to the new Dojo architecture, we would like to recommend to articles on the Dojo website:

Migrating to AMD

The most important change with the new Dojo version is the switch to the Asynchronous Module Definition (AMD) standard. While the client-side yFiles AJAX library still comes as a single resource that need to be loaded using a <script> tag, all classes are now separate AMD modules that have to be required individually:

yFiles AJAX 2.0
<script type="text/javascript" src="../javascript/dojo/dojo.js" djConfig="parseOnLoad: true"></script>
<script type="text/javascript" src="../javascript/dojo/yfiles-ajax.js"></script>

<script type="text/javascript">
var hierarchy = new yfiles.client.tiles.HierarchyManager(graph);


<div dojoType="yfiles.client.tiles.widget.GraphCanvas" id="canvas" tileSize="600" nodeEvents="true"
           edgeEvents="true" baseUrl="../incremental" path="grouping.graphml" maxZoomForFitContent="1.0"
           sizeMin="50" sizeShare="66" showLoading="false">
yFiles AJAX 2.1
<script data-dojo-config="async: true" src="../javascript/dojo/dojo.js"></script>
<script src="../javascript/dojo/yfiles-ajax.js"></script>


   function(GraphCanvas,HierarchyManager) {
      var hierarchy = new HierarchyManager(graph);


<div data-dojo-type="yfiles/client/tiles/widget/GraphCanvas" id="canvas"

Other Dojo changes

Besides switching to AMD, some deprecated Dojo functionality has been replaced by the corresponding modern variants in the demo sources:

Deprecated Replacement Documentation
var widget = dijit.byId("myWidgetId")
require(["dijit/registry"], function(registry){
  var widget = registry.byId("myWidgetId");
  dojo.connect(hierarchy, "onSwitchToSubgraph", this, "updateParentInfo");
  require(["dojo/on"], function(on){
    on(hierarchy, "onSwitchToSubgraph", lang.hitch(this, "updateParentInfo"));
Events with Dojo
var self = this;
  url: this._canvas.baseURL + '/TreeCollapser/toggleNode',
  content : { path : 'CollapsibleTree', id : nodeId, layout : this._layouter },
  load: function(result, ioargs) {
    self._refresh(result.bounds, result.shift);
  handleAs: "json"
     var self = this; + '/TreeCollapser/toggleNode',{
       data: { path : 'CollapsibleTree', id : nodeId, layout : this._layouter },
       handleAs: 'json'}
     ).then(function(result, ioargs) {
       self._refresh(result.bounds, result.shift);

Migrating from yFiles AJAX 1.4 to yFiles AJAX 2.0

The following changes have to be made when migrating from yFiles AJAX 1.4 to yFiles AJAX 2.0.

GraphCanvas: changed behaviour of fitContent

In yFiles AJAX 1.4 the fitContent method of GraphCanvas always fetched the world bounds from the server. This behaviour has been changed so that it will now use the world bounds stored in the GraphCanvas.

In most cases this won't be a problem. If you refresh the canvas before you do a fitContent however, you'll need to change your code and provide the new callback parameter to GraphCanvas.refresh and perform the fitContent within that callback.

// canvas is an instance of yfiles.client.tiles.widget.GraphCanvas
canvas.refresh(null, null, false);
// canvas is an instance of yfiles.client.tiles.widget.GraphCanvas
canvas.refresh(null, null, false, function() {


We appreciate your feedback. Please send your remarks, questions or bug reports to

Copyright © 2006-2013 yWorks GmbH. All Rights Reserved.