sitemanager manual 2.2.x

7/29/2019 SiteManager Manual 2.2.x

1/70

Roadsend PHP SiteManager

Shannon WeyrickRoadsend, Inc.

Jon MichelRoadsend, Inc.


2/70

Roadsend PHP SiteManager

by Shannon Weyrick and Jon Michel

2.2.x Production Series Edition

Copyright 2001 by Roadsend, Inc.


3/70

Table of Contents1. Introduction......................................................................................................................................................................................6

Overview....................................................................................................................................................................................6

Feature Summary.......................................................................................................................................................................6

About Roadsend.........................................................................................................................................................................8

2. General Information ......................................................................................................................................................................10

Version Numbering..................................................................................................................................................................10

File Extensions for SiteManager Re source Files .....................................................................................................................10

Security Concerns ....................................................................................................................................................................10

Directory Layout......................................................................................................................................................................11

3. SiteManager Fundamentals..........................................................................................................................................................12

SiteManager Global Variables .................................................................................................................................................12

SiteManager Root Object ($SM_siteManager) .......................................................................................................................13

loadSite Method...........................................................................................................................................................13

loadModule Method.....................................................................................................................................................13includeModule Method................................................................................................................................................14

rootTemplate Method...................................................................................................................................................14

loadTemplate Method ..................................................................................................................................................14

loadCodePlate Method.................................................................................................................................................15

dbConnect Method.......................................................................................................................................................15

startSessions Method ...................................................................................................................................................15

addPersistent Method...................................................................................................................................................15

completePage Method..................................................................................................................................................15

fatalDebugPage Method...............................................................................................................................................16

Global Configuration System...................................................................................................................................................16

getVar Method..............................................................................................................................................................17

getSection Method .......................................................................................................................................................17

setVar Method ..............................................................................................................................................................18

Variable Replacement ..................................................................................................................................................18

Section IDs..................................................................................................................................................................19

SM_Object Base Class.............................................................................................................................................................20

......................................................................................................................................................................................20

Internationalization Support.........................................................................................................................................20

Directive Scripts.......................................................................................................................................................................21

Modules....................................................................................................................................................................................22

Overview......................................................................................................................................................................22

moduleConfig Method .................................................................................................................................................22

moduleThink Method...................................................................................................................................................25

canModuleLoad Method..............................................................................................................................................26

Database Connectivity .................................................................................................................................................27

Session Functionality...................................................................................................................................................28

Module within Modules...............................................................................................................................................29

Extending Your Modules .............................................................................................................................................29

preThinkList and postThinkList ..................................................................................................................................30InVar Propagation (read-write inVars) .........................................................................................................................33

Multilingual Support....................................................................................................................................................33

Module Design Tips.....................................................................................................................................................34

Templates.................................................................................................................................................................................34

3


4/70

Templates within Templates (sub-templates)...............................................................................................................36

CodePlates................................................................................................................................................................................36SmartForms..............................................................................................................................................................................39

Usage............................................................................................................................................................................39

Create a New Form ......................................................................................................................................................39

Configure Form............................................................................................................................................................40

Add Elements...............................................................................................................................................................40

Loading a SmartForm ..................................................................................................................................................41

Configuring Elements ..................................................................................................................................................42

Run Form and Input Validation Check ........................................................................................................................42

Form Templates............................................................................................................................................................43

Hidden Variables..........................................................................................................................................................44

Session Aware Forms...................................................................................................................................................45

Session Management ...............................................................................................................................................................45

Configuring Sessions ...................................................................................................................................................45

Using Sessions .............................................................................................................................................................46

Member Login Sessions...............................................................................................................................................47Database Connectivity .............................................................................................................................................................49

Database Connection Settings......................................................................................................................................50

Multiple Database Connections ...................................................................................................................................50

Error Handling and Debugging................................................................................................................................................51

DebugOnVar ................................................................................................................................................................51

JavaScript Debug Window...........................................................................................................................................52

Helpful Debug Routines ..............................................................................................................................................53

Miscellaneous Routines ...........................................................................................................................................................53

4. Designing a SiteManager Site By Example .................................................................................................................................54

Assess Site Needs ....................................................................................................................................................................54

Determine Separation of Static Layout from Dynamic Content ..............................................................................................55

Determine Method of Splitting Dynamic Content Into Modules ............................................................................................56

Determine Site Plan .................................................................................................................................................................56

Implement Site Plan.................................................................................................................................................................57Site Configuration ........................................................................................................................................................57

Template Design ..........................................................................................................................................................57

Module Design:............................................................................................................................................................57

5. Using The Test Site.........................................................................................................................................................................59

6. Extending SiteManager.................................................................................................................................................................60

7. Frequently Asked Questions .........................................................................................................................................................61

8. Getting More Help .........................................................................................................................................................................62

A. Directive Lists................................................................................................................................................................................63

Module Directives....................................................................................................................................................................63

Template Directives .................................................................................................................................................................64

SmartForm Directives ..............................................................................................................................................................64

Input Entity Directives.................................................................................................................................................66

Filter Directives............................................................................................................................................................66

B. File Formats...................................................................................................................................................................................67

.XSM Resource Files ...............................................................................................................................................................67

SMARTFORM.............................................................................................................................................................67

SMLANGUAGE..........................................................................................................................................................67

4


5/70

SMOBJECT .................................................................................................................................................................67

SMCONFIG.................................................................................................................................................................67SMRESOURCE...........................................................................................................................................................67

Tag Descriptions ..............................................................................................................................................68

5


6/70

Chapter 1. Introduction

Overview

SiteManager is an Open Source Web Application Framework that leverages the power of PHP and its Object Oriented features to

create a powerful base library for all types of web applications.

SiteManager was designed with PHP programmers and development teams in mind. It allows them to separate the process of web

site design into four steps: code creation, layout design, site implementation and site management.

Step 1. Code Creation. During code creation developers construct modules of reusable source code. The modules can be shared

easily between projects and developers. SiteManager simplifies creating, configuring, and maintaining code modules by providing

a common framework and an integrated library of tools. The library includes database connectivity, user session management, error

handling, security, SmartForms, and much more.

Step 2. Layout Design. During layout design, standard HTML tags, style sheets, and SiteManager XML Area Tags combine to

form a powerful template engine. This engine lets developers keep the HTML layout separate from the code modules that power it.SiteManager Area Tags are used to identify important sections of the layout to the template engine. Layout based templates give

designers and graphic artists freedom to create and change the appearance of the entire site without worrying about breaking the

sites functionality. Advanced SiteManager developers can take reusable layout design even further through the implementation of

CodePlates.

Step 3. Site Implementation. During implementation developers use directive scripts to assemble modules of code and template

layouts into the completed web site that clients will see. Only a few line of code are required to select which template is used, add

modules into specific areas of the template, and customize each module.

