Revision as of 23:26, 1 April 2008

The current pre-alpha sandbox for the web client is at ?? setting it up now ???

Here the overall idea of the web design, and as usual this document is subject to change.

The target web client is based on the following components being available.

apache

database

php

Commands - this is an extensive TODO list of commands and class functions.

php5.2+

5.2 is our platform of choice. More importantly 5.2 has JSON built in.

Importantly the get and set methods are used, so ideally everything is an ojbject of some sort of another.

There can be broken down into the following areas that cover their class areas.

 The persistent object as a json call to a Record eg
 case: 'LIST_USERS':
   //* this is a foo object so
   $u = new WI_Users($ID);
   //$u->list(); << we cant use lsit its a reserved word in php
  $u_>view();

More of this to follow.. says pedro .Have a target path.. fortunately from experience..

Were also using php exception to raise application errors. see classes/WI_Exceptions.php

and mimiec for more help because his maths is way beyond mums simple php ;-)

JSON

The config.main.php file detects if mod_json() is loaded and available, ie php5.2+ and if its not, then load the libs/JSON.php script.Not yet implemented.. and maybe dont need to be.. JSON.php file is there..

RPC

the rpc/ directory contains all the ajax requests. These are broken into either a fetch or an action. For example getting a list of users is a fetch and updating an user would be an action. See WI_Commands

Objects

Everything (almost) needs to be an object. Were using the php5 methods of __set() and __get() to maintain persistance.

One of the bummers is that we'd like to create functions such as

return $users->list();

however in a class declaration of

public function list(){ .. 

the list is considered a keyword. damn so the suggested function is

$users->users_list();
// its a pain init

It is worth while to have a look at class.wi_Core.php which which needs to be extended for each instance.

A quick introduction to the the technique is with the following psuedo code

class wi_Comment extends wi_Core
{
   public function __construct($id){
      //* call to parent class which set up all variables etc
      //* The first var is the ID, and the second is the name of primary key
      parent::__construct($id, 'comment_id');
      if($this->_id > 0){
         $sql = 'select * from comment where comment_id=?'
         $this->_data = $this->db->getRow($sql, array($this->_id));
      }
   }
}

__autoload()

The __autoload() function is used to load classes. This means that files can be included on the fly as required. If there is a new library then please add it to the __autoload() function declared in config.main.php.

Its noted that the php name space is class.wi_Foo.php with a capital F. However with php5.3 around the corner, we will have namespace.

smarty

We might not need it - apart from maybe some spoolng and email formatting.

javascript

The front end will be mainly driven by Ext.js. Its worth taking some time to check out the samples and the extensive API's. The system works more like XUL, Gnome, Qt etc where components are packed into an area so some experience in this area is useful. There's hardly any HTML in there.

As the web client will really heavily on javascript, then we need to be pretty careful about name space, and Ext comes with its own "namespace manager" etc.This is currently being researched.

All JavaScript needs to pass the jslint test, which means that global variables need to be declared at the top of any js file with

/*global Foo, Bar */ - note no space before g

Code optimisation

There are a few tool kits out there for compressing javascript files as well as concating them. eg yuicompressor which is the one well probably use.

We need to be clever about how to use the javascript in dev mode vs production mode.

$JS_LIBS

There is a $JS_LIBS variable in the config.local.php file and points to the "js" subdirectory of the webissues directory.

One optimization trick is to locate the JavaScript libraries/style sheets on another domain. For example a http://libs_sub.domain.com can be optimized with compression and caching enabled. The rationale is that normally a browser out of courtesy will only make around five concurrent connections to a server, so having some material on another domain, even serving from the same machine really does speed things up.

Form Handling

There are two techniques for submitting extra variables back to the server, eg the action or ID. The first way is to add them as {params} eg

myForm.form.submit({ url: 'foo.php',
                     params: {action: 'UPDATE', my_id: some_id, vals: myForm.getForm().getValues()}
...

The other way is to include the values as hidden fields, like traditional html,

//* hidden fields
{name: 'action', xtype: 'hidden',value: 'UPDATE'},
{name: 'my_id', xtype: 'hidden'} // takes value from reader
//* submit is now a one liner
myForm.form.submit({ url: 'foo.php',
                     params: {vals: myForm.getForm().getValues()}

The second form is preferred as it makes it easier to read, but also that all the variables are contained "in the form" and not in other strange places.

Ext Plugins

There will be a few of these, and should be located in js/ext-plugins/*, and they should be documented here. Small styles code for various widgets should be added to the plugins.css file instead of individual files.

Ext.ux.form.FieldSet (Fieldset.js)

There are a couple of quirks with the stock FieldSet object.

1) You cant set the checkbox value (i know). This plugin was taken from this forum thread. Its an extendion of FieldSet, that has a setValue() function. The "checked" even is being looked at.

2) There is no event for "checked" which is being looked at. In the interim the expand/collapse events are used where expand = checked = true (a hack i know).