AXEL-FORMS is an extension to the Adaptable XML Editing Library that defines additional plugins and filters to create forms, a binding mechanism and a command mechanism. Like AXEL, AXEL-FORMS is an open source (LGPL v2.1) library.
The binding and the command mechanisms define microformat instructions to be included directly on the XTiger XML and application page markup. This way you can use them without writing Javascript code, in a fully declarative way.
Use the binding mechanism to dynamically constrain the authoring process (e.g. constrain a field input space with a regexp, contrain two dates to follow each other, etc). This is targeted at XTiger XML authors.
Use the command mechanism to associate high-level commands such as save (save the open document to a server), or load (load a document into an editor) with user interface controls such as buttons into a page. This way it is easy to create editing user interfaces. This is targeted at web application developers. Some commands may be redundant with functionalities exposed by the $axel wrapped set object, however they do not require writing Javascript code and thus are easy to render in markup generation tool chains such as XSLT transformations.
Javascript developers have access to the binding and command mechanisms in the
$axel.binding and $axel.command namespaces. Javascript developers can create
and register new bindings and commands as explained in the documenation.
AXEL-FORMS requires JQuery and AXEL. Some demos using the Date filter (from AXEL) also require the jQuery-UI library. It is apparently compatible with jquery-ui-1.12.1 although third part contains an older version).
The master branch is the stable release branch
The devel branch is the development branch of current version
Some versions have been tagged when we upgraded some components :
- version 0.2 uses jquery-1.7.1
- version 0.3 uses jquery-1.7.1 brings very few changes over version 0.3, however it is the last one using jquery-1.7.1
You must checkout the AXEL-FORMS repository into a sibling directory of the AXEL code distribution available at https://github.com/ssire/axel.
To clone the AXEL distribution from its git repo run :
git clone git://github.com/ssire/axel.git.
To clone the AXEL-FORMS distribution from its bitbucket repo run :
git clone [email protected]:ssire/axel-forms.git.
This repository is also published as the AXEL-FORMS web site thanks to the Git Hub project pages mechanism. From the web site you can directly test AXEL-FORMS inside your browser without any preliminary software installation. Follow the instructions of the section "For the impatient".
The web site is regularly updated, however to really get the latest version checkout the repository. The master branch is where we push AXEL-FORMS more stable releases while the devel branch is where we prepare the next release.
This repository contains some sample templates in the templates folder.
You can open those templates using the editor in the editor folder.
To launch the editor just open the editor/editor.xhtml file inside
your browser (Firefox recommended, see the security note displayed in the launch screen).
If you are just interested in using and deploying AXEL-FORMS, all you need
to do is to build the library (see below) and to copy the dist/axel-forms.js
file to your Web server. You must also have deployed AXEL onto your server.
The rule of thumb is that if you checkout the master branch it will contain
a built of the dist/axel-forms.js library file lined up with the code. Be aware that if
you checkout the devel branch, you will need to rebuild the dist/axel-forms.js file
following the instructions of the next section.
To build the library with the latest sources concatenated and minified inside
the dist folder, run the build.lib target in the scripts directory:
cd scripts
ant build.lib
You need to have or to install the ant tool,
which is already available on many operating systems. Ant is easy to install,
you just need to copy its jars somewhere and to have it into your $PATH.
You also need to install the Yahoo UI compressor onto your machine (jar file), and
to edit the scripts/ant.properties file to point to it.
You can get the Yahoo UI compressor at https://github.com/yui/yuicompressor
Alternatively the build.debug target simply concatenates source files
together, so you can use it without installing the compressor.
AXEL-FORMS is an extension to AXEL developped and maintained by S. Sire at Oppidoc.
Please contact us for further inquiries.
You can run the demonstration editor directly from the file system, however this may lead to some problems transforming the templates and/or loading XML data on some browsers. This is because they will not allow the editor to transform a template loaded inside an iframe, and/or to read files from the file system because of a strict application of security policies.
An alternative solution is to access the AXEL distribution from a web server.
For instance, if you have ruby installed you may run a one line command into a terminal to start a web server serving the current directory and below (at http://localhost:3000 on the example below) :
ruby -r webrick -e "m = WEBrick::HTTPUtils::DefaultMimeTypes; m.update({'xhtml' => 'application/xhtml+xml'}); s = WEBrick::HTTPServer.new(:Port => 3000, :DocumentRoot => Dir.pwd, :MimeTypes => m); trap('INT') { s.shutdown }; s.start"
You need to start the web server from the AXEL-FORMS parent directory where you have copied an AXEL distribution too.
Don't forget to configure the server to serve XTiger XML template files with the 'application/xhtml+xml' MIME-TYPE, otherwise the browser will propose to save them as external documents and not transform them.
Such commands exist with other languages (e.g. python).
We currently do not have strong coding conventions as you will see by yourself when browsing the source code, however respect at least these ones :
- soft tabs
- 2 spaces per tab
- remove spaces at the end of lines (you may use a filter such as
sed -E 's/[ ]+$//g') - test source files with jslint
Each plugin should be documented in a self-describing template file inside
the templates/plugins folder.
Each filter should be documented in a self-describing template file inside
the templates/filters folder.
Each binding should be documented in a self-describing template file inside
the templates/bindings folder.
Each command should be documented in a self-describing template file inside
the templates/commands folder.