Step 4. Site Management. In order to facilitate maintenance of the site, almost all of the top level settings are stored in global

(system wide) and local (site specific) XML configuration files. These settings include database connection information, directory

locations and all of the configuration options for sessions, debugging and default extensions. Once the site has been created you can

utilize the Global Configuration System to make changes and upgrades safely.

As a truly Open Source project, Roadsend PHP SiteManager includes full source code, which is clean and well documented.

Feature Summary

Module System

Modules are the nucleus of a SiteManager web application. They are the functional blocks of code such as a search engine,

tree menu, or data driven news display that make a web site interactive or original. SiteManagers powerful object-oriented

system helps programmers to design reusable modules for their websites by allowing for run time configuration. This lets the

same module do different things depending on the context in which it was called or the page that loaded it. Modules even can

decide not to load at all. Modules also have embedded support for cascading style sheets, client side scripting and for the

extensive library of SiteManager object functions such as database access, sessions, and SmartForms. While many PHP web

programmers are busy reinventing the wheel, users of the SiteManager system will have access to a growing library of

modules developed by the Open Source community.

Template SystemTo support team-oriented development of web applications, SiteManager uses a powerful template engine which separates

HTML, graphics and layouts from functionality. The SiteManager template engine gives developers much more than a simple

"search and replace" template variable system. Using SiteManager tags, a template defines arbitrary "areas" in which to place

modules of code. These tags are interpreted by the SiteManager system. A template can load specific modules into areas or

6


7/70


use Directive Scripts and CodePlates to extend modularity even further. Templates can also be used recursively

(sub-templates), or even used inside of a module.

CodePlates

CodePlates take the template system a step further. CodePlates solve the problem of having to duplicate code when you use a

similar template/module layout scheme in multiple pages. CodePlates are templates that already have certain modules

associated with their areas. These modules are configured inside of the CodePlate. A CodePlate can be loaded as the main

layout template or added to an area in another CodePlate or Template. This functionality makes creating co brands with

SiteManagers template engine fantastically easy.

SmartForms

To truly create a "dynamic" website, input must be continually gathered from the user. This creates the need for a consistent,

structured way to setup an input form, validate input, and gather the information. Creating form elements and validating input

by hand is always slow and tedious.

SmartForms were created as a way to rapidly create an input form using predefined input entities, validate the input using

predefined filters, and gather the information in a structured way. SmartForms includes all the standard input types (textbox,

checkbox, select list, etc) as well as some not so standard, but still often used types (date select,combo box, state list, country

list, etc). It also includes many predefined filters (required, number, email, credit card, phone, regexp + more) that you can

attach to any input entity. You can attach any number of filters to any input entity. And, SmartForms are "database-aware" - we

include entities such as DB Select list, which populates a list from a database. All entities and filters are pluggable modules of

code, where all you have to do to add a new entity to the system is drop it into the correct directory.

When using a SmartForm, you never have to worry about creating elements or checking for input validity by hand. You dont

even have to worry about outputting the form its all handled by SmartForms. All you do is define the form, run it, and ask it

if all input was valid.

Database Connectivity

Roadsend SiteManager uses the PEAR Database abstraction layer for database connectivity. It is included with all versions of

PHP (v4 and above). It allows connectivity to a number of different databases through a common API.

SiteManager includes a middle layer of functionality that allows the PEAR DB system to be integrated within the SiteManager

system. Database settings and creation of the database object are consistent with the framework for SiteManager and the

Global Configuration System. Once a database connection is defined in the GCS, it is usable by all SiteManager objects.

Global Configuration System

All core classes in SiteManager have access to the SiteManager Global Configuration System or GCS. Stored in XML files

for easy access, the default options are first set on a global level in the Global Configuration file. When you create a new site,

you can override or augment the default options in a local configuration file.

User Sessions

SiteManager includes its own user session management routines. The session manager can use a database or the URL to store

information on each session. Sessions are maintained with cookies or a session ID passed with all internal links. Session

variables are automatically included when passing information through SmartForms and regular HTTP links. Session

management is available with or without a database. All session variables can be serialized, allowing complex objects to be

kept persistent.

Related to the session management is the Member system. SiteManager includes full support for allowing members to "log in"

to the site, and all modules know if the current session is a Guest or Member session.

7


8/70


Security

SiteManager adds a layer of protection when accessing variables coming in from a web client. A module designer is able tellSiteManager what type of variable its expecting (for example, an integer), and SiteManager will fail to run the script if the

value passed for that variable doesnt match the type expected. This limits the amount of damage a user can do by passing or

changing passed script variables.

Support Routines

Many supporting routines are included with SiteManager to help create your web application. These include:

Authorization Routines

Data Manipulation Routines

Error Handling / Debug Routines

Security Routines

Misc Support Routines

Object Oriented Framework

The SiteManager framework is extensively object oriented, to promote reusable code and easy maintenance.

The SiteManager source code is clean and well documented.

Open Source

Roadsend SiteManager is an Open Source project. The entire system may be distributed and used freely. The source is freely

available for all to learn, review and change. Please read the license agreement available in the file LICENSE in the /doc

directory, or on the web at http://www.roadsend.com/license/rpl1.txt

We actively encourage all hackers to help us maintain and grow the project. Please see CONTRIBUTE in the /doc directory

for more information.

We continue to build our community of developers who are activity creating Modules, SmartForm Entities and Filters,

example sites, and helping with maintenance of the project. In this way we will ensure SiteManagers continued growth as theleading Web Application Framework for PHP.

About Roadsend

Roadsend, Inc. is based in Fishkill, NY. We provide hosting and consulting services for Web business applications. Our website is

http://www.roadsend.com, and you can reach us at

Roadsend made the switch from PERL to PHP as its main web programming language back in 1998 around the time 3.0 was

coming out. From then on it was obvious PHP would make a quick rise to the top as the best (and of course freely available)

website development language.

Over the course of 3 years, Roadsend developed many websites and libraries to support them. Eventually it became necessary to

switch to a more structured, modularized framework. SiteManager has grown out of that system.

Commercial support is available. Please see the main Roadsend website, or send us mail.

The primary authors of Roadsend SiteManager are:

Shannon Weyrick ()

Jon Michel ()

8


9/70


Roadsend would like to thank all who have contributed to the project. For a full list of contributors, please see doc/THANKS in the

distribution.

9


10/70

Chapter 2. General Information

Version Numbering

SiteManager follows a version scheme that consists of three numbers - for example, 2.1.11

The first number (MAJOR) indicates the version of the underlying architecture. All releases with the same first number have the

same underlying architecture. Releases with different MAJOR numbers are not guaranteed to be 100% compatible with each other.

The second number (MINOR) indicates the development state. If the second number is even, the version is a "stable" release. If

odd, its a development release and should not be used for production quality sites.

