Return to daxe_2016_doc.txt CVS log

Up to [LON-CAPA] / modules / damieng / doc

added updated doc about Daxe

LON-CAPA Daxe in 2016

graphical_editor.tex explains the background of LON-CAPA Daxe development. Since it was written, A first version of LON-CAPA Daxe has been created and integrated in LON-CAPA 2.12.

The source code is still in the CVS at loncapa/modules/damieng/graphical_editor/loncapa_daxe.
LON-CAPA Daxe is based on Daxe, which is on github at https://github.com/adopt/daxe.
Some basic documentation is available on the Daxe website at http://adopt.github.io/daxe/.


Dart development

The development tools for Dart have evolved quite a bit. Current options are listed at https://www.dartlang.org/tools.
The Dart Editor (which was developed at google) and the Dart plugin for Eclipse have been removed from collective memory (if you somehow manage to download them, they do not support the latest SDK).
Google is now strongly suggesting JetBrains IDEs like WebStorm. WebStorm is commercial with an annoying licensing scheme, but it is free to develop open-source applications (as long as a free licence is renewed every year). There are several open-source editors that can use a plugin for Dart edition, adding not only syntax highlighting but also some useful tools like real-time warnings. For instance, integration with Atom is pretty good, except that there is no debugging. Debugging has to be done in Dartium, which is doable but not convenient.

For instance, to setup a Daxe development environment with Atom,
- install the Dart SDK and Dartium from https://www.dartlang.org/install
- make sure the Dart SDK bin directory is on the PATH
- install Atom from https://atom.io/
- in Atom, install the dartlang package
- open the loncapa_daxe project directory
- see https://dart-atom.github.io/dartlang/ for more info


Running LON-CAPA Daxe from the source

To run LON-CAPA Daxe,
- go to the loncapa_daxe directory, use the terminal command ./build.sh (this should get the latest Daxe from github and compile everything)
- use the command "pub serve" to start a web server on port 8080 with the documents in loncapa_daxe/web.
- in Dartium, use the following URL: http://localhost:8080/loncapa_daxe.html?config=config/loncapa_config.xml (it starts with an empty document)

Opening the same URL with a different browser will trigger an automatic conversion to Javascript (which can take a few seconds), but it should work. Obviously, debugging is easier directly in Dart, which is why Dartium is used for that. But other browsers have to be used for testing.

Debugging in Dartium can be done with the developer tools (F12).


Integrating into LON-CAPA
(this can be done without an editor for Dart, just with the Dart SDK)

- ./build.sh should prepare the build directory with everything needed.
- cd build
- tar cvzf daxe.tar.gz daxe
- copy daxe.tar.gz into loncom/html/adm/daxe/
- update the VERSION file there


Daxe vs LON-CAPA Daxe

Daxe is simply an extensible XML editor for the web. It it useful to provide a user interface to edit XML documents in an XML language that does not already have a specific editor. It provides a solid basis to create a new customized editor for a given XML language, because it provides an implementation for the basics of any XML editor.

LON-CAPA Daxe is an extension of Daxe, designed only to edit documents using the LON-CAPA language. It adds many display types providing a custom UI for LON-CAPA XML elements, some new menus and toolbar items, and a preview panel. All these things are initialized in loncapa_daxe.dart, which contains the main procedure for the web application. The LON-CAPA language is defined in the XML schema loncapa.xsd inside web/config, and the general user interface for documents using this language is defined in loncapa_config.xml in the same directory. Both are XML files and can be edited with Daxe. The schema is a W3C XML Schema document, while the configuration file is using Daxe's XML language for configuration files.

Each custom display type has a class in web/nodes and the link between the new display type and the class is done in loncapa_daxe.dart with the addDisplayType method. The config file is using that display type for chosen elements in the language.


LON-CAPA documents vs XML documents

LON-CAPA documents are currently not using the XML syntax (they are not "well-formed"). One example of this non-XML syntax is non-escaped less-than characters within script elements. Edition with Daxe is only possible for XML documents, so a conversion is needed from LON-CAPA documents into XML, and vice-versa.
This is done automatically by the Perl scripts in loncom/homework/cleanxml. These scripts also try to fix frequent errors in the HTML code automatically. In some rare cases, it is possible that the conversion from LON-CAPA to XML fails, which means that it will not be possible to edit the document with Daxe. Usually it is possible to fix the document with the text editor, but not always. For instance, one syntax that cannot be fixed easily is when an element purposely contains start or end tags without the corresponding start or end tags. A change in the document logic would be required to fix that. Once a document has been converted into XML, it might still not be valid (ie conforming to the schema). Daxe provides a real-time validation and a full document validation to check for errors and help fixing them, but it will also let authors edit documents and save them even if they are not valid.