----------------------------------------------------------------
---------------- AXEL integrator's FAQ --------------------
----------------------------------------------------------------
Last update: 2013-10-10 by S.Sire
This document gives some advices for integrating AXEL into your application.
It is presented as a FAQ. You are welcome to share your experience to improve
it.
PLEASE READ THIS DOCUMENT BEFORE USING AXEL
Summary
=======
How to build the library ?
==========================
The library comes with the latest sources concatenated and minified inside
axel/axel.js. However it is wised to make a fresh version by running the
"build.lib" target in the scripts directory ("cd scripts" then "ant
build.lib"). This requires that you install the Yahoo UI compressor onto your
machine, and that you edit the "scripts/ant.properties" file to point to it.
You can get the Yahoo UI compressor at http://developer.yahoo.com/yui/compressor/
How to build the library for debugging purpose ?
================================================
Follow the instructions above with "build.debug" target instead. The generated
library will be a concatenated version of all the library files including
comments, which is more convenient for debugging purpose. This does not
requires to installe the Yahoo UI compressor.
How to select which source files to include into the library ?
==============================================================
The files to include into the library are defined by the "core.lib.files",
"editor.lib.files", "devices.lib.files", "filters.lib.files"
and "util.lib.files" in the "scripts/ant.properties" file.
You can remove some files to generate a smaller library.
The dependencies between the source files are explained in the
"How to know which files to include in the library ?" entry of this FAQ.
How to test the core features of the library after checkout ?
=============================================================
The first thing to do is to open test/auto/loadSave.html and to hit the "Run
Test" button at the upper right, within each browser and on each operating
system that you intend to support.
You must be aware however that if you open it directly from within your file
system (i.e. no web server involved), all of the tests may fail on some browsers
and if you click on the [inspect] link you should see a message such as:
Exception while loading "XXX" : Access to restricted URI denied
This is because the default security policy of the browser prevents the test
application to open files from the local file system using the XHR object.
This is the case with Firefox for instance.
If this happens, you can either start again serving the files from behind a Web
server, or find a way to enable access to local files from the XHR object.
On Firefox for instance you have to set "security.fileuri.strict_origin_policy"
to false in the "about:config" panel. See [1]
The test configuration is described in test/auto/configuration.js, hence you
can also customize it with your own test. Each test is defined by a template
and an XML sample data file produced with the template. The test will load the
template, transform it, load the XML sample data, dump the XML data, and
compare it with the initial data. It FAILS if there is a difference, which
means something is wrong. You are encouraged to create your own configuration
and make extensive tests on your own data when ugrading the library to a newer
version.
Currently all the tests configured by default PASS on Firefox, Safari, Chrome,
Opera and Internet Explorer (except the test based on the 'content' plugin).
The tests with the "richtext" plugin FAIL on Opera and Internet Explorer.
This is due to some minor differences in the serialization
results. However it doesn't mean the plugin is not functional but only that
different browsers give different HTML serializations which are all valid and
can be viewed in any browser.
All the tests above can be executed directly from the file system on Firefox
3, Safari 4, Internet Explorer 7, Opera 10, on Windows, Mac OS X, and
Linux (Ubuntu). For Google Chrome there is a security restriction that prevents to
open URLs with XMLHTTPRequest from the file:// domain. In that case you must
launch the test from behind a Web server (see "How to configure
scripts/server/server.rb to execute the tests" if you want to use the test
server provided with AXEL).
[1] http://kb.mozillazine.org/Security.fileuri.strict_origin_policy
How to test the interactive features of the library after checkout ?
====================================================================
The second thing to do is to test the library with user interactions. There
are two ways to proceeds, unfortunately none is automatized yet and requires
user interaction...
The first way is to open each pre-defined template distributed with the
library from the test/gui folder inside a target browser. There should be
different templates for the core library and each of the plugins. Each
template imports the AXEL library which has been generated inside the axel
folder (see "How to build the library ?") and transforms itself to become
auto-editable. Then follow the instructions of each template that describe
some interactive tests to performs.
The second way is to open editor/editor.xhtml, select a template (Page
shortcut drop down list) and hit the "Visualize" button to generate the
corresponding editor and enter data. You can also use the preferences button
to load XML data inside a template. There should be at least one sample
template for each plugin / filter.
You can also directly test your own template by entering its path by hand. We
strongly advice that you do so with your own template and test the interactive
features before upgrading the library to a newer version.
The editor.xhtml application can be run directly from the file system with
Firefox 3, Safari 4, Opera 10 and Internet Explorer 8. It renders the
templates inside an iframe. This is convenient as it also loads the external
CSS files. We have some problems with Internet Explorer 7 not loading
correctly the templates (MIME-Type sniffing issue, and/or not injecting the
AXEL style sheet inside the iframe). In that case you can use
editor/editornoframe.xhtml that does the same thing but without an iframe. The
drawback is that in that case any external CSS files included by the template
will not be loaded.
How to learn about AXEL API to load and transform templates into editors ?
==========================================================================
You should read the AXEL tutorial that starts in
tutorial/tutorial.xhtml
Alternatively you can look at the source code of:
- editor/editor.xhtml : to see how to load a template
and transform within an iframe
- editor/editornoframe.xhtml : to see how to load a template with an Ajax
request and transform it to a div in your application Web page
How to write portable (cross-browser) templates ?
=================================================
Use the file templates/samples/Template.xhtml as a starting point for your templates
How to Serve portable (cross-browser) templates ?
=================================================
We do not have a definitive answer. But we have noticed the following facts.
From the local file system, to open a template file either in a Web page or in
an iframe, the file should have a .xhtml extension. In addition for Internet
Explorer you should include the following META tag (it seems the META tag
prevails for MIME-type sniffing when opening file from the local file system):
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
From the local file system, to open a template with the XMLHTTPRequest object
or with an ActiveX object, we have no opinion :)
From a Web server, to open a template file either in a Web page or in an
iframe you should serve it with the "application/xhtml+xml" MIME type for all
browsers excepted for Internet Explorer. For IE you should serve it with a
"text/html" MIME-type. Be careful however that the "text/html" MIME-Type will
fail on all the other browsers. Hence you should implement content-type
switching on the server.
Alternatively you can server a template from a Web server to an XMLHTTPRequest
object or an ActiveX object. It seems that in that case the best thing to do
is to serve it with a "text/xml" MIME-type which is acceptable on all the
browsers.
How to configure scripts/server/server.rb to execute the tests ?
================================================================
scripts/server/server.rb starts a Web server that listen on port 8042
(http://localhost:8042/demos/index.html) and that serves the full library
distribution.
You can use it to launch the sample editor and/or do some testing from
behind a Web server in case you have problem to launch them from within the
file system. Read the previous entry "How to Serve portable (cross-browser)
templates" to learn how to properly configure their MIME-Type.
The server.rb script does not implement contextual MIME-TYPE switching, hence
you must set your own by hand depending on the case, and using an instruction
such as my_mime_types.update({"xhtml" => "text/html"}) (see the source code).
How to get some documentation about the available plugins / filters ?
=====================================================================
Some very common plugins are described in the XTiger XML specification [1]
(such as "text" and "select").
The rule of thumb is that every plugin / filter should have a How-To style
guide in the docs folder, and a demonstration template that you can play
with using the editor/editor.xhtml application in the templates folder.
Finally you can check the AXEL wiki [2].
[1] ssire.github.com/xtiger-xml-spec/
[2] https://github.com/ssire/axel/wiki
How to know which files to include in the library ?
===================================================
All the files in "src/core" are required except "iebrowser.js" which is
required only to run on Internet Explorer.
All the files in "src/editor/classical" are required except "xmlrobustloader.js"
which is required only to use the robust loader algorithm. In that case you may
also omit the "xmlloader.js" file if you don't use the basic loader algorithm.
You must leave "xmlloader.js" after "xmlrobustloader.js" to set the default loader
algorithm to the basic one.
You need the files in "src/plugins" according to the primitive editors you use
in your templates:
text.js: 'text' primitive editor (depends on text.js device)
select.js: 'select' primitive editor (depends on popup.js device)
link.js: 'link' primitive editor (depends on popup.js device)
photo.js: 'photo' upload primitive editor (depends on popup.js, upload devices
and documentid.js filter)
video.js: 'video' primitive editor for YouTube video
(depends on popup.js device)
You need the files in "src/devices" according to the primitive editors you use
in your templates as stated above. For your information:
text.js: input and textarea text entry fields
popup.js: popup menu that may segmented
lens.js: generic lens device (mega popup) for all lens based primitive editor
upload.js: transfers a file (e.g. image file) to a server through an iframe
requires a server that implements a corresponding communication
protocol
You need the files in "src/filters" according to the filters you use in your
template. The only exception is "documentid.js" which can be required to use
the 'photo' primitive editor. For your information:
common.js: 'noxml' filter
documentid.js: 'documentid' filter to be used with 'photo' plugin
event.js: 'event' filter to generate 'axel-update' events
wiki.js: 'wiki' filter of the 'text' primitive editor
image.js: image inclusion by URL filter of the 'text' primitive editor
initially developed for the Article.xhtml template
layout.js: 'layout' filter of the 'text' primitive editor (experimental)
video.js: YouTube 'filter' of the 'text' primitive editor, alternative to
'video' plugin
debug.js: 'debug' filter for each of the primitive editors
How to choose between the basic XML loading algorithm or the robust one ?
=========================================================================
This is an OPTIONAL section you do not need to understand for using the library.
When loading XML data in a template with xtiger.util.Form.loadData, as
described in the tutorial, the library uses the XML loading algorithm defined
by the defaultLoader property of xtiger.editor.Generator. That property is set
by the latest of the two source files "xmlrobustloader.js" and "xmlloader.js"
which is included in the library. The pre-built "axel.js" file does include
only the basic algorithm (i.e. "xmlloader.js").
Alternatively you can explicitly set the loader object by calling the
setLoader method of xtiger.util.Form with either a new
xtiger.editor.RobustLoader, or a new xtiger.editor.BasicLoader argument to
select respectively the robust or the basic algorithms (in that case do not
forget to include either "xmlrobustloader.js" or "xmlloader.js" into the
library).
The robust loader uses a greedy algorithm for loading XML data. It supports
some forms of backward compatibility at the data level when a template has
been modified. The drawback is that the template must conform to a set of
restrictions on the full XTiger XML specification. The modifications
themselves are limited to a restricted set of modifications. Both the XTiger
XML restrictions and the allowed modifications are defined in a "Guidelines
for writing robust XTiger XML templates" document written by Antoine Yersin
which is available on demand (contat us).
In conclusion be very careful if you want to use the robust XML loading
algorithm. In particular USING THE ROBUST XML ALGORITHM ON TEMPLATES WHICH ARE
NON ROBUSTS may lead to some data loss and distortions when editing data.