The third number (RELEASE) indicates the version within this release level. Different versions in the same release level may

contain bug fixes or new features, but should be back wards compatible with previous versions in the same release level.

File Extensions for SiteManager Resource FilesThe following file extensions are used in SiteManager:

File Extension List

Extension: .inc

File Type: PHP Library Code

Extension: .mod

File Type: SiteManager Module

Extension: .tpt

File Type: SiteManager HTML Layout Template

Extension: .stp

File Type: SmartForm Layout Template

Extension: .xsm

File Type: XML Configuration/Definition File

Extension: .php

File Type: Web Page Loadable PHP Script (Directive Script)

Extension: .cpt

File Type: CodePlate Object

Security Concerns

We recommend you make all of the SiteManager Resource Files unreadable by the webserver, except ".php" files. The rest are not

meant to be seen by users.

The following line will accomplish this in Apache:

# dont allow access to SiteManager files

Order allow,deny

10


11/70

Chapter 2. General Information

Deny from all

Check your web servers documentation for more information.

Directory Layout

Every site run by SiteManager has a common directory structure (on UNIX, this is commonly found in /var/www/myProject or

/home/httpd/html/myProject)

/ - (root)

/admin - (admin / config directory)

/modules - (local site modules)

/templates - (local site templates)

/smartForms - (local site smartForms)

/config - (local site configuration files)

/codePlates - (local site codePlates)/locale - (localization files)

/home - (main page directory)

All files in /admin should be protected from reading by the webserver. None of these files located in this directory or its

subdirectory should be readable by a user requesting them through the web. The best way to stop this is the stop the webserver

from reading the file types found in these directories. Alternatively, you can tell the webserver not to serve any files under the

admin/ directory.

For even better security, you can move the directories underneath admin/ to a directory outside of the web document root. This is

the most secure, as configuration files will then be unavailable to web clients. The only required file in the web root will be

common.inc, which will be accessed by the directive scripts. If you need to, common.inc can be renamed to common.inc.php

(just make sure your directive scripts access it this way!).

SiteManager itself contains the following directory structure (on UNIX, this is commonly found in /usr/local/lib/php/)

/ - (root)

/bin - (binary files/scriptsfor maintenance and automation)

/cache - (resource cache directory)

/config - (configuration files,

ie globalConfig.xsm)

/doc - (documentation, LICENSE, etc)

/lib - (main lib directory)

/sfFilters - (SmartForm filters)

/sfInputEntities - (SmartForm input entities)

/modules - (SiteManager core modules)

/skeletonSite - (skeleton site used for

template when creating new site)

/smartForms - (site wide SmartForms)

/tables - (SQL table creation scripts)

/templates - (SiteManager core templates)

/testSite - (Fully functional test site)

11


12/70

Chapter 3. SiteManager Fundamentals

SiteManager Global Variables

The following are global variables and objects setup and used by SiteManager. Remember that since they are global, PHP requires

that you declare them as such within functions and class methods.

$SM_siteManager

The root SiteManager class. Use this class for high level control of the site, such as starting the Database and Session systems,

Loading a Module, or Loading the Root Template. You will use this object frequently throughout your SiteManager site.

$SM_siteID

This is the unique site ID for your project. It should be defined in admin/common.inc. It is used for configuration and

debug purposes. It is arbitrary, but all capital by convention. It can only contain letters and numbers, and can not contain white

space. An example siteID is TESTSITE. Note that this siteID MUST match the tag from your projects

config/localConfig.xsm file!

$SM_siteName

This is the site name for your project. It is arbitrary free-text, used for debugging purposes. It may contain white space. An

example $SM_siteName is Test Site 1

$SM_sessionVars

A string that contains the current valid session parameters, useful for using as GET parameters to a script. All registered

persistent variables will show up here. See also SM_session::getSessionVars(), which will update this variable to the

latest session values and return a copy of itself.

$SM_debugOutput

An array with debug information. Each time a call to SM_debugLog is made, and new item is added to the array. You

shouldnt need to access this array directly. See the ERROR HANDLING section for more information.

$SM_rootDir

If you dont want to - or cant - place the SiteManager directory into the PHP include path, you can set this variable in

siteManager.inc. Point it to the main SiteManager root directory, and SiteManager will be able to find its library files.

$SM_develState

The current value (true or false) of the develState flag from the GCS variable "debug" SECTION of the GCS. Use this flag

in an if block when you want debug information to show up only when the develState flag is on. This is useful for limiting the

amount of debug information that shows up on a production server.

$SM_defaultLocale

The current value of the defaultLocale variable from the GCS variable "localization" SECTION the GCS. It determines

the site wide default locale.

12


13/70


$SM_clientLocale

A string (or possibly an array of strings) of the values retrieved from the HTTP_ACCEPT_LANGUAGE server variable. Itwill contain a list of locales the current client is using. It can used to determine which language should be used for output, for

example. It is automatically used by the getText() method of SM_object to determine the default language.

$SM_debug

IfdebugOnVar is true in the GCS, and this variable is set to (int) 1, SiteManager will generate debug output before the main

page output. See the Error Handling and Debugging section for more information.

SiteManager Root Object ($SM_siteManager)

When a project includes siteManager.inc for use in the site, a global object named $SM_siteManager is created automatically.

You will use this object to perform high level functions in your site, such as:

Loading a Module

Loading Layout Templates

Starting the Database System

Starting the Session System

Accessing the Global Configuration System

Debugging

What follows is a partial list of methods you may access from $SM_siteManager. For further documentation on these methods

and others available through $SM_siteManager, consult the SiteManager API Documentation, available on the web at

http://www.roadsend.com/siteManager

Return By ReferenceSeveral methods in the SiteManager system return values by reference: you must use the reference

assignment operator ( =& ) as in the examples shown in order to configure and use the objects returned

properly. For more information on this, see the PHP documentation: References Explained

