Upload
marcosdecarvalho
View
227
Download
0
Embed Size (px)
Citation preview
7/29/2019 SiteManager Manual 2.2.x
1/70
Roadsend PHP SiteManager
Shannon WeyrickRoadsend, Inc.
Jon MichelRoadsend, Inc.
7/29/2019 SiteManager Manual 2.2.x
2/70
Roadsend PHP SiteManager
by Shannon Weyrick and Jon Michel
2.2.x Production Series Edition
Copyright 2001 by Roadsend, Inc.
7/29/2019 SiteManager Manual 2.2.x
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
7/29/2019 SiteManager Manual 2.2.x
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
7/29/2019 SiteManager Manual 2.2.x
5/70
SMOBJECT .................................................................................................................................................................67
SMCONFIG.................................................................................................................................................................67SMRESOURCE...........................................................................................................................................................67
Tag Descriptions ..............................................................................................................................................68
5
7/29/2019 SiteManager Manual 2.2.x
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/29/2019 SiteManager Manual 2.2.x
7/70
Chapter 1. Introduction
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
7/29/2019 SiteManager Manual 2.2.x
8/70
Chapter 1. Introduction
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
7/29/2019 SiteManager Manual 2.2.x
9/70
Chapter 1. Introduction
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
7/29/2019 SiteManager Manual 2.2.x
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
7/29/2019 SiteManager Manual 2.2.x
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
7/29/2019 SiteManager Manual 2.2.x
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
7/29/2019 SiteManager Manual 2.2.x
13/70
Chapter 3. SiteManager Fundamentals
$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
7/29/2019 SiteManager Manual 2.2.x
14/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
15/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
16/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
17/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
18/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
19/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
20/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
21/70
Chapter 3. SiteManager Fundamentals
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):
7/29/2019 SiteManager Manual 2.2.x
22/70
Chapter 3. SiteManager Fundamentals
$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
7/29/2019 SiteManager Manual 2.2.x
23/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
24/70
Chapter 3. SiteManager Fundamentals
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
7/29/2019 SiteManager Manual 2.2.x
25/70
Chapter 3. SiteManager Fundamentals
$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
7/29/2019 SiteManager Manual 2.2.x
26/70
Chapter 3. SiteManager Fundamentals
// 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
7/29/2019 SiteManager Manual 2.2.x
27/70
Chapter 3. SiteManager Fundamentals
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
*/
function moduleConfig() {
// 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
7/29/2019 SiteManager Manual 2.2.x
28/70
Chapter 3. SiteManager Fundamentals
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("
7/29/2019 SiteManager Manual 2.2.x
29/70
Chapter 3. SiteManager Fundamentals
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).
7/29/2019 SiteManager Manual 2.2.x
30/70
Chapter 3. SiteManager Fundamentals
function moduleThink() {
// base think code, possibly blank
}
function extraFunction() {
// extra base functionality
}
}
class extendedModule extends testModule {
function moduleThink() {
// 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
7/29/2019 SiteManager Manual 2.2.x
31/70
Chapter 3. SiteManager Fundamentals
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 the module. run before moduleThink
*/
function moduleConfig() {
// configure which methods will be run automatically
$this->preThinkList[] = moduleHeader;
$this->postThinkList[] = moduleFooter;
}
/**
* this function contains the core functionality entry point for the module.
*/
function moduleThink() {
// virtual - this will be written by the extending module designer
31
7/29/2019 SiteManager Manual 2.2.x
32/70
Chapter 3. SiteManager Fundamentals
}
// 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 the module. run before moduleThink
*/
function moduleConfig() {
// configure
parent::moduleConfig();
// other configuration here...
$this->directive[title] = Extended Module Test;
}
/**
* this function contains the core functionality entry point for the module.
*/
function moduleThink() {
$this->saybr("This output is being displayed by the extended mod-
ule. It is wrapped in a table generated by the base module");
32
7/29/2019 SiteManager Manual 2.2.x
33/70
Chapter 3. SiteManager Fundamentals
$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