Copyright © 1999, 2000, 2001, 2002, 2003, 2004 The NO-SOD Project
2004
Table of Contents
List of Tables
Table of Contents
The following rules apply to the NO-SOD Framework version 2.0.1 (tod10), and are presented as a summary of a starting point for new developers. This document is not the complete developer manual, but may be used as a small reminder.
Any module requires a module code, three characters length. The module codes are delivered for free by the NO-SOD team. Internal modules (meaning specific modules for a company) must use the Inx module code. See http://www.no-sod.org/certification.php for details.
Implemented systems are using the following database components:
Content of .db file provides (located in include/dbparameters):
all .db files may point to the same host/database, for small configurations.
To use a database connection you must instantiate an object "nsdDB". Any access to this database must go through the instantiated object. Multiple database object may be instantiated.
Implemented systems are using the following database components:
File names must start with the three module code (always uppercase for "src" and "html" file types) characters.
Source code files have ".src" suffix (under /src/dev/)
Html template files have ".html" suffix (under /html/dev/)
Included files must have ".inc" suffix (under /include/ccl/...)
Library files must have ".lib" suffix (under /src/dev/)
All picture files must be stored in the directory "/pics/module code" where module code is lower case.
All icon files must be stored in the directory "/icons/module code" where module code is lower case.
All javascript files must be stored in the directory "/js" where the .js file name must contain the module code.
All registered session variables of a module must begin with the module code. Other variables must take care of reserved variables (lower/uppercase):
CERT, ACT, NSD*, SRC*, HTML*, DSP, MYSESS, MYSYSDB, MYTRAILDB, LOAD, CCL*, IP, FAULT, ERROR, POS, CUR_ACT, XMLDATA, XMLDATANAME, XMLINDVALUES, XMLINDNUMBER
To register a variable, put the variable in the $_SESSION array. The variable must have the same name as the key in the array.
$_SESSION["XXXregisteredvar"]=$XXXregisteredvar;To use a registered session variable, use the variable name directly ($XXXregisteredvar)
To unregister, use the unset PHP function as follow: unset($_SESSION["XXXregisteredvar"]))
Data are received through variable, transmitted with either GET or POST methods. To enable variable reception with the register_global parameter set to OFF (php.ini), use the following functions:
For POST data:
$nsdpostvars["srcFILENAME"]=array("var1","var2"...);For GET data:
$nsdgetvars["srcFILENAME"]=array("var1","var2"...);srcFILENAME is the source file called by the html get action. Var1, var2, etc are the list of the variable names to enable
To request from a source code file to merge an html template files with computed variables, and send the result to the client browser (as output):
Put the name of the html template file into the variable $nsddspz
From a source code file, you can link the process to the execution of another source code file by setting the variable $act to the name of the linked source code file.
From an html file, you can post, or get the $act variable in order to define the source code file to call from the client browser. The only PHP file must stay the FLY.PHP
Table of Contents
Every call from the browser to the HTTP server goes through the file called 'FLY.PHP'. This script manages the execution of the process within the NO-SOD Framework environment. By calling the FLY.PHP at every process of your web application, you take directly benefit of the framework security and integrated development environment.
Explanation step by step of the FLY process:
nsdmailing
values = 0 (Inactive) or 1 (Active)
When activated, every call to the mailing functions provided in the framework will be executed. Set this to 0 if you do not have mail infrastructure, such a SMTP server.
load
values = 0 or 1 or 2
This variable defines how the framework will find the source code and html files reuired during a module execution.
The major difference between load 0 and 2, is that with load 2, the documents loaded are not kept in memory for next calls.
This is easier to develop or debug in load 2, avoiding to logoff from the moduleat each trial. This is correct for all document types execept LIB files. LIB files are always kept in memory.
nsdsqltrace
values = 0 (Inactive) or 1 (Active)
When activated, the framework genrates SQL logs of every database access under the /logs directory.
nsdver
This set the framework version. It's used to retrieve LIB, INC, SRC and HTML files of the current framework at runtime.
nsddspz
This is the final output variable. Developers set this variable to the name of their html file to output, within the SRC code.
The FLY will use this variable in one of the latest step to see if there is an output to process or not.
Including external files
nsddms.inc
This is main part of the NO-SOD Framework. It contains the management of the documents, database and session objects types.
These three towers cannot be loaded through the documents engines, because they are the mechanism of documents engine.
ecpmod.inc
This is the Electronic Check Point module custom class file. Dedicated functions may be used by other module than ECP as well.
For audit trail, module security, and control reasons, the variable called 'ip' is set to the remote client ip address.
If the client window browser name is not defined, set the name of this variable called 'nsdwin' to 'MAIN'. The 'MAIN' browser processes are going through every audit trails. Sometimes it's usefull that a subwindow browser of an application doesn't go through audit trail, particulary when this subwindow has for goal to check indefinitely if something has changed at the back-end side (like a big loop waiting the end of another process). E.g. btach job process are most of time requiring that kind of behaviour. To avoid having a trace of the subwindow hits every x seconds in your trail database, call the 'FLY' script with nsdwin as get or post variable, with a value not equal to 'MAIN'.
If the fly.php is called without the variable $act defined, then the process start a new NO-SOD session.
To do so, here are some actions executed:
Instantiate a new session object, and try to start it. If session started with the no-sod version, then:
In the case the session didn't started, the error returned will be "SIZ" => Sizing error, no more free session slots, try again later.
Name the session with the certificate ($cert), and start the php session.
Check if the session object is present. If not present, exit with error code "CER" => Certificate error, either the $cert was wrong, or the session environment cannot be retrieved.
If the session is started successfully, declare all session variables as global (this exports all variables from the session array as global varaibles).
Verify if the remote client ip address has not suspiciously changed. If the IP is not same as in the session variable IP property, then exit with error code "TIP".
Connect the system database using the appropriate db object.
Evaluate every library object document defined in the library list property of the session object.
Declare all the variable from GET,POST and FILE php arrays, defined as expected in the source code execution ($act) by the developer through $nsdgetvars and $ndpostvars arrays, as global variables.
Unserialize registered objects from the session object list property (cf keepobject method of the session object). This provide an effective way to set the Class definitions inside versionned documents, avoiding .INC flat versioning.
Track everything in the audit trail, and check if session is not timed out.
This process is looping indefinitely, unless no other action (source code extraction and execution) is requested. This check is done by verifying the $act variable content.
If a source code set the $act variable content to the name of another source code, then the process will be 'linked' to the requested action.
For each action requested, here comes the sequence:
The fly is checking the varaible $nsddspz. If the variable is not empty, then retrieve the html object document name defined in the $nsddspz variable. The variable $nsddspz is set by the module developer in the action source code.
The html object document type are kept in memory as session variable as the .src (action source code) files. The loading process is exactly the same. The html document content is not directly evaluated, but is 'Evaluated and merged' with existing environment variables of the fly runtime execution. That's how these html files are templates.
Then the process send the merged result to the standard output.
Every object having his class definition stored in a versionned source code file (so, not defined in .INC files) must be serialized and stored under a property of the session object, being an array of serialized objects. This is needed because if you register directly these objects as session variable, then at the next fly execution, the 'session start' statement will try to 're-life' these objects without having their class definition available (because stored inside source code document objects or library that have not yet been 're-life' themself.
Type: available variables
Location: nosod.lib / fly.php / nsddms.inc
Table 3.1. Variables list
| Variable | Description |
|---|---|
| $cert | Session certificate |
| $mySess->uname | User name |
| $act | Source code to execute (action) |
| $nsddspz | Output html template (name of the display) |
| $mySess | The session object |
| $mysysDB | The system database object |
| $mytrailDB | The audit trail database object |
| $load | The loading mode for execution (dev: 2, database:1, file is load zero) |
| $ip | Remote client browser's ip address |
| $fault | Boolean value set at true when error occurred |
| $error | The error message defined when $fault is true |
| $pos | Defined at zero where requested action requires to be logged in |
| $cur_act | The current action ($act) processed |
| $xmldata | Global variable used for XML parsing |
| $mySess->id | Session number |
| $mySess->uid | The user id of the user logged in |
| $mySess->fullname | The complete user name of the user logged in |
| $mySess->modname | The current module initials |
| $mySess->modversion | The current module version |
| $mySess->modsrcver | The current source code version of the current module |
| $mySess->modguiver | The current GUI version of the current module |
| $mySess->nsdver | The current Framework version |
| $mySess->ip | Remote client browser's ip address |
| $mySess->start | Session start time stamp |
| $mySess->liblist | Array of libraries currently used |
| $mySess->objlist | Array of objects having class definition in libraries |
| $mySess->cname | The remote browser's computer name |
| $mySess->parameters | Array containing each parameter of the current module |
| $mySess->userloggedin | Boolean value set to true when the user is logged in |
| $mySess->profile | User profile of current user |
| $mySess->message | Message to transmit to the user through the GUI |
Type: standalone function
Location: nosod.lib
htmlgen(arg1, arg2)
Input:
Output: string (returned)
This function has for goal to generate automatically an html table content. The approach is to provide in 'arg1' the name of the array prepared by a previous process. This array must be two dimensions, where the first dimension is the row (starting at 0), and the second dimension is the column (starting at 0).
In arg2, you put as string a subpart of html table, identifying the row template. Inside the row template, put the characters '++vx++' at each place of a data, where x is the column number + 1 (means you start with ++v1++).
The function will return the complete html table generated. It's usefull when you generate a table from a database query, and that you do not know in advance how must row the table will contain. This function can be used also for generating html dropdowns and lists, as the template principle is the same.
Example: Suppose your html template file contain something like
"<TABLE>$IN0K_INFO</TABLE>"
The source code generating the html output will be something like:
"$query=$IN0DB->queryExec("SELECT NAME,FIRSTNAME FROM PEOPLE WHERE YEAROFBIRTH=2000");$i=0;
while ($r = $IN0DB->queryFetch($query))
{
$IN0K_INFO[$i][0]=$r["NAME"];
$IN0K_INFO[$i][1]=$r["FIRSTNAME"];
$i++;
}
eval(htmlgen("IN0K_INFO","<tr>
<td><font face=\"Courier New\">++v1++</font></td>
<td><font face=\"Courier New\">++v2++</font></td>
</tr>"));
"
Type: standalone function
Location: nosod.lib
htmlgentable(arg1, arg2, arg3, arg4, arg5)
Input:
Output: string (returned)
This function has for goal to generate automatically an html table content, as HTMLGEN, but is dedicated to produce table effects with one row on two having a different backgroud color. The provide higher visibility in the table produced in the html output.
The approach is to provide in 'arg1' the name of the array prepared by a previous process. This array must be two dimensions, where the first dimension is the row (starting at 0), and the second dimension is the column (starting at 0).
In arg2, you put as string a subpart of html table, identifying the row template. Inside the row template, put the characters '++vx++' at each place of a data, where x is the column number + 1 (means you start with ++v1++).
In arg3, you must give the name of the background color variable defined in the row template as well. E.g. for a ++vbgcolor++ in the template, provide "bgcolor" in arg3.
In arg4 and arg 5, provide hexadecimal colors for rows background. E.g. #CCCCCC and #AAAAAA
The function will return the complete html table generated. It's usefull when you generate a table from a database query, and that you do not know in advance how must row the table will contain.
Example: Suppose your html template file contain something like
"<TABLE>$IN0K_INFO</TABLE>"
The source code generating the html output will be something like:
" $query=$IN0DB->queryExec("SELECT NAME,FIRSTNAME FROM PEOPLE WHERE YEAROFBIRTH=2000");$i=0;
while ($r = $IN0DB->queryFetch($query))
{
$IN0K_INFO[$i][0]=$r["NAME"];
$IN0K_INFO[$i][1]=$r["FIRSTNAME"];
$i++;
}
eval(htmlgentable("IN0K_INFO","<tr bgcolor=\"++vbgcolor++\">
<td><font face=\"Courier New\">++v1++</font></td>
<td><font face=\"Courier New\">++v2++</font></td>
</tr>","#CCCCCC","#AAAAAA"));
"
Table of Contents
Location: nosod.lib
This class has for goal to provide user object definition to the application. Everything related to a user must be processed through this class, for reliability reasons.
Principle:
Every user definition is stored in the system database, as an XML document of type 'user'. So this class uses the nsdDoc class as storage engine, with document type 'usr'. Objects are stored in tables nsduser(master), nsdusers(versions) and nsduseri(exported indexes) tables.
Table of Contents
Location: nosod.lib
This class has for goal to provide group object definition to the application. Everything related to user's group must be processed through this class, for reliability reasons.
Principle three types of group are defined:
Users can be attached to public or private groups, never directly to system groups.
Summary schema: user (n) -> (n) public or private group (1) -> (n) system group
Groups are stored inside the system database, in the table nsddgroup. Relationships between system groups and other groups are stored in the table nsddlink, as well as relationships between users and groups.
Location: as source code files
Library files such nosod.lib have for goal to contain sets of functions and classes usable by the module source code. Isolating these functions and classes in a lib file provide an efficient way to avoid code redundancy.
What's the difference with a .INC file ?
The main difference is that .LIB content is managed by the framework like a source code document. This means the document is stored, versionned and extracted as the complete module code. Dot INC files are not managed by the document management engine of the framework. To benefit of the security with versionned source code, use .LIB files instead of Dot INC. Library files do not need php tags ($lt;?php ?>), .inc files need these tags.
How to manage session variables containing objects having their definition stored in a .LIB file ?
This question comes from the fact PHP regenerates objects at the session start statement. When the session starts (the php session, not the no-sod session... the session start statement is executed at every server hit) php needs to have available the class definitons of objects re-generated. If not, objects are lost. With .LIB files, the problem is that the class definition stored in a document object, are only available after the session start (as they are also session variables). In order to provide the possibility to put class definitions in .LIB files, every object of a .LIB that you want to register a session variable must be processed by the keepobject() function. So, to register an object, just call keepobject() and give the object name as argument. If you ask yourself how is it possible, the mechanism serializes all objects passed through the keepobject function before the end of the FLY execution. The FLY unserialize these serialized objects kept as session variable at the beginning of the FLY execution. Refer the FLY documentation for more details. Note that the keepobject function is a method of the session object (defined in the nsddms.inc file).
How to create a lib file for my module ?
Your module lib file name must begin with your module initials, and be a .lib extension. You must store the lib file in src/dev directory, with .src files. In order to declare your lib file to be loaded automatically by the framework, at your module login, you must put the name of your lib file (without the .lib) extension in the nsdmodule table of the system database, in the column 'libname'.