(http://php.net/manual/en/language.references.php)

loadSite Method

loadSite($file)

Call this method to load in local configuration settings for your site. This is usually done in admin/common.inc See the next

section, Global Configuration System, for more information on this. Also, have a look at the example common.inc in

skeletonSite/admin/ directory. Note, you may call this more than once to load multiple configuration files.

Note: The tag in this file must match the $SM_siteID you define in admin/common.inc!

The configuration files will be cached if caching is turned on.

13


14/70


loadModule Method

&loadModule($moduleFile, $moduleName=)

Call this method when you wish to load and create an instance of a module. See the Directive Script and Module sections for more

information on why and when you would want to do this. This function will look through your module paths (as defined in the

Global Config System) for the file named $moduleFile (automatically adding a ".mod" extension). If the actual class name of the

module is different from the file name of the module, you must specify its name in $moduleName. For example, if the module file

name youre loading is testModule.mod, but the module class is myTestModule, you must use the following command:

$module =& $SM_siteManager->loadModule(testModule,myTestModule);

If you wish to load a module thats contained in the file testModule, and the class name is also named testModule, you may

use simply:

$module =& $SM_siteManager->loadModule(testModule);

The one exception to this rule are modules that are prefixed with "SM_". These modules are part of the SiteManager package, such

as "SM_rawHTML". The file is located in /modules/rawHTML.mod, but the class name is SM_rawHTML. Normally you

would have to solve this discrepancy by using both parameters of loadModule(), but in this case, it will find and load them correctly

without. For example, to use the SM_rawHTML module you need simply:

$htmlMod =& $SM_siteManager->loadModule(rawHTML);

See the Module System section and example scripts for more information.

includeModule Method

includeModule($moduleFile)

Call this method when you wish to load a modules definition, but not create an instance of it. This is generally used when you

need a modules definition available because you are extending it to create a new module.See the Module System section for information on Extending Modules.

rootTemplate Method

&rootTemplate($fName)

Call this method to set the root HTML layout template for use. It will search the template paths (as defined in the Global Config

System) for the template file $fName (automatically adding .tpt extension for you)

Example:

$rootTemplate =& $SM_siteManager->rootTemplate(basicTemplate);

The root template may also be a CodePlate. See the Template System section and example scripts for more information.

loadTemplate Method

&loadTemplate($fName)

14


15/70


Call this method to load an HTML layout template. You should only call this method directly if you plan of loading a template to

place inside of another template (see the Templates section for more information on templates within templates) or from inside amodule. Otherwise, you should be using rootTemplate() to load a single root template. This method will search template paths.

loadCodePlate Method

&loadCodePlate($fName)

Load a CodePlate for use. CodePlates are extensions of regular templates see the CodePlate section for more information. This

method will search the codePlates paths.

dbConnect Method

dbConnect()

This method sets up database connection(s) for the rest of the system to use. It will use the database settings found in the Global

Configuration System.

This method does not take parameters, nor does it return anything. It should simply be called once (usually in common.inc) to

create the database connection(s).

See the Database Connectivity section for more information.

startSessions Method

startSessions()

This method starts sessions. It should be used when you wish to keep certain variables persistent between links and forms, or to use

the member system. You almost always want to use this, and it should be called in common.inc.

See the Sessions section for more information.

addPersistent MethodaddPersistent($varName)

Use this method to specify that a variable should be kept persistent throughout the system. It should be called only after

startSessions() is called.

For example, if you would like to keep the variable "userName" persistent for a user:

$SM_siteManager->startSessions();

$SM_siteManager->addPersistent(userName);

All session-aware modules will now keep this variable intact automatically, as soon as it gets a value.

Note, you may also setup persistent variables in the Local Site Configuration file. They should be in the "pVars" SECTION see

the Global Configuration System section, or the testSite/admin/config/localConfig.xsm example file for more

information. Depending on your session configuration, the variable type of the persistent variable value can be any valid PHP type

(string, int, array, object, etc). See the Sessions section for more information.

15


16/70


completePage Method

completePage()

This method should be the last method called in a Directive Script. It runs all modules, collects their output, and inserts it into the

templates.

See the Directive Script section for more information, or look at the example scripts in skeletonSite/ and testSite/

directories.

fatalDebugPage Method

fatalDebugPage()

This method will generate a very informative debug page. It should be called in place of completePage() ie, AFTER all

modules have been added and configured.

Instead of showing the final HTML output as completePage() does, it will show all information on how the page WOULD have

been generated. That is, it will list all Global Configuration data, what templates are in use, which modules are loaded, how themodules are configured, what SmartForms are in use in these modules, and how the SmartForms are configured.

This function should not be used on live production sites.

Global Configuration System

SiteManager uses (at least) two configuration files to configure paths, flags, and a variety of other options. You may also add your

own sections and variables to the local configuration file, or create an entirely new one. The values in these files are the basis for the

SiteManager Global Configuration System, or GCS.

GLOBAL settings are the default settings that will be used for all sites that use SiteManager. If a configuration value requested for

a particular SITEID doesnt exist, the GLOBAL setting will be used instead (if found).

When siteManager.inc is included, the GLOBAL settings are read in by the root $SM_siteManager object. It reads it into an

SM_config object accessible through $SM_siteManager->siteConfig.LOCAL settings are read from a file in the sites admin/config directory of every site. The main file is usually

localConfig.xsm but is definable in common.inc If you add other XSM configuration files, they should also be located in the

admin/config directory.

admin/common.inc will generally tell $SM_siteManager to read in the LOCAL settings using the

$SM_siteManager->loadSite() method. At least one call to loadSite() should be made - but you may load as many local

configuration files as you like.

Configuration files can be cached - see the section on caching for more information.

Every site that uses SiteManager is assigned a SITEID ($SM_siteID). This ID is used by the configuration system to determine

which settings to use for this site. It is also used by the debug system when outputting errors and warnings.

$SM_siteID should be assigned in admin/common.inc BEFORE siteManager.inc is included.

SiteManager uses a custom XML file to describe configuration values. Configuration is basically a list of key/value pairs, broken

up into various sections. Section examples include:

dirs - directory settings

localization - localization settings

db - database settings

flags - misc flags

16


17/70


sessions - session settings

pVars - persistent variables

The easiest way to explain the settings is to take a look at the XML file that actually stores the variables:

This excerpt from globalConfig.xsm shows 1) how the XML structure is laid out 2) how variables are defined.

To access a variable from $SM_siteManager->siteConfig in module code, you would use one of two function calls:

getVar Method

$SM_siteManager->siteConfig->getVar($section, $name, $mergeGlobal=false, $sectionID=)

This function should be used when a single variable is required. For instance, to retrieve the main lib directory from section dirs,

you would use:

$libDir = $SM_siteManager->siteConfig->getVar(dirs,libs);

$libDir would then be a single string variable that contains the main lib directory.

Notice you can list VAR names more than once in the config file (such as the modules VAR in the example above). When this

happens, an array is created. For example, to get the two modules directories from the global config you would use:

$moduleDirs = $SM_siteManager->siteConfig->getVar(dirs,modules);

$moduleDirs is now an array of values that contains the two values listed in the configuration file.

The $mergeGlobal option is used to tell the SM_config object whether you want to just use the LOCAL settings, or both the

GLOBAL and LOCAL settings. Usually, you want the local settings to override global settings, but sometimes youd like to have

both. Use this option to control that. When set to TRUE, you will receive an array of values that consists of all values set for that

variable name in both GLOBAL and LOCAL context.

The $sectionID is used when a section defines itself multiple times, with different IDs. If you need to, you can use this parameter

to specify which ID youre accessing. Normally, you can leave this parameter off. See the section below regarding multiple IDs.

17


