This document explains how to install and use yFiles AJAX.
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 |
The yFiles AJAX distribution comes with the yFiles AJAX Java server library and the yFiles for Java library. This allows creating yFiles AJAX applications which have access to powerful automatic layout algorithms and to the GraphML (de)serialization support offered by the yFiles libraries.
Using the yFiles AJAX server libraries requires:y.jar
) contained in a yFiles AJAX
evaluation package is only valid for the evaluation period. When replacing an evaluation license with a full version license,
the y.jar
also has to be replaced with the jar
contained in the full version distribution.
Licenses for third party software included in this distribution of yFiles AJAX:
The yFiles SVG extension package (ySVG) uses the freely available SVG toolkit Batik 1.7. The Apache Software License applies to Batik.
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
servlet-api.jar
to the lib/java
folder of the yFiles AJAX distribution, orservlet-api.jar
using the -Dservlet.api.dir
parameter.
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.
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.
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.
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.
demos/web-content/*
lib/javascript
lib/resources
yfiles-ajax-license.xml
) is copied to the WEB-INF
folder of the web application,
demos/src
are copied to the
WEB-INF/classes
folder of the web application and
yfiles-ajax.jar
and y.jar
that are located in lib/java
folder are copied to the WEB-INF/lib
folder of the web application.
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 |
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.
Configure the Dynamic Web Project:
Configure the Java source path
demos/src
" as the Java source directory.demos/src-jee6
" as an additional Java source directory.Configure the Web Module:
Add the yFiles AJAX, yFiles for Java and ySVG libraries to the build path:
yfiles-ajax.jar
,
y.jar
, ysvg.jar
and batik.jar
from the lib/java
subdirectory.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:
lib/resources
folder.lib/javascript
folder.
yfiles-ajax.jar
,
y.jar
, ysvg.jar
and batik.jar
that have been added to the build path in the previous step.Please verify that the deployment assembly mappings exactly match the configuration shown in the screenshot.
Create a new server configuration:
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
. registerLicense
call needs to be
executed before any servlet requests are handled by the BaseServlet
or any derived Servlets.
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:
lib/resources
- client-side resources required by the yFiles AJAX client library.lib/javascript
- the dojo build that includes the yFiles AJAX client JavaScript library.lib/java
- contains the yFiles AJAX server library (yfiles-ajax.jar
) and the yFiles for Java library
that is used by the yFiles AJAX server (y.jar
). These libraries have to be deployed to the WEB-INF/lib
folder of your web application.lib/web.xml
- a web application deployment descriptor that provides the servlet mappings of the yFiles AJAX web application API.
The deployment descriptor has to be copied to the WEB-INF
folder of the web application. You might have to merge the yFiles AJAX servlet
mappings with any existing definitions of your web application's descriptor instead.
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.
lib/java/yfiles-ajax.jar
lib/java/y.jar
lib/javascript/dojo/yfiles-ajax.js
, lib/javascript/dojo/nls/yfiles-ajax*.js
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 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 Developer's Guide
yFiles for Java 2.10 API Documentation
yFiles for Java Demos and Sample Code
The yWorks Knowledge Base contains information about specific topics for all of our products (troubleshooting, tips and tricks, answers to frequently asked questions).
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:
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); </script> […] <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> <script> require(["yfiles/client/tiles/widget/GraphCanvas","yfiles/client/tiles/HierarchyManager"], function(GraphCanvas,HierarchyManager) { ... var hierarchy = new HierarchyManager(graph); } ); </script> […] <div data-dojo-type="yfiles/client/tiles/widget/GraphCanvas" id="canvas" data-dojo-props="tileSize:600,nodeEvents:true,edgeEvents:true,baseURL:'../incremental', path:'grouping.graphml',maxZoomForFitContent:1.0,sizeMin:50,sizeShare:66,showLoading:false"> |
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"); }); |
dijit/registry |
dojo.connect(hierarchy, "onSwitchToSubgraph", this, "updateParentInfo"); |
require(["dojo/on"], function(on){ on(hierarchy, "onSwitchToSubgraph", lang.hitch(this, "updateParentInfo")); }); |
Events with Dojo |
var self = this; dojo.xhrPost({ 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" }); |
require(["dojo/request/xhr"], function(xhr){ var self = this; xhr.post(this._canvas.baseURL + '/TreeCollapser/toggleNode',{ data: { path : 'CollapsibleTree', id : nodeId, layout : this._layouter }, handleAs: 'json'} ).then(function(result, ioargs) { self._refresh(result.bounds, result.shift); } ); } |
dojo/request/xhr |
The following changes have to be made when migrating from yFiles AJAX 1.4 to yFiles AJAX 2.0.
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.
1.4 | // canvas is an instance of yfiles.client.tiles.widget.GraphCanvas canvas.refresh(null, null, false); canvas.fitContent(); |
2.0 | // canvas is an instance of yfiles.client.tiles.widget.GraphCanvas canvas.refresh(null, null, false, function() { canvas.fitContent(); }); |
We appreciate your feedback. Please send your remarks, questions or bug reports to yfilesajax@yworks.com.
Copyright © 2006-2013 yWorks GmbH. All Rights Reserved.