As a follow-up to my SMIL-animated SVG for accessible textbooks article, here is a copy of the README file of wecena.bliotux. I currently have 4 full-time wecena volunteers currently making accessible textbooks for children with cognitive disabilities (mainly dyspraxia) under the supervision of an INSERM medical research lab and of a dyspraxia-related non-profit organization, Dyspraxique Mais Fantastique. They currently use Didapages, a Flash-powered proprietary authoring tool to make these would-be accessible textbooks. But we are not satisfied by this tool and I wanted to propose an open-standards free software alternative. So I wrote wecena.bliotux as a proof-of-concept of such an alternative technological framework.

Beyond dyspraxia and children with disabilities, I think bliotux may be of some use for any developer looking for an alternative to Flash as a technology to make highly-graphical, ineractive and animated offline or online applications. The source code is available under the wecena subversion repository (until I create a dedicated repository). Here is a full copy of the README file :

wecena.bliotux

This software package is a framework for building web applications having the following buzzwords

• web
  apps: run in your web browser
• offline
  apps: no web server, no Internet connection required
• rich
  applications : highly graphical user interfaces, using SVG
• animated
  applications : pages can include (interactive) animations using (SMIL-powered) animated SVG templates
• interactive
  : interaction/behaviour is defined in a simple Javascript file corresponding to a given page
• with persistence
  of user data and application state : using local storage with persistence engines such as Google Gears (or HTML5 localstorage when it’s mature enough in Firefox)
• template-based
  : pages sharing a common layout/structure are based on template files
• document-oriented: a simple data structure in a data.js file defines the data used to populate the corresponding SVG template for any given page
• free software: distributed under the Affero GPL License (even though I am not 100% sure of the exact meaning of the Affero version for offline applications BTW…)
• based on open standards: SVG now (Daisy Profile for SMIL+SVG, CSS and WAI-ARIA in the roadmap) rather than based on proprietary technologies such as Microsoft Silverlight or Adobe Flash
• highly accessible
  even though using JavaScript (see open standards…)
• as cross-browser
  compatible as possible: apps should run on any web browser as long as they offer some support for SVG and Javascript; and bliotux users should not have to care much about browser compatibily.

The original aim of this package is to build a non-Flash interactive animations management framework so thataccessible
textbooks can be made for children with cognitive disabilities (mainly dyspraxia).
But it could be used to produce any set of interactive animations
such as books, websites, interactive animations or I don’t know what.
You imagine.
You experiment.
You tell me what it may be useful for !

The following JavaScript libraries are used

• jQuery
• jQuery.SVG
  (RaphaelJS
  might have been a better choice).
• jQuery.jStore
  (PersistJS
  might have been an acceptable choice).
• Google Gears
  (as a dependency of jStore because the implementation of HTML localstorage by Firefox has a bug)
• doctestjs
  (because I would be so cool if only I could figure out how to use Javascript doctests for this project…)

Disclaimer with regards to JavaScript as a programming language :
Ahemm… Javascript was selected because we wanted to have one and only one language to be used both for the making
of bliotux-powered templates and pages and for their execution.
And their execution should not require any
prior installation of software : the web browser should be the only required stuff.
And Javascript seems to be the only open-standards-oriented way to offer rich interactivity to SVG in web browsers.
Too bad.

How to use wecena.bliotux ?

At the moment wecena.bliotux is nothing but a proof-of-concept.
More will come in case the project I’m working on selects this technology
as a viable alternative to the Flash-based proprietary product we are
currently using in order to make accessible textbooks for children
with cognitive disabilities.

Download and install bliotux

It’s in a subversion repository.
There is some subversion documentation available in
case you don’t know how to download software from a subversion repository. Bliotux is stored
in the wecena repository but it will get its own repository some day.

Create a template

Bliotux pages are based on templates.
Let’s create a first template.

Name your template

Choose a name for your template. In this example,
the name is

simpleOperation

because it is a template page for textbooks
for children learning additions and other simple mathematical operations.

Name a template folder accordingly.
For instance, I have

wecena.bliotux/templates/simpleOperation/


Define the layout of your template

This part is the job of a graphics designer.

The layout of a template is defined by a SVG file.
(Download, install and) use any SVG editor to create such a file.
I personnally use Inkscape, which is free software.

Your SVG template should be named

layout.svg

and
should be stored under the template folder.
Here it goes:

wecena.bliotux/templates/simpleOperation/layout.svg


The next version of Inkscape should allow you to use its new timeline-based animation editor capabilities to add
animation to your template.
At the moment, you will have to have an XML developer edit the source code of your SVG
template and add animation (animated SVG) instructions “by hand” if needed.