18/70


getSection Method

$SM_siteManager->siteConfig->getSection($section, $sectionID=)

Use this function to retrieve an entire section at a time. For example:

$dbSettings = $SM_siteManager->siteConfig->getSection(db);

This will return a hash that can be used in the following way:

$dbType = $dbSettings[dbType];

$pers = $dbSettings[persistent];

This function automatically merges GLOBAL and LOCAL settings.

The $sectionID is used when a section defines itself multiple times, with different IDs. If you need to, you can use this parameter

to specify which ID youre accessing. Normally, you can leave this parameter off. See the section below regarding multiple IDs.

setVar Method

You may also SET a variable through the global configuration system. This can be used to override a value read in from the config

file.

$SM_siteManager->siteConfig->setVar(dbSettings,dbType,mysql);

Note: You cannot change GLOBAL variables this way (only those LOCAL to this siteID)

Variable Replacement

To increase maintenance and portability, you can use variable replacement in all SMCONFIG files.

Once you define a VAR name/value pair, you may substitute the value in at a later time, by accessing much the same way you do as

PHP variables. This is the way the globalConfig.xsm and localConfig.xsm files are done in the "dirs" SECTION:

You could use this feature in the following way:

18


19/70


By default, variable substitution only works for variables defined within the current SECTION. To reference a variable from

another section, use the format:

In addition, if you try to use a variable that wasnt defined beforehand in this file, it will automatically attempt to substitute the

current global PHP value of that variable. that means you can substitute in any PHP or server environment variable. You can also

use an associative array (hash) in this context. For example:

... etc

Section IDs

It is possible for SECTIONs to be defined multiple times, if you specify an additional attribute (id). You may then either 1)

Specify a sectionID when accessing that section (or a variable in the section), in which case you would receive only the value from

the variable in the sectionID you requested or 2) Dont specify a sectionID, in which case you would receive the value of the

variable you requested from all IDs, merged into one array (so that it appeared that there was only one section with multiple

variables specified with the same name).

This is used, for example, by the db section to define multiple database connections:

If youre not accessing a section with multiple ids, you dont have to worry about this feature (leave that parameter blank when

calling getVar() or getSection())

19


20/70


SM_Object Base Class

Several SiteManager objects extend the SM_object base class.

This class gives a set of methods used for a common configuration system, database access, session access, language independence,

and caching.

All classes that extend this class receive the follow methods. Check the SiteManager API for more information on how to use them.

addDirective($key, $val) - add a key/value pair configuration directive

configure($cDir) -

configure the object all at once with an array of key/values

loadConfig($configFile) - load configuration data from XML file

loadLanguage($langFile) - load language independent text definition XML file

dumpInfo() - debug class info dump

debugLog($msg) - add text to the class debug log

getClassLog() - return output of class debug log

getText($id) - get a string of text by a language independent id

saveSerial($file, $prefix, &$data) - cache PHP data to the SiteManager cache directory

loadSerial($file, $prefix, &$data) -

load cached PHP data from SiteManager cache directory

They also include the following class variables:

$directive. $directive is a standard associative array ie, a list of key/value pairs. It is used to configure the object.

addDirective(), configure(), and loadConfig() all work to setup this array.

Therefore, any object that inherits this class, such as SM_modules, can be configured through:

$module->addDirective(key,value);

This system is used extensively throughout SiteManager, and we recommend using it as an alternative to class variables when

creating modules and other code. There are benefits to doing so:

1. Its easier to create reusable code, because classes that have several parent classes are easier to maintain and configure

2. Common, expandable system for defining a configuration scheme for objects

3. Key/value pairs can be loaded from an XML file using built in methods

4. You can pass and receive directives easily from other objects that descend from SM_object

$dbH. This variable is a reference to the current database handle. This is used by the module system, SmartForms, etc. as a

common way to access the default database connection.

$dbHL. This variable is a hash of all available database connections, indexed by the connection ID. If database support is on, there

should be at least one entry with the index default. See the Database Connectivity section for more information on using this.

$sessionH. This variable is a reference to the current session manager, if available. Its is an object of type SM_session. See

Session Management section for more information.

$classLog. This variable is an array that contains a list of debug messages for the class. It is populated with theSM_object::debugLog() method, and displayed with the SM_object::getClassLog() method.

$liText. This variable is a multidimensional hash that stores different translations of text the object will use for output. It has two

keys: [$locale][$textID]. It is populated with the SM_object::loadLanguage() method, which reads information from an XML

file. You should not access this directly, however use the getText() method instead.

20


21/70


Internationalization Support

All SM_object descendants (include Modules, SmartForm entities, etc) include support for internationalization - currently, the

ability to support multiple languages for output.

This is done by loading an XML based language description file. The file is organized so that each block of text to be displayed is

assigned an arbitrary ID string, and then listed multiple times in the file in different language sections, translated accordingly.

The text may then be retrieved with the getText() method, in the desired (or default) language, by its ID string, and finally

written for output.

Because of the format of the XML file, translations can be added at any time, allowing for great scalability. The code need not

change at all when a translation is added, since the block of text will still be accessed by the same ID string.

For the file format of the XML language file, see Appendix B. For an explanation of using the loadLanguage() and getText()

methods, see the Module section under Multilingual Support.

Directive ScriptsDirective scripts are the high level link between Modules and Templates.

They are described here so that as you go through the Modules and Template section, you can better understand the parts they play.

A directive script is an actual "page". It will be the script that the webserver loads first when an URL is accessed.

The directive script is generally very short - in fact, as a general rule, you want to do as little logic here as possible. Its job is to:

1. Include the sites common.inc, which in turn sets up the configuration for this site and includes the SiteManager libraries

2. Load the modules to be included in this page

3. Configure the modules

4. Load the template(s) or CodePlate(s) to be used for this page

5. Add the modules to the correct areas in the correct order

6. Output the final page

Generally, depending on the amount of configuration to be done to the modules, this can be done in 10-15 lines of code.

When the command is given to "run" the page and output it, the following happens:

1. All modules run through their configuration routines (moduleConfig())

2. All modules run through their "think" routines ( moduleThink())

3. HTML and JavaScript output is collected from each module

4. The output from the modules is placed in the proper areas in the template

A sample, annotated directive script follows (yes this is the entire page):


22/70


$mod1 =& $SM_siteManager->loadModule(rawHTML,SM_rawHTML);

// configure the module

$mod1->addDirective(output,Hello World);

// create root template. notice, returns a reference!!

$layout1 =& $SM_siteManager->rootTemplate("basicTemplate");

// add our module to area areaOne

$layout1->addModule($mod1, "areaOne");

// finish display

$SM_siteManager->completePage();

?>

Modules

Overview

Modules are pieces of code that get executed so that their output is placed into a template. All modules are extended from the same

base class, and have a common structure.

