Documenting javascript

Sandrine and Alain worked on the javascript documentation tools and how they could be integrated into our sphinx generated documentation.

They first studied pyjsdoc which unfortunately only generates HTML. After a somewhat successful attempt to generate sphinx ReST, we decided to use a consistent documentation format between python modules and js modules and therefore switched to a home-made, very simple javascript comment parser. Here's an example of what the parser understands:

/**
 * .. cfunction:: myFunction(a, b, /*...*/, c, d)
 *
 *    This function is very **well** documented and does quite
 *    a lot of stuff :
 *    - task 1
 *    - task 2
 *
 *    :param a: this is the first parameter
 *    ...
 *    :return: 42
 */
function myFunction(a, b, /*...*/, c, d) {
}

The extracted ReST snippets are then concatenated and inserted in the general documentation.

Unit testing javascript

Katia, Julien and Adrien looked at the different testing tools for javascript, with the two following goals in mind:

• low-level unit testing, as cubicweb agnostic as possible
• high-level / functional testing, we want to write navigation scenarios and replay them

And the two winners of the exploration are:

• QUnit for pure javascript / DOM testing. Julien and Adrien successfully managed to test a few cubicweb js functions, most notably the loadxhtml jquery plugin.
• Windmill for higher level testing. Katia and Sylvain were able to integrate Windmill within the CubicWeb unit testing framework.

Of course, there is still a lot of work that needs to be done. For instance, we would like to have a test runner facility to run QUnit-based tests on multiple platforms / browsers automatically.

Parametrized stylesheets and vertical rhythm

Sylvain worked on property sheets and managed to implement compiled CSS based on simple string interpolation. Of course, compiled CSS are still HTTP cached, automatically recompiled on debug mode, etc. On his way, he also got rid of the external_resources file. Backward compatibility will of course be guaranteed for a while.

Nicolas worked on CSS and vertical rythm and prepared a patch that introduces a basic rhythm. The tedious work will be to get every stylesheet to dance to the beat.

What's new in CubicWeb 3.9?

The 3.9 release development was started by a one week long sprint at the beginning of May. The two goals were first to make it easier to customize the look and feel of a CubicWeb application, and second to do a big cleanup of the javascript library. This led to the following major changes.

• We introduced property sheets, which replace former external_resources file, as well as define some constants that will be used to 'compile' cubicweb and cubes' stylesheets.
• We started a new, clean cubicweb.css stylesheet, that tries to keep up with the rhythm. This is still a work in progress, and by default the old css is still used, unless specified otherwise in the configuration file.
• We set the bases for web functional testing using windmill. See test cases in cubicweb/web/test/windmill/ and python wrapper in cubicweb/web/test_windmill/ if you want to use this in your own cube.
• We set the bases for javascript unit-testing using qunit. See test cases in cubicweb/web/test/jstests/ and python wrapper in cubicweb/web/test_jscript/ if you want to use this in your own cube.
• We cleaned the javascript code: the generic stuff moved into the cw namespace, the ajax api is now much simpler thanks to more generic and powerful functions. As usual backward compatibility was kept, which means that your existing code will still run, but you will see tons of deprecation warnings in the firebug console.
• We implemented a simple documentation extraction system for javascript. Just put ReST in javascript comments, and get all the power of sphinx for documenting your javascript code.

But that's not all! There are also two major changes in 3.9.

Architectural change: adapters

The first major change is the introduction of adapters, also found in the Zope Component Architecture and documented in the GoF book. This will allow for better application design and easier code reuse. You can see several usage in the framework, for instance the "ITree" adapter in cubicweb.entities.adapters, the "IBreadCrumbs" adapter in cubicweb.web.views.ibreadcrumbs, or still the "ICalendarable" adapter in cubicweb.web.views.calendar.

Important full search improvement

The second major change will benefit directly to end users: we worked with our friends from SecondWeb to expose the ranking feature found in postgres full-text search. This clearly improves the user experience when doing full-text searches. Ranking may be finely tuned by setting different weights to entity types, entity types attributes, or even be dynamically computed per entity instance. Of course, all this is done in an adapter, see "IFTIndexableAdapter" in cubicweb/entities/adapters.py.

Minor changes

Other minor changes include:

• support for wildcard text search for application using postgres >= 8.4 as backend. Try searching for 'cub*' on cubicweb.org for instance.
• inline edition of composite relation
• nicer, clickable, schema image of the data model
• enhanced support for the SQLserver database

Enjoy!