next_inactive up previous


Double Choco Latte Developer Documentation

Michael L. Dean

$Id: dcl_developer.html,v 1.1.1.1 2001/08/09 02:39:46 mdean Exp $


Contents

1 Application Architecture

Double Choco Latte is an object oriented implementation of a problem/project management system. All actions are performed with objects that are split into 3 distinct layers: data, logic, presentation.

1.1 Login

When logging in to DCL, the login form is submitted to the web server with the user's credentials. DCL then attempts to locate that user in the database using the short field in the personnel table. If a match is found, it then performs an md5 hash of the password and compares it to the hash stored in the database. If that matches, a cookie is sent to the client with the user id, menu id, domain name, selected language, and password key.

For each successive page request, the user's credentials are re-evaluated. The cookie stored on the client system is used to load the appropriate person (if the person still exists) and compare the hashed password. In the future, this will change when real session support is introduced.

Also, during login and for each page request, the configuration is read from the dcl_config table. This table contains parameters to change the behavior and look-n-feel of DCL. When sessions come to town, this information will be persisted in the session information to reduce load on the SQL server.

1.2 Logout

Logging out simply resets the cookie to nothing, in essense deleting it.

1.3 Class Factory

Before going further, it is worth noting that DCL makes use of a class factory for object loading and instantiation. The function is named CreateObject and is used as such:

$obj = CreateObject('boSMTP');
CreateObject then looks to see if a global variable CLASSNAME_PHP3_INCLUDED has been defined. If not, it includes the appropriate file (in this case boSMTP.php3).

After the file has been included (or verified as being previously included), the object is instantiated and returned to the calling function. In the above example, $obj will contain a new instance of the boSMTP class.

1.3.1 Why Is It Called a Class Factory?

This question will invariably come up. The answer is pretty simple: a class factory is a method for the developer to request the class by a unique name and let the factory take care of the details for loading it and instantiating it. Of course, the factory in this case is represented by the simple function CreateObject.

1.4 Page Requests

Page requests all pass through main.php3. main.php3 evaluates the value of the menuAction variable. menuAction is defined as classname.methodname. Since all DCL actions are object oriented, this makes it a snap to develop new functionality and not worry about directory structures and such. All that's required is that the objects are locatable by the class factory.

What main.php3 does is segment the menuAction var into two distinct entities: the class name and method name. Pseudocode for representing this is:

list(classname, methodname) = explode('.', menuAction);

$obj = CreateObject(classname);

$obj->methodname();

1.5 File Naming Conventions

The file names are representitive of the class' name and the layer it is a part of. A file name is composed like so: <layer><classname>.php3.

The layers are:

bo
Business Object. This is the layer that handles the guts of the operations.
db
DataBase. This layer handles the interface between the other layers and the database. Normally, every table within DCL will have a corresponding db class. However, for some cross reference tables and such, there may not necessarily be a class.
html
Presentation. This layer does the majority of page rendering functions. This includes instantiating templates, populating their variables, and displaying them.

2 Database Abstraction

The database functionality is abstracted to ease porting of DCL to other SQL servers. Currently supported servers are: PostgreSQL, MySQL, Microsoft SQL Server, and Sybase Adaptive Server Enterprise. The current abstraction layer is custom written for DCL, but it might shift to modified PHPLib versions in the future.

Each server has it's own class in a file named after it. PostgreSQL is in pgsql.php3, MySQL is in mysql.php3, Microsoft SQL Server is in mssql.php3, and Sybase ASE is in sybase.php3.

2.1 Database Date Handling

To compensate for the differences in how the SQL servers store dates, two classes were written: Timestamp and Date. These classes are defined in datetime.php3.

The purpose of the each class is to handle the transition of date and timestamp entities between the presentation layer and the SQL server. This ensures that the data going into the SQL server is correct and that the data displayed to the user can be localized to their preference.

2.2 Other Database Characteristics

Anytime a difference between SQL servers is found, a function is written to abstract the difference. This ensures a common interface for all consumers of the database layer classes. Some examples are: LIMIT clause, case (in)sensitive queries, and data type casting.

3 Templates

The templates class comes from phpGroupWare, which in turn used the PHPLib templates class. To use templates in DCL, a template factory was created. This is implemented in the function CreateTemplate. CreateTemplate takes one parameter: an array of handles and template files you would normally pass to set_file. Example:

$Template = CreateTemplate(array('hForm' => 'htmlWorkorderForm.tpl'));
CreateTemplate will handle finding exactly which htmlWorkorderForm.tpl the caller needs by using the configured template set.

3.1 Location

