             TUTOS V2 Development guide, or some ideas
            -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

Here are some thoughts on how to implement the new TUTOS, that is a
TUTOS with application logic usable as xml-rpc services, and a new
rendering engine using smarty templates.

The objectives are, in order:

  1. clean out the presentation code from TUTOS code

  2. add comments to each function, saying what are the input and
     output, and what do the function

  3. publish the public part of tutos application logic as xml-rpc
     services

  4. re write the presentation code using smarty html templates system

Before giving some details about how to manage such tasks, let me
point clearly this: I'd want all that stuff to be ready and usable by
april, so I will have to be efficient. The main idea here is to do all
the stuff in little time, but yet cleanly enough for it to be really
useful.


1. Cleaning code
-=-=-=-=-=-=-=-=-

The main idea is to clean out each and every formatting code, so there
won't be any 'echo' call nor any html to be seen.

A great number of tutos files are doing some tutos logic and some
presentation stuff, such as *_overview.php and the like. We will have
to separate the logic stuff.

I plan to keep those file for handling TUTOS presentation stuff, see
section 4.

Logic stuff can be implemented in *_overview.pinc files for
example. Those file in particular will have to clearly define inputs
and outputs.

While doing this, the html rendering of TUTOS will be broken, so we'll
have to get others ways of testing the stuff. See section 3!


2. Commenting the code
-=-=-=-=-=-=-=-=-=-=-=-

If I had to say one thing about TUTOS code, I would talk about the
lack of comments. Please take the rewritting oportunity to comment the
code, using phpdoc format for example (http://www.phpdoc.de/).

Those comments are to be very useful right away, writting templates.


3. Publishing an API
-=-=-=-=-=-=-=-=-=-=-

This can be done after the cleaning, or better while doing it.

The better would certainly to write tests while we are refactoring the
code. In some other projects I have used python xmlrpclib as an xmlrpc
console, this is really useful. What about some unit tests in python?

This would allow for client and inter-operability tests. And then we'd
have a regression tests tool for the published part of TUTOS.

Of course we could use PHPUnit to do the same job, but here I'm in a
hurry, so Iplan to write tests to assure myself I'm not in the wrong
path, and I know how to writte them quickly with python.

So while cleaning out the current TUTOS code, we publish some API and
use it to test the code we're editing.


4. Writting templates
-=-=-=-=-=-=-=-=-=-=-

The logic application is now clearly available thru functions,
publishing data structures where we find the data we asked. Those data
have to be presented on a way that fits to a web browser.

We will write down html templates for rendering lists, tables, menus
and so on, those templates will take as argument a PHP data structure.
And as we use smarty, we have a direct access to PHP data structure
from within the html template.

Please begin each template by :
 . a note on what it presents (kind of data, ...)

 . an example of the data structure containing the information
     we should use print_r() to obtain this example

 . then the html code itself

On the html code, I'd like to follow the W3 specifications for better
accessibility and standard compliance. What about XHTML1.1 and CSS2?

And some ECMAScript if we can't make it with css...

We could have a template/ subdirectory for each new theme we want to
implement, if templates are well documented writting a new theme
should be easy.

Smarty provides also some configuration files, so we can easily
decline a theme on color styles. So we obtain a two level choice when
selecting a display mode: first a theme, then a color sheme, or style.