Here is a clue about how to possibly accelerate the development of such SVG animations without waiting for the
next version of Inkscape :

1. Download and install Open Office Impress
2. Make a (duplicate) sketch of your layout in Impress
3. Add the desired animation effects to it using the rich set of animation features Impress offers
4. Save your animated Impress presentation in its native .ODP format
5. Open this file using an archive handler (such as winzip under windows) :
   Open Office files are nothing but ZIP archives containing XML and graphics
6. Edit the source code of the main XML file this .ODP archive contains.
7. Ask your XML developer to copy, paste and adapt the animations instructions therein
   into your
   
layout.svg

   file.
   (The animation instructions can easily be located : they use the
   
anim:

   namespace).

Define the interactivity of your template

This part is the job of a Javascript developer.

This is the hardest part if you are not a developer.
It should be easy if you have any experience in web development.

In the case of a children textbook for teaching additions and other simple mathematical operations,
we’d like our “simpleOperation” template to display a simplified virtual keyboard with numbers.
When the child clicks on a number, this number is added to a “result” text element in the template layout.
So we need to know how to use an SVG element (the number we want to click on) as an interactive button
which will display some text result as the content of an other SVG element.

The interactivity of your template is first prepared in your

layout.svg

file.
Using Inkscape XML Editor (Ctrl + Shift + X), you add event attributes
to the SVG elements you want to add some interactivity to. This involves accessing
the XML source code of the SVG file, which you should not be afraid of thanks to
Inkscape XML Editor.

For instance, let’s say you have a SVG group of elements which you want to
act as a button. You select this group using Inkscape. You press Ctrl+Shift+X. The
XML Editor opens. There you see the group of elements as a <g … > element.
You then want to add interactivity to this group. You have to add a

onclick

attribute.
The value of this attribute should be “clickButton(evt)”. This means that whenever the
user mouse clicks on this button, a MouseEvent event called “evt” will be fired and
some Javascript function called “clickButton” will have to handle this event so that
something special happens.

Now you have injected some interactivity attributes into the XML source code of
the SVG file of your template. This source code now includes things like this :

<g onclick="clickButton(evt)" ...


Let’s develop this clickButton Javascript function so that you define what should
happen whenever the button is clicked. This definition is written in a Javascript file
you have to name “interaction.js” and which sits under the template folder:

wecena.bliotux/templates/simpleOperation/interaction.js


For instance, this file could contain the code below (see included examples, too, if needed) :