The templates are located in the <dcl_root>/templates/<template_set> directory. To create another template set, simply copy the default template set to a sibling directory and begin modifying the templates to match the look and feel desired.

The custom directory contains template files used for non-html rendering. A current example is the Customer Quality Questionnaire email template.

3.2 Variable Naming Conventions

Templates use several different naming conventions. Currently, all variables are prefixed with a special abbreviation to describe what the variable will be replaced with.

TXT_
Static text
VAL_
Data Value
CMB_
Combo Box
BTN_
Button Text
COLOR_
Color (currently light and dark are supported from the DCL configuration)

3.3 Using Templates in html Classes

Templates are instantiated by the template factory. If a particular template is very large and/or has a large amount of supporting code, an html class is created to specifically handle only that template. If the template and supporting code is small, several template handlers can be combined into one class in different methods.

4 XML DOMish Document Objects

The latter part of April 2001 saw the introduction of a couple of classes to generically support parsing XML documents into a DOMish structure using PHP arrays. The objects make use of the bundled XML Expat parser and the PHP xml_parser_set_object function, which by nature requires PHP 4 due to objects being passed by reference.

4.1 xmlNode

This class represents a node in the XML document. It consists of a name (the tag name), an array of attributes (key => value), an array of child nodes, and a pointer to the parent node, if any. Only the root node has a NULL parent node.

It is important to remember that an xmlNode object does not have any methods itself. It is merely the representation of the properties of a node in an XML document.

4.1.1 xmlNode Member Variables

4.2 xmlDoc

xmlDoc is the document class. It is a container for a root node, which contains all of the child elements of the XML document. This class is capable of building the DOMish structure from a file or a string. It can also reproduce an XML document from the DOMish structure, which makes the xmlDoc class ideal for performing updates to the nodes.

4.3 xmlDoc Object Interface

The interface for the XML objects is relatively minimal at this point. It will probably be extended and enhanced in the future as is necessary.

4.3.1 Parsing

4.3.2 Rendering

4.3.3 Modifying

4.3.4 Navigating

4.3.5 Member Variables

5 Logic Layer

The logic layer (represented mostly by the bo*.php3 classes) controls what operations are performed for each function. For example, the boTimeCards.dbadd method will accept posted form data, add it to the database, load the associated work order, check the time card status against the work order status (and change the work order if necessary), and accumulate the time card hours with the existing applied work order hours. This is all performed within a database transaction as well (so MySQL users are out of luck until the transaction support becomes commonplace).

Just remember that the bo classes consume the db and html layers. The logic layer coordinates the necessary calls between the layers, although some html classes may require access to db classes.

6 National Language Support

Multiple languages are supported with the use of string resource files. These files merely define strings used within DCL as constants.

6.1 Location

The string resources are located in <dcl_root>/str/<language> directories. <language> is the short abbreviation of the language (e.g., en for English, it for Italian, sv for Swedish, etc).

Creating a new translation involves copying an existing set for a language you are comfortable with to the new language directory. Then translate each string in the file to the new language.

In the future, it would be very beneficial to create a small web application to maintain and generate these resources from a database. This could be made available as part of DCL, or as a development tool for it.

6.2 Naming Conventions

All string resource files are given an abbreviated name equivalent to the area of DCL they apply to. For example, cfg.str is for the configuration strings, wo.str is for work order strings, etc.

The strings defined in the resource files are prefixed with STR_<resource_abbreviation>. So, the cfg.str strings all begin with STR_CFG_, wo.str has STR_WO_, etc. This makes it very easy to identify the resources in the code and which file they belong to.

7 Database Schema



\resizebox*{!}{0.95\textheight}{\includegraphics{DoubleChocoLatte.eps}}



8 TODO Feature List

8.1 Authentication

8.2 Work Orders

8.3 Project Management

8.4 Tickets

8.5 Security

8.6 E-mail Gateway

8.7 Reporting

8.8 UI

8.9 NLS

8.10 Accounts

9 Contributors

The following is a quick list of people who have contributed to DCL in one way or another. If I forgot you, it's because I'm very disorganized ;-), but I'm trying to get this complete. Just shoot me an email and what section you belong in and I'll add you to the list.

9.1 Core Developers

9.2 Packagers

9.3 Documentation

9.4 Translations

9.5 Patches

About this document ...

Double Choco Latte Developer Documentation

This document was generated using the LaTeX2HTML translator Version 99.2beta8 (1.42)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /usr/local/apache/htdocs/dcl/dcl/docs/dcl_developer.tex

The translation was initiated by Mike on 2001-05-05


next_inactive up previous
Mike 2001-05-05