The base class for all objects is SM_module

Extending this class to create a module gives that object several important features:

1. It allows the new object to be added to a template or codePlate, where its output will be added into an area of the template

2. It sets up the object to receive input from SmartForms and other modules

3. It allows the object to create and use a SmartForm

4. It allows JavaScript code to be taken from this module and included with the main JavaScript output section of the templatethis module will show up in

5. It allows code to use the database and session systems available through SiteManager

All modules, upon creation, are assigned a Module Prefix. This prefix is used by the system to differentiate between modules. It is

used, for example, to avoid variable naming conflicts when using modules that configure for themselves variables of the same

name. The module prefix is used behind the scenes, and generally should not have to be referenced at all.

There is only one required method that must be implemented for the module to work:

moduleThink() - the "brains" of the module

Although not required, generally a module will also implement:

moduleConfig() - configure the module

moduleConfig MethodFor a module to be reusable in different contexts, it should be able to change its output and/or the way it looks when it outputs on

the fly. This means it needs to be configurable at run time through directive scripts (pages). Enter the moduleConfig() method.

22


23/70


One important difference between moduleConfig() and moduleThink() is that the moduleConfig() method is automatically

run when a module is loaded through $SM_siteManager->loadModule(), and the moduleThink() method generally isnt rununtil $SM_siteManager->completePage() is called. This allows the user to re-configure any defaults that were defined in

moduleConfig() before running the actual module.

There are three main configuration options to be done in moduleConfig(). Of course, the module designer may do any

configuration code they need in this space whats important is that this function is executed BEFORE the moduleThink()

function.

Here is a sample moduleConfig() method:

function moduleConfig() {

// load base configuration files

$this->loadConfig("moduleSettings"); // load some directives from XML file

// directives

// these are defined and overridden by DIRECTIVE SCRIPTS

$this->addDirective(tableName,); // table name to operate on$this->addDirective(maxVisibleSize,30); // max size of a form element (default)

$this->addDirective(dataField,); // field to operate with (primary key)

$this->addDirective(siteName,Test Site); // site name

// variables this module will use for configuration (these are all made up and arbitrary)

// thee are setup by GET and POST vars

$this->addInVar(widgetType,0); // which widget type should we use?

$this->addInVar(format,basic); // which "format" to use

// styles we will use in this module

$this->addStyle(linkText); // style used when outputting HTTP links

$this->addStyle(baseText); // style used for plain text

// if this module requires database functionality,

// check for a proper connection

if (!isset($this->dbH)) {SM_fatalErrorPage("this module requires a database connec-

tion, which wasnt present!");

}

}

Directives. Often a module designer wishes to let the user configure how the module should act, such as whether it should output

in a table, whether it should be run in "advanced" or "basic" mode, whether it should end the script after a form loads or transfer to

another page, etc (all arbitrary examples). These settings are done through the $directive variable and addDirective()

method.

Setting a directive involves using the functionality inherited from SM_object. For example, to add a directive to a module:

$mod1->addDirective(siteName,Test Site);

Using a directive in the module code is as easy as referencing the $directive hash variable. For example, the code:

$this->say("Welcome to {$this->directive[siteName]}!");

23


24/70


is much more reusable in a module than hard-coding:

$this->say("Welcome to Test Site!");

It allows others to use the module and configure it without ever having to look at the internals of the way it works.

You may also use the loadConfig() method inherited from SM_object. It allows you to have an external file that defines

directives. If you are going to use loadConfig(), you should call this first in moduleConfig(), so that later addDirectives

will override those loaded in the external config file.

Using loadConfig(), you can setup certain directives that ALL modules should use such as "tableBorder" or other cosmetic

options. Then, simply call loadConfig() in each of your modules. This way you only have to define those options in one place,

and when they need to change, you can change them all in one place. See the SM_object section for more information on

loadConfig()

Tip: Directives are different from INVARS (described below) in that they are meant to be configured and overridden by a

programmer who is using the module to create a page.

inVars. If the module is to take any input (ie, from HTTP_POST_VARS of HTTP_GET_VARS) it must declare which variables it

will be looking for using the class variable $inVar and method addInVar()

It must declare inVars for several reasons:

SiteManager will be able to check the inVar for correct typeness. This allows SiteManager to (for example) make sure the integer

variable youre expecting in variable foo wasnt actually passed as a string. This is a good security measure when youre

taking a integer variable that will be used as an index in an SQL query, and you want to make sure someone isnt intentionally

making the value a string of SQL commands.

SiteManager will be able to check for conflicts with other modules in the page. If you happen to be using two modules with the

same inVar, but they are meant for different uses, SiteManager can warn you

SiteManager will be able to keep variables from different modules who werent designed to work with each in tact. This allows

you to place modules into a page without the modules worrying about passing variables they werent designed to know about.

You access persistent session variables from your module by declaring an inVar with the same name as the declared persistent.

You can access SmartForm variables passed from your forms in your module.

For example, if a module is expecting a "widget type" to be passed to it, through the "widgetType" variable such as:

http://localhost/testScript.php?widgetType=5

then it should declare that it will use this variable in moduleConfig():

$this->addInVar(widgetType,0,int);

The second parameter is the default value to use, if one wasnt passed to the script. If this parameter is left blank, the default value

is blank.

The optional third parameter tells SiteManager that widgetType should be a number. If the script is called and widgetType is set,

but its actually a string value, SiteManager will not let the script load. This is a security measure.

Also see the section below about Propagating InVars.

Note: Variables passed to scripts should NOT be accessed directly, as in:

global $widgetType;

- o r -

24


25/70


$HTTP_GET_VARS[widgetType];

The example above is incorrect- use the getVar() function as follows:

$widgetType = $this->getVar(widgetType);

Again, using this system lets the module system handle naming conflicts, session variables, and other behind the scenes voodoo.

Tip: INVARS are different from Directives in that they are meant to be variables that change based on how the script was

accessed, ie they get setup either through GET or POST variables passed to the script, or through session code.

Styles. In order to promote re-usability, and module should be able to output itself in a manner thats configurable without

touching the internals of the module.

One way to do this is by using CSS Style Sheets when outputting HTML. This allows a user to use the module and change the way

it looks simply by defining certain style sheet elements in their template. This way, they never have to touch the module code.

All styles to be used in a module should be declared, in much the same way as INVARS, but with the addStyle() method:

$this->addStyle(headingText); // style used when outputting section headings

$this->addStyle(linkText); // style used when outputting HTTP links

A module has a hash called $style. It contains a key/value pair that links two properties:

1. Internally named style sheet element

2. Externally named style sheet element

This is done so that the module can reference a particular style sheet element name that may change later, when the module is

configured. For example, if the module is to output a text or a link:

$this->say(Test Link);

$this->getStyle and $this->say reference the internal name of the style but later on, when the module is configured, the actual

style sheet name it outputs may change. For example, then the user configures the variable in the Directive Script (page), they may

wish to change "headingText" to be "boldRed", which is what they have defined in their style sheet:

$mod1->setStyle(headingText,boldRed);

$this->say("Section One: Test Information","headingText");

When the module is run the following is displayed: Section One: Test Information"

moduleThink Method

The required method to implement for a module is called moduleThink(). This method is what gives the module functionality.

Here is a simple example:

function moduleThink() {

25


26/70


// output whats contained in the directive output

$this->say($this->directive[output]);

}

When this module is run, it will buffer output. NO MODULE SHOULD EVER USE echo or print! This is because the module

must save its output for later when it will be placed into the correct area of the template.

WarningA Module should never echo or print output!

Instead of echoing output, use the method say() or saybr() thats part of the SM_module class:

$this->saybr("This is module output");

DO NOT use:

echo "This is module output";

All output in SiteManager is buffered, so you wont see echoed output unless you have Debugging output turned on. See the

Debugging section for more information on that.

Another (special) method of output is the sayJS() function. This is used for the module to output JavaScript code. It requires its

own function so that the JavaScript code shows up in the correct JavaScript area of the template. sayJS() works just like say().

You do NOT have to include any tags when using sayJS, the module system does this for you. See the Template

section for more information on this.

Other than that, the moduleThink() code may do anything youd like. You of course have the full power of PHP and all its

extensions at your disposal. Here is a list of SiteManager helper functions that will be useful when designing modules. See the

SiteManager API for more information on each method.

$this->say(); - use to buffer module output

$this->saybr(); - use to buffer module output with a
tag

$this->sayJS(); - use to buffer JavaScript output

$this->getVar(); - use to access a variable declared as an INVAR

$this->newSmartForm(); - create a new SmartForm for this module (see SmartForm section)

$this->getStyle(); - retrieve a style sheet element name

$this->getText(); - use to retrieve language independent text by ID

$this->directive[]; - retrieve a directive

canModuleLoad Method

Sometimes a site designer will want to load and display a module only under certain circumstances - for example, if a particular

variable was passed to the page. One way to do this is add logic code either to a directive script or a CodePlate that decides when to

load and add the module to the template.

26


27/70


It can be more convenient, however, to always load the module in the directive script, and let the module itself decide whether it

should display itself or not. This is a more portable method, as the module has full access to inVars and session variables, and youwont need to worry about adding display logic to every directive script you use this module in.

For a module to decide not to display, it must implement the canModuleLoad() method. If this method exists, it is run after

moduleConfig, but before moduleThink. This allows it to be configured through directives, and allows access to declared inVars.

The method should return either true or false. If it returns true, the module will run its moduleThink() code as normal. If it

returns false, the moduleThink code will notrun, and no output will be displayed by the module.

Here is an example (module excerpt):

/**

* configure the module. run before moduleThink

*/


// Directives

$this->addDirective(tableBorder,1);

$this->addDirective(tableBgColor,#eeeeee);

$this->addInVar(menuID,0,int);

}

/**

*

* only load if our inVar is set to 8

*

*/

function canModuleLoad() {

return ($this->getVar(menuID) == 8);

}

In this example, the module would only display itself if menuID were passed to the script, it was a number, and the value was 8.

Database Connectivity

Accessing a database in the modules is easy. When you extend the SM_module class, a class variable called $dbH is available

automatically. Either this variable is NULL, in which case there is currently no available database connection, or it is a reference to

the current default database connection. There is no need to make a connection by hand in a module.

If your module requires access to a database, you should check for connectivity in moduleConfig, using:

// if this module requires database functionality,

// check for a proper connection

if (!isset($this->dbH)) {

SM_fatalErrorPage("this module requires a database connec-

tion, which wasnt present!");}

27


28/70


Then, in moduleThink(), you are guaranteed access to the database. You may use $this->dbH as a normal PEAR Database

object. For example:

$SQL = "SELECT * FROM testTable";

$rh = $this->dbH->simpleQuery($SQL);

if (DB::isError($rh)) {

SM_debugLog($SQL,$this);

SM_fatalErrorPage("There was a problem with the query!");

}

while ($rr = $this->dbH->fetchRow($rh)) {

$this->say($rr[firstName].
);

}

$this->dbH->freeResult($rh);

Youve now just written a data aware module that can be used in any SiteManager system, and on any database system that PEAR

supports.

Multiple Database Connections. SiteManager has the ability to have more than one active database connection. $this->dbH is

always a pointer to the default database connection. If you wish to access a database connection handle other than the default, you

use the $this->dbHL hash, and reference the database ID, such as:

$SQL = "SELECT * FROM testTable";

$rh = $this->dbHL[secondary]->simpleQuery($SQL);

if (DB::isError($rh)) {

SM_debugLog($SQL,$this);

SM_fatalErrorPage("There was a problem with the query!");

}

while ($rr = $this->dbHL[secondary]->fetchRow($rh)) {

$this->say($rr[firstName].
);

}

$this->dbHL[secondary]->freeResult($rh);

See the Database Connectivity section for more information on setting up and accessing multiple database connections.

Session Functionality

Much like the database functionality, session functionality is contained automatically in the variable $this->sessionH

To make your modules "session-aware", you should use the hLink() method.

hLink($link, $text, $class=, $extra=)

hLink() will make a link to $link, around text $text. It will use a style of$class (from your $this->style

array) if specified. $extra will place extra text into the tag if you need it (such as TARGET="")

hLink will automatically append the current session variables onto your link (even if $link contains variables of its own).

It should be used in the following way:

$this->say($this->hLink("newScript.php?user=1","Link To New Script"));

Using hLink() instead of hard coded $this->say("


29/70


Take a look at the /modules directory for some examples of modules.

Accessing Persistent Variables. To access a variable that has been declared as persistent variables with the session system, simplydeclare an inVar with the same variable name as the persistent variable. Then, use $this->getVar() method to retrieve it. Using

this method, you can access strings, arrays, objects and any other variable you would like to keep persistent.

Module within Modules

Inside of the moduleThink() method, you can of course use any standard PHP functions, as well as function libraries you may

have written and included. But another way to increase the re-usability of your code is to write SiteManager modules that are to be

used specifically inside of other modules. The benefits of doing this instead of writing normal functions and including them is that

you receive the same Global Configuration System abilities as other modules, plus you have access to the current Database and

Session handles.

To use a module within a module:

// declare $SM_siteManager to be global

global $SM_siteManager;

// load the module through SM_siteManager like normal (make sure youve

// defined it as global though!)

$testModule = $SM_siteManager->loadModule("testModule");

// call the run() method on the module

$tOutput = $testModule->run();

// gather its output, and say() it into your own

$this->say($tOutput);

$this->sayJS($testModule->getJS());

The code for the module to be loaded can be any normal module code. However, when designing a module to be run within other

modules, make sure you turn off the outputInTable directive otherwise youll get two module tables inside of one module.

// (in sub-modules moduleConfig())

$this->addDirective(outputInTable,false);

Extending Your Modules

All modules extend the base SM_module class, which gives them a common framework for integrating into SiteManager sites. To

promote reuse of code, you can also extend your own modules to provide other modules with common functionality.

To do this, you create a normal SiteManager module, but instead of extending SM_module, you will extend your new base module

(which of course extends SM_module itself).


30/70



// base think code, possibly blank

}

function extraFunction() {

// extra base functionality

}

}

class extendedModule extends testModule {


// override custom base modules think function

// call function from base module

$this->extraFunction();

}

}

?>

Normally, however, you wouldnt want to keep both the base module and the extended module in the same file. You might put the

base module in a file called testModule.mod and the extended module in a file called extendedModule.mod - both in your

sites modules/ directory.

Note that when you do this, you must make sure that when you define your extended module, it already knows the definition of

your base module. You do this through the $SM_siteManager->includeModule() method. It will search your current module

paths for the base module you specify. Note, however, you must declared $SM_siteManager global first.

You can now call $SM_siteManager->loadModule() on your extended module in the normal way.

For an example of extending modules, look in the testSite/admin/modules directory at base.mod and extendedMod.mod

30


31/70


preThinkList and postThinkList

A common way to use extended modules is to create a base module that defines how the module will look once its output is

complete (ie, by wrapping it in a table of some sort), and then extending that module every time you would like the functionality of

a module to wrapped in the same table.

This is common in Portal systems, for example, where all the modules might be in a common table layout: a table header the same

color, a title in the header, and button in the header for "closing" that module.

One way to do this is create a module with two extra methods: moduleHeader() and moduleFooter(). The header would

contain the code to output the top of the common TABLE, the footer would contain the code to close it.

If you extended this module, you could then call $this->moduleHeader() at the start of your moduleThink(), and

$this->moduleFooter() at the end. This would wrap the output of your extended module in the table from the base module,

keeping the two separate which will aid maintenance and modularity.

However, the module designer who is extending the base module is still required to know which methods to call at the start and end

of his moduleThink() to make the module output correctly. If the designer of the extended module is not the same as the designer

of the base module, it might not be clear which methods he is to use.

To solve this problem, SiteManager allows the designer of the base module to have certain class methods run automatically when

the module is extended. In the above example, the designer of the base module would have moduleHeader() run automatically

before moduleThink(), and moduleFooter() run automatically AFTER moduleThink(). This allows the designer of the

extended module to not have to call them at all, and therefore not have to worry about which methods he needs to call the make his

extended module output properly.

SiteManager handles this through two arrays: preThinkList and postThinkList. They are simply an array of strings. The

values of the strings should be the function names to run before and after moduleThink() (respectively). The functions do not take

arguments, and will be run in the order they were added to the array. You can add as many functions to each list as you would like.

Here is an example of a base module that illustrates the example above:

/**

* a base module. extends base SM_module class.

*

*/class baseMod extends SM_module {

/**


*/


// configure which methods will be run automatically

$this->preThinkList[] = moduleHeader;

$this->postThinkList[] = moduleFooter;

}

/**

* this function contains the core functionality entry point for the module.

*/


// virtual - this will be written by the extending module designer

31


32/70


}