function clickButton(evt){
    alert('You clicked the button !');
    $('.whereResultShouldBeDisplayed', svg.root()).html('Clicked !');
    $('.someSVGElementsWhichShouldBeEmptiedWhenButtonGetsClicked', svg.root()).html('');
    storageSave('.whereResultShouldBeDisplayed', 'Clicked !');
    storageSave('.someSVGElementsWhichShouldBeEmptiedWhenButtonGetsClicked, '');
}

If you are as unfamiliar with Javascript as I am, you need some more explanations here.
What does this function says ?

It says that it takes an input parameter called “evt”. But it won’t use it in this case.

It first displays a popup alert window with a message (‘You clicked…’)

Then it changes the content of the SVG displayed in the web browser. It writes the text ‘Clicked !’ in
every SVG (or HTML BTW) element which has an attribute called “class” (the same attribute which can be used
for CSS files) including the value “whereResultShouldBeDisplayed”.

For instance, let’s say you have this text element in your layout.svg file :

<text
  id="text4790"
  y="386.98224"
  x="454.43787">
  <tspan
    y="386.98224"
    x="454.43787"
    id="tspan4786"
    class="whereResultShoudlBeDisplayed someOtherClass">Not clicked yet.</tspan>
</text>

Then, once the user clicks the button, your interaction.js file will have this text element changed into this :

<text
  id="text4790"
  y="386.98224"
  x="454.43787">
  <tspan
    y="386.98224"
    x="454.43787"
    id="tspan4786"
    class="whereResultShoudlBeDisplayed someOtherClass">Clicked !</tspan>
</text>

Can you see the difference ?

For more information about how Javascript can have the web browser manipulate
the content of the page at runtime, please see jQuery API documentation. Just remember to
apply jQuery selectors to the root of the SVG document (

svg.root()
) and you should be fine.

There is also this call to storageSave in your interactivity function. What does it mean ?


storageSave

is a function defined by bliotux.
It takes 2 input parameters : a key and its value.
It will have this pair of (key, value) made persistent in the local web browser.
Even if the browser (and possibly computer) is closed (shutdown), this (key, value) pair is still available
and can be later retrieved using another bliotux function :

storageLoad(key)
.
Next time the same page is displayed, any SVG element which corresponds to key (as a jQuery selector) will have
its content filled with value.

In this example, storing the text

"Clicked !"

as
the value of the key

.whereResultShouldBeDisplayed

means 2 things:

1. this text
   
"Clicked !"

   can be further retrieved with any Javascript call to
   
storageLoad('.whereResultShouldBeDisplayed')

2. next time this page is displayed using the same web browser, the
   
"Clicked !"

   text will be added to all SVG elements which have the
   
whereResultShouldBeDisplayed

   class attribute in their source code.

As a result of this, the state of each page can be made persistent
so that when the user returns to a given page he already interacted with
this page displays the exact same info/aspect/behaviour as before.

Now you have your

interaction.js

file which defines the full interactivity of your template document.

Create a page

Creating a page is much easier than creating the template a page is based on.
But it requires writing some (extremely simple) code using any text editor (Windows notepad…).
Any brave user should be enabled to do so.

You have a full bliotux template, including an SVG layout (possibly including animation) and Javascript interactivity.
Now let’s create a page based on this template.

Name the folder with the page name

In this example, let’s name a first page

Sesamath_CP_page-094_exercice-001

along the name of a French free (as in free speech) textbook vendor.
In order to do so, we create this folder:

wecena.bliotux/pages/Sesamath_CP_page-094_exercice-001/


When we want to access this page, we’ll have to direct our web browser to such an URL as

file:///home/jean/wecena.bliotux/index.xhtml?page=Sesamath_CP_page-094_exercice-001


Define the template this page uses

Which template will this page use ?
The answer comes as a Javascript file we have to create:

wecena.bliotux/pages/Sesamath_CP_page-094_exercice-001/data.js


This file contains the declaration of variables describing this page.
The variable called template defines the template to be used for this page:

var template = 'simpleOperation';

Populate the template

The next variable in this

data.js

file define data which will get injected into the template so that
the page is built :

var data = {
  '.pageCentaine':'',
  '.pageDizaine':'9',
  '.pageUnite':'4',
  '.exerciceCentaine':'',
  '.exerciceDizaine':'',
  '.exerciceUnite':'2',
  '.operande1Centaine':'',
  '.operande1Dizaine':'',
  '.operande1Unite':'7',
  '.operateur':'-',
  '.operande2Centaine':'',
  '.operande2Dizaine':'',
  '.operande2Unite':'5',
  '.resultatCentaine':'',
  '.resultatDizaine':'',
  '.resultatUnite':'',
};

This data associative array lists (key, value) pairs which define which content should be injected where.
The key (for instance

.pageCentaine

) is a jQuery selector to be applied to the root of the SVG template.
The value is some SVG code which is to be inserted as the content of any SVG element matching the key.

Rather than using

id

attributes as selectors (

#pageCentaine

), it seems preferable to use

class

attributes (

.pageCentaine

) which carry the meaning (semantics) of the corresponding SVG element and can be reused
several times in the same template (whereas IDs should be unique, I suppose).
Anyway, the SVG template should be edited so that the corresponding

class

attribute are present where needed.

Include some page-specific graphics

Using the mechanism of templates and the data.js file, you may have your SVG template include some areas where
pages could have specific bitmap (JPEG, PNG) files displayed.
This is just the matter of including such a JPEG file in the

layout.svg

file,
giving the corresponding SVG element an appropriate class attribute (using Inkscape XML editor for instance)
and then defining in

data.js

the name of the picture file to insert in this area of your layout for this specific page.

But you can also have given pages include full SVG files.
For instance, the left part of

simpleOperation/layout.svg

is meant to display a funny but didactic illustration
where characters (such as Tux the penguin) invite the child to perform the mathematical operation at hand.
Such an illustration could contain page-specific animations.
Adding an animated GIF file would not be enough.
The full power of SVG for animations may be required.
In such cases, you can define an svgParts variable in the data.js file of the page :

var svgParts = {
  '#illustration': 'illustration.svg'
}

This variable says : “Hey, bliotux, please look at my template
and find the SVG element with

illustration

as the value of its

id

attribute.
Then replace this full SVG element with the first

g

element (SVG group) you will find
in the

illustration.svg

file sitting under this page folder. Thanks.”

That’s it

You can access and test your page at a URL which should look a bit like that (the exact path depends on the folder hierarchy
on your hard drive):

file:///home/jean/wecena.bliotux/index.xhtml?page=Sesamath_CP_page-094_exercice-001


Side note : Now I realize I can’t use doctestjs for this document so it’s pretty useless to me.
It would have been much useful if only I had figured out a way to have some Javascript code generate
a template document in the filesystem during the doctest so that I can further test bliotux on it
using doctestjs. Maybe later…