Introduction to XAP - 04/22/2008
For the past two years I've been working on the Apache Incubator XAP project. We're preparing to release version 0.5.0 at the time of my writing this, and I strongly encourage you to check it out.
XAP is a javascript framework which uses XAL (the eXtensible Application Language) to create ajax rich internet applications with minimal javascript. This is done through it's library of dynamic widgets (such as tables with selectable and expandable rows and sortable columns), and the use of the XAL language, which has XModify, databinding, and data requests to perform a lot of the kludge operations so the developer can focus on core appication functionality. Many of the widgets used are ported in from the Dojo toolkit.
Today, I'm going to show you how to set up XAP on your own server so that you can start working with XAL and create your own XAP applications.
Downloading XAP
XAP is available for download here
I'm using what will soon be version 0.5.0, which will be available on the XAP website for download soon. Working with both should be essentially the same. After unpacking the framework build, I dropped it into my root directory. You can see it here. Click on the ajax-index.html file to see the default hello world in action.
Configuring XAP
We have XAP uploaded to my server, but we want to run it on this page, which is in a different directory than the default application it gives us. Plugging XAP into a web page can take a little bit of finagling with directories, but if you have firebug you should be able to isolate issues and fix them very easily. Start by working with the code in ajax-index.html and changing things there.
Here's the code I used to set up XAP on this page, with changes marked in red:
<style type="text/css"> @import url(apache-xap-ajax-framework-0.5.0-incubator/dist/xap/css/xapDefault.css); </style> <script type="text/javascript"> djConfig = { parseWidgets: false, baseRelativePath: "apache-xap-ajax-framework-0.5.0-incubator/dist/xap/src/dojo/" }; window.onload = function(){ Xap.createEmbeddedApplications(); }; </script> <script language="JavaScript" type="text/javascript" src="apache-xap-ajax-framework-0.5.0-incubator/dist/xap/lib/xapcore.js"></script> <script language="JavaScript" type="text/javascript" src="apache-xap-ajax-framework-0.5.0-incubator/dist/src-js/DisplayUIDocument.js"></script>
If you're loading the xap application in a different directory, you also need to change the location of the plugin file in XapConfig.js
pluginFiles: [
"apache-xap-ajax-framework-0.5.0-incubator/dist/xap/src/plugin.xml"
],
And here's the DIV where I embed the XAP application
<div applicationName="SampleApplications" startPage="apache-xap-ajax-framework-0.5.0-incubator/dist/ajax-index.xal" configFilePath="apache-xap-ajax-framework-0.5.0-incubator/dist/xap/config/XapConfig.js"></div>
As you can see, all the changes involve just adding another directory level to all the paths.
Code breakdown
<style type="text/css"> @import url(apache-xap-ajax-framework-0.5.0-incubator/dist/xap/css/xapDefault.css); </style>
These lines load the XAP CSS, which controls application appearance. There's currently only one default look, and it's more professional looking than pretty, but it's clean and intutive, which is the most important part. You can use this file to mess with the appearance of your applications.
djConfig = {
parseWidgets: false,
baseRelativePath: "apache-xap-ajax-framework-0.5.0-incubator/dist/xap/src/dojo/"
};
djConfig holds the Dojo configuration parameters. Setting parseWidgets to false prevents Dojo from parsing the whole document. We disable dojo widget parsing because we want to render the widgets as XAP widgets, and just take advantage of Dojo's backend widget functions.
window.onload = function(){
Xap.createEmbeddedApplications();
};
Calling Xap.createEmbeddedApplications initializes any XAP applications you have on the page. We set it to be called when everything else has been loaded.
<script language="JavaScript" type="text/javascript" src="apache-xap-ajax-framework-0.5.0-incubator/dist/xap/lib/xapcore.js"></script>
This is the main javascript file, and will probably be the slowest part of the loading of your application. I recommend sending it to the client gzipped to reduce its load time by about 75%.
<script language="JavaScript" type="text/javascript" src="apache-xap-ajax-framework-0.5.0-incubator/dist/src-js/DisplayUIDocument.js"></script>
This file is the MCO loaded by the XAL file. MCOs let you use more complex client-side code to your application that can't be handled by a macro. This MCO has the function that gives the alert with the DOM XML when the button is clicked.
pluginFiles: [ "apache-xap-ajax-framework-0.5.0-incubator/dist/xap/src/plugin.xml" ],
XAP has a plugin framework that lets you add in your own custom widgets. This is fantastic for adding Google, Yahoo, or MSN Maps, java, flash, Youtube videos, RSS feed readers, and an infinite number of other possible widgets,
<div applicationName="SampleApplications"
startPage="apache-xap-ajax-framework-0.5.0-incubator/dist/ajax-index.xal"
configFilePath="apache-xap-ajax-framework-0.5.0-incubator/dist/xap/config/XapConfig.js"></div>
This is the div where the application is embedded. applicationName gives an index with which we can access the application. For example, with the application's name (SampleApplication) we can access the application through javascript with window.xapApplications["SampleApplication"]. Each application should have its own unique name to prevent conflicts. The startPage attribute says where to find the first XAL file. configFilePath is the path of the configuration file. Fairly self-explanatory.
Hello, World!
And there you have it. Our application is working. Click the button to see the contents of the ajax-index.xal file.
Once you have up and running the basic hello world xal file that comes in the root directory of your xap build, you can start messing around with the xal file to get a feel for the widgets and layout containers. Check out the XAL schema documentation on the Nexaweb Developer site. In a coming entry, I'll show you how to make a dynamic ajax web application with XAP.