// this function will run automatically before moduleThink()

// the designer of the extended module need not call it directly

function moduleHeader() {

// notice you can use directives here that may be setup by the extended module

$this->say("{$this-

>directive[title]}");

}

// this function will run automatically after moduleThink()

// the designer of the extended module need not call it directly

function moduleFooter() {

$this->say("");

}

}

and here is the extended class

/**

* an extended module. extends baseMod class.

*

*/

// include base module

global $SM_siteManager;

$SM_siteManager->includeModule(baseMod);

class extendedMod extends baseMod {

/**


*/


// configure

parent::moduleConfig();

// other configuration here...

$this->directive[title] = Extended Module Test;

}

/**

* this function contains the core functionality entry point for the module.

*/


$this->saybr("This output is being displayed by the extended mod-

ule. It is wrapped in a table generated by the base module");

32


33/70


$this->saybr("The generation of the table was done automatically through preThin-

kList and postThinkList methods");

}

}

InVar Propagation (read-write inVars)

While designing modules you may find it necessary to have not only "read-only" type inVars, where your module is simply reading

a value that was passed to the script, but also "read-write" type inVars, where you want your module to not only read the current

value of a variable, but make that value available to other modules on the current page.

Propagated inVars were designed so that modules placed together on a page that werent designed to work together still function

correctly. The best way to illustrate this is by example.

Say you have three modules on a page. The first one is a menu, the second is a text viewer. When you click on an item in the menu,it displays some text in the viewer on the right. The viewer module declares an inVar called "id". When you click on a menu item, it

reloads the page with the proper "id" set which the textViewer uses to display the correct content.

Now, the third module isnt related to the modules above. Its a login box with a SmartForm. Since its a SmartForm it has to reload

itself, which means it will post to PHP_SELF.

So lets say someone comes to this page, and selects an item in the menu, with id=5. Now, once they do that, they decide to login, so

they type in their username and password in the third module, and hit submit.

Now heres the trouble. They had previously clicked on a menu item, which set id to 5. But the login module doesnt know

anything about "id", it wasnt built to use it, and therefore wouldnt have added it as a hidden on its own. So once they click

submit, the id variable would have been erased, and the user would no longer be on the page they selected from the menu. Lets

say they typed the wrong password, so the page reloads a couple times. It would be nice if id stayed 5 the whole time because the

SmartForm added a hidden for the id variable, even though the login module doesnt know anything about it.

This is what propagated (ie, "read-write") inVars do. The login SmartForm will automatically add a hidden called id and set it to

5, because it knew that another module on the same page was using this inVar.

There is a configuration variable propagateInVarDefault in the flags section of the GCS. This determines the default

settings of when inVars will propagate. If this is set to false, you must explicitly set which inVars to propagate. If this is set to true,

all inVars will propagate by default and you must explicitly tell SiteManager which NOT to propagate. You most likely want to

keep the default setting ofnotpropagating by default, and only turning on propagation for specific variables that should.

You can also turn set inVar propagation either for a whole module, or on an inVar by inVar basis. Consult the Module section or the

API docs for more information.

Multilingual Support

Because the Internet is a global network, your sites (and modules) need the ability to display in multiple languages. SiteManager

handles this by allowing you to define and load an XML language description file.

The language XML file format is described in Appendix B. Once you have a language file defined, you load it into your module

with the loadLanguage() method, which i

sitemanager manual 2.2.x

Documents