<put document name here> 1/13 Last update: 08.04.2009 10:36:18 Author: Joern Turner <joern.turner@chiba-project.org> 1 - Introduction...2 1.1 - What is XForms?...3 1.2 - What is Chiba?...3 2 - Getting started...4 2.1 - Development requirements...4 2.2 - The source tree explained...4 2.2.1 - The convex module...5 2.2.2 - The Core module...5 2.2.3 - The src module...5 2.2.4 - The tools module...5 2.2.5 - The web module...6 2.3 - Building...6 2.3.1 - Getting the sources...6 2.3.2 - Building with Ant...7 2.4 - Running Chiba Web...8 3 - building smart webapps...9 3.1 - The XForms Feature Explorer...9 3.2 - Page layout...9 3.3 - Dojo and Chiba...9 3.4 - using XSLT...9 3.5 - using Connectors...9 4 - Customizing Controls...10 5 - Extending Chiba...11 5.1 - custom XPath Functions...11 5.2 - Connectors...11 5.3 - Schema Datatypes...11 5.4 - supporting new useragents...11 5.5 - adding custom Javascript components...11 6 - Appendices...12 6.1 - Links...12 6.2 - Glossary...12
<put document name here> 2/13 1 Introduction This Guide covers Chiba versions starting with Chiba Web 3.0.0b1 Forms are an important part of the Web, and they continue to be the primary means for enabling interactive Web applications. Web applications and electronic commerce solutions have sparked the demand for better Web forms with richer interactions. XForms 1.0 is the response to this demand, and provides a new platform-independent markup language for online interaction between a person (through an XForms Processor) and another, usually remote, agent. XForms are the successor to HTML forms, and benefit from the lessons learned from HTML forms. [XForms 1.0 W3C Candidate Recommendation 12.11.02, 1.1] HTML Forms once made the Web interactive, allowing users to talk back to the servers they visit. Since then whole industries have built their profits on HTML forms as they have existed since the very beginning of HTML (Hypertext Markup Language). Whole technologies have evolved around the possibility to interact with users via the Internet. Despite the immense impact HTML Forms have had on the development of the Web, years of use have shown that they are not suitable for today's applications any more. Missing validation, data-typing and logic-components must be compensated with scripting which itself leads to bad maintainability and increasing development cost. The arrival and growing popularity of AJAX has not improved this situation. Though a huge variety of cross-browser libraries is available there's also a lack of standards about the details of data formats, typing, submission control, events, validation and calculation etc. etc. XForms is a open standard 1 that addresses all these issues bringing rich interaction, a well-defined processing model and universal data management to improve the situation. It's based on XML and therefore is easy to handle, offers self-describing datastructures and is adaptable to any application or environment. But there are things belonging to a full-flegded application that XForms intentionally leaves out: specifically layout and the concrete control or widget to the used to interact with the user. Implementations have to choose which widget set or UI markup they want to support on a specific platform. As XForms is platform- and device-independent no assumptions about specifica only available in a certain of client can be made. E.g. a voice client is not interested in layout altogether. Therefore Chiba on the one hand provides an implementation of the XForms standard but does more by providing a toolkit of controls and layout containers to build complete, dynamic web applications. It further wraps the whole thing in a nonintrusive architecture that's easy to use with any existing application and is especially well-suited to work with XML applications. This guide covers the more advanced topics like building from source, development tools, building your own controls, integration with your application and of course the various possibilities of extending the existing functionality. 1 XForms 1.0 is a W3C Recommendation since 29 October 2007. XForms 1.1 will arrive as a final Recommendation in early 2009.
<put document name here> 3/13 1.1 What is XForms? XForms is a W3C recommendation since October 2003 and the successor of HTML forms. Xforms will replace HTML forms in XHTML 2.0. It addresses the limitations of HTML forms and adds common functionality found in most form-applications like logic, validation, calculation and data-typing. Today a diversity of frameworks is used to circumvent the weaknesses of web forms. These are either proprietary and/or commercial which makes it hard to port them to another server-infrastructure and raises the overall cost-of-ownership. While serverinfrastructures like J2EE and.net have evolved and established industry standards for nearly all requirements, the form-processing part will still be hand-coded over and over again. Once XForms is adopted this picture will change drastically. Forms will be portable from one server to another, serve different clients, provide rich validation and calculation and allow complex logic without a single line of scripting code. Furthermore XForms is maintainable through clear separation of logic, data and presentation which allow a role-based development process. For further information please check the links at the end of this document, especially the book from Micah Dubinko which gives a good overview and in-detail description of the technology along with some practical tips. 1.2 What is Chiba? Chiba is a XForms framework and a toolkit that allows to quickly build state-of-theart web applications in a declarative way. It evolved around a XForms Processor implementation in Java (commonly called the 'Chiba Core'), has an AJAX layer to speak to common browsers and provides a UI toolkit for dynamic, accessible and consistent widgets. While the first versions of Chiba started up with a server-side approach and a request/response interface it quickly became apparent how powerful the combination of AJAX and server-side XForms could be for applications especially XML applications 2. Chiba Web 2.0 was the first attempt to implement that model. While interaction and dynamic behavior were good the use of native controls in the browsers also exposed some restrictions in styleability, extensibility and the integration of custom controls. Starting with 3.0 Chiba makes full use of the power of the Dojo toolkit and allows to use all its components either as 'XForms-connected' widgets or by simply adding some layout to your pages with layoutcontainers. Further a JavaScript API to the XFormsProcessor is offered for those developers that want even more control of the client UI. 2 Whatever XML applications might be. Here it's just in the sense of 'if you use XML a lot'.
<put document name here> 4/13 2 Getting started This chapter should help you get started with Chiba development. Please note that this guide assumes some familiarity with technologies like CSS, XPath, DOM, JavaScript and of course XML. If your primary goal is to write XForms you should refer to the ChibaUserGuide for details. This guide is meant for developers that like to extend Chiba classes, integrate their own JavaScript components, write connectors to read/write data from arbitrary sources or implement their own XPath functions in case the provided feature set is not sufficient. While Chiba can be used in a variety of Java architectures as a standalone component the remainder of this document will focus on the usage of Chiba Web. 2.1 Development requirements If you'd like to build the Chiba sources yourself or make use of the Chiba tools you'll need: Apache Ant 1.7 or higher installed on your system Apache Maven 2.0 or higher installed on your system (optional) Chiba uses Apache Ant as its build tool and provides all targets needed to support the development cycle as well as build source and binary distributions. The targets are described in detail in Chapter 3 Building. As an option for the Maven enthusiasts there's also support for using Maven for the same purpose but making use of Maven specific plugins and extensions. Chiba offers Ant targets to avoid double housekeeping between Ant and Maven by generating the needed pom.xml files. 2.2 Building The following step depends on which version you like to build. You can use one of the released versions, the trunk version or any other version you like. 2.2.1 Getting the sources For a build from a source archive: 1. download the wanted version from Sourceforge 2. create a directory and unpack the archive to that directory
<put document name here> 5/13 For a build of the trunk version (you'll need a SVN client installed): 1. create a fresh directory for the checkout and change to that directory 2. execute the following SVN command in a directory of your choice: svn checkout https://www.chiba-project.org/svn/chiba/trunk/chiba/ 2.2.2 Building with Ant Chiba uses Ant as primary build tool but also offers support for Maven. The Maven support is considered optional but should always be operational as the pom.xml files can be regenerated at any time from the build.properties.xml. As mentioned above each of the modules Convex, Core, Src and Web will have their own build.xml file. To execute the default target of the respective module: >ant 1. cd into the Chiba 'core' directory 2. execute the following Ant command The default target will be marked in bold text in the following reference tables. building the Core Ant target clean prepare compile distribute-sources distribute-binary distribute doc package test Description cleans the target directory prepares the target directory + copies resources compiles the Core classes creates a source archive for releases creates a binary archive for releases call the 2 targets above in one go create JavaDoc creates a jar file from Chiba Core in the target directory. A default chiba-config.xml will also be placed in the output. run all unit-tests and generate a report
<put document name here> 6/13 building Chiba Web Ant target build-dojo Description compiles all javascript into one or more layer files according to the chiba.profile.js for use with the 'dojo' useragent. These will get included by dojo.xsl while building the initial page. You can run this target explicitly while developing to have support for both useragents 'dojo' and 'dojodev' available in an exploded target directory. clean compile deploy-resources deploy-test-resources deploy-to-servletcontainer cleans the target directory compiles the Web classes and places them into target directory. copies XForms branch from src/main/xforms to the exploded webapp under target. Deploys all files needed to run with useragent 'dojodev'. copies the XForms test suites to the exploded webapp. deploys a exploded webapp along with forms to a servlet container specified by property setting webapppath found in build.properties.xml. distribute doc exploded-webapp generate-site package To use this target you have to configure the property to point to the absolute file location of your servlet container on your system! assembles tar.gz and zip archives for redistribution of the sources. This target is normally not of interest for the developer but is used to prepare Sourceforge download packages by the development team. creates JavaDoc creates an exploded webapp int the target directory. The name will be determined by Ant property web.app.name configured in build.properties.xml under /root/web/app/name. builds the Chiba homepage from the XML found under src/main/doc/site. creates a war-file from the target directory packaged with compiled Javascript sources. This target should be used for final deployment. prepare prepares the target directory + copies resources test run all unit-tests and generates a report
<put document name here> 7/13 2.3 Running Chiba Web Startup your servlet container and point your browser to: http://localhost:8080/chiba This assumes that you run your container on port 8080 and you use the default context name 'chiba'. 2.4 The source tree explained Chiba is organised in several modules 3 and the directory structure of the source tree follows the conventions layed out by the Apache Maven project. Maven users should feel right at home. Nevertheless Chiba stays completely independent of Maven. All dependency management is handled in build.properties.xml file which is found in the root of the tree. A look into this file reveals that here all java library dependencies are listed for the respective modules along with some meta-info as version numbers, modulenames and compiler options. Each module in Chiba will have its own build.xml file to compile and package the sources. See Chapter 'Building' for details. The following chapters give an overview (in alpabethical order) of the modules found in Chiba. You'll likely not use all of them at once but it may be useful to know whats there. 2.4.1 The convex module depends on: Core Convex integrates the Chiba XForms Processor in a Java Applet which may be run locally from disk or distributed by a remote server. Implemented as a faceless applet it will live in the rendered XForms page and update the HTML page via the Javascript brigde. Thus it provides an option to render pages as common HTML pages but to process the XForms logic in Java in an efficient way. Convex is a nice tool for quickly developing XForms as no server is needed for execution. Due to lack of resources there is currently no up-to-date release available! 3 'module' is used here not in the strict sense of a Maven module but as a 'main unit of organisation'.
<put document name here> 8/13 2.4.2 The Core module As the name implies this is the heart of the project. This module contains the sources, dependent libraries 4 and resources files. Further all JUnit tests are found here. 2.4.3 The src module Right in the root there's a directory src which contains global resources for all other modules such as the documentation (src/main/doc), forms (src/main/xforms) and the official XForms test suites (src/main/test) organised in further subdirectories. It is recommended to use the directory src/main/xforms to put your own forms as it will get deployed by the respective Ant targets in Chiba Web. For easier referral this directory is considered the root module and named Src for the reminded of this document. 2.4.4 The tools module The tools module contains several productivity tools that might be helpful in XForms development. Each tool is organised in its own subdirectory and will offer a local build.xml file for running. Currently you'll find our XFormsForHTML efforts here which is a XSLT transformation to turn pages following the syntax proposed by the XForms for HTML WD into full XForms syntax. Schema2XForms is a form generator that turns annotated XML Schema files into workable XForms. 2.4.5 The web module depends on: Core This module contains the probably most well-known flavor of Chiba distributed as 'Chiba Web'. It is a server-side implementation of the XForms standard and offers the full power of XForms applications via a fully AJAX-enabled user interface while still providing a fallback for non-scripted browsers. Consistent look and behavior for all supported user agents without the need for any plugin or installation are the strongpoints of this module. In the root of the web directory there is the build.xml to compile this module along with a pom.xml file for the Maven users. 4 Note for Maven user: Chiba comes with all needed libraries bundled and does not rely on Maven repositories. Special Ant targets are provided to setup a local Maven repository on your system to work with.
<put document name here> 9/13 src/main/java holds the Java classes that adapt the Core processor to the web environment. Most explanations in the reminder of this guide will be related to the web module. src/main/lib that Chiba Web adds to the Core. src/main/webapp mirrors the directory structure found later in an exploded webapp or war-file. src/main/webapp/web-inf holds all configuration files involved with Chiba.
<put document name here> 10/13 3 building smart webapps not just XForms but also Dojo and chiba and exist and and and bla... 3.1 The XForms Feature Explorer The XForms Feature Explorer is a live XForms that shows all the power of XForms along with markup snippets to copy and explanations as help. The XForms Feature Explorer will be available from your local installation or public under http://www.chiba-project.org:8080/xf/xformsfeatureexplorer.xhtml. 3.2 Page layout Everythings' starting with a good layout... 3.3 Dojo and Chiba 3.4 using XSLT chiba xslts explained config and user agents... 'xinclude' via XSLT 2.0!!! 3.5 using Connectors
<put document name here> 11/13 4 Customizing Controls tbd
<put document name here> 12/13 5 Extending Chiba 5.1 custom XPath Functions 5.2 Connectors 5.3 Schema Datatypes 5.4 supporting new useragents 5.5 adding custom Javascript components tbd.
<put document name here> 13/13 6 Appendices 6.1 Links [1] Features page of Chiba project http://chiba.sourceforge.net/features.html The official homepage of the W3C http://www.w3c.org/markup/forms Chiba homepage http://chiba.sourceforge.net Chiba project page at sourceforge http://www.sourceforge.net/projects/chiba Chiba Download http://sourceforge.net/project/showfiles.php?group_id=20274 Status of Implementation - http://chiba.sourceforge.net/features.html interesting book about XForms from Micah Dubinko - http://dubinko.info/writing/xforms/book.html Links to other XForms implementations http://www.w3c.org/markup/forms in section 'XForms Implementations' A short introduction to XForms from Micah Dubinko (Author of the above book and member of the working group) - http://www.xml.com/pub/a/2001/09/05/xforms.html 6.2 Glossary document container a document in any XML compatible markup language like (XHTML, SVG, VoiceML, FlashML) that embeds XForms markup host language Integration a XML markup language that embeds XForms markup. a standalone distribution that uses the Chiba core and provides a platformspecific XForms implementation. Currently available distributions are 'Chiba Web', 'Chicoon' and 'Convex'.