Configuration

The application is configured via one (or more) configuration file(s), which are parsed by the WCMFInifileParser class. The configuration parameters are defined by key-value pairs as they are used in the ini file format. The application interprets values, which are enclosed in curly brackets ({}), as arrays. Related parameters are arranged in sections.

Note:

Please note, that the framework interprets paths - if not explicitly indicated otherwise - as relative to the BASE path, which is defined in /application/base_dir.php. This is the root directory of /wcmf and /application by default.

• Action Keys
• Configuration for individual users
• Configuration file sections
• Example of a configuration file

Action Keys

An important concept of the application's configuration is that of Action Keys. An action key describes the state of the application together with the action to be performed next. The state, which the application is in, results from the current controller and the context, in which it is executed. Controllers must exist as classes, whereas contexts and actions can be defined freely. They must only be taken care of in the controllers and if necessary transported between the views (as form data, see also Programming the application, Programming the views).
The format of the action keys is the following:

controller?context?action 

In the configuration file an action key has the controller assigned, which should be executed next if the action key is valid by the application's current state and the user action or the return value of the current controller (see also Application flow).
Since parts of the action key can be omitted in the definition, an algorithm has to choose, which action key fits a given value triplet. This algorithm is implemented in the method WCMFInifileParser::getBestActionKey. In this method the InifileParser searches in the configuration file for the a list of combinations successively and ends the search when it found one. After that the controller, which is assigned to that combination, is executed. The order of the combinations is the following:

 1. controller?context?action
 2. controller??action
 3. controller?context?
 4. ?context?action
 5. ??action
 6. controller??
 7. ?context? 

As a rule of thumb the action key which describes the state of the application the most accurate is favoured.
Frequent examples are:

Always execute the SaveController when action save is selected, no matter which state the application is in:

??save = SaveController 

Always execute the ProjektController when the context is project as long as no action is specified, return to the ProjektController respectively from all controllers, which have no specific action assigned upon termination:

?project? = ProjectController 

If no matching action key can be found, the ActionMapper tries to execute the last Controller that had a view attached again. This can save some typing. For example you don't need to configure an action key for the ok return action of SaveController, if you always want to execute the Controller afterwards, from which the save action was initiated.

Configuration for individual users

In the table user of the database scheme (see also Database scheme) each user can have her own configuration file assigned. This will be loaded after the standard configuration (config.ini) and extends its settings. If two keys have the same name the one from the user configuration overwrites the standard one. Using the roleconfig configuration section, you can easily asign configuration files to groups (see below).

Configuration file sections

The following sections are known to the framework classes. Whatever parameter is necessary for the application can be defined in further sections and can be read using the methods of the WCMFIniFileParser.

[config]

This section refers to the configuration files. The following keys are known to the framework::

 include          = array with configuration files
                  ; allows the inclusion of further configuration files
                  ; (Included values don't overwrite the current)
                  ; used in: class.InifileParser.php
 hiddenSections   = array with sections
                  ; allows the hiding of sections in the admintool
                  ; used in: class.InifileParser.php
 readonlySections = array with sections
                  ; allows the protection of sections in the admintool
                  ; used in: class.InifileParser.php 
 

[classmapping]

Since Controller, PersistenceMapper and other classes in the configuration file's sections are only labeled with their classnames, the framework needs information, in which files the class definitions can be found. In the section classmapping therefore a corresponding definition file for each class is given.

classname = path_to/classfilename 

[typemapping]

The relation between domain classes and their PersistenceMappers (see Data storage) is set in the section typemapping. A * as key means that all types, which are not specified, will be handled by the assigned PersistenceMapper. The PersistenceFacade uses these information to find the appropriate PersistenceMapper classes for the domain classes.

type = mapperClass 

[implementation]

In some cases the framework offers different implementations for abstract classes. At the moment this refers to basic services, which access the data storage (database, XML), e.g. AuthUser. The implementation, which should be used by the framework can be specified in this section. For the following classes an implementation can be chosen:

 LockManager = LockManagerRDB|BusyLockManager|NullLockManager
 UserManager = UserManagerRDB|UserManagerXML
 User = UserRDB|UserXML
 Role = RoleRDB|RoleXML
 UserRole = NMUserRole
 View = View|NullView
 ControlRenderer = DefaultControlRenderer
 ValueRenderer = DefaultValueRenderer
 HTMLFormat = HTMLFormat
 JSONFormat = JSONFormat
 SOAPFormat = SOAPFormat 

Furthermore this mechanism allows developers to provide own implementations of the abstract classes.

[initparams]

Since some classes require specific parameters in their constructors (e.g. database connection), these parameters can be grouped in sections (e.g. [database]) and referenced in the section initparams. The keys are the classnames and the values the corresponding parameter sections. The key-value pairs of the parameter section will be passed as associative array to the constructor upon creation of the objects.

class = initsection 

[converter]

In this section DataConverters for types are configured (see Data storage):

type = converterClass 

[actionmapping]

In the section actionmapping the actual application flow is defined. This is achieved by defining the transition from one controller to the next.
The key is an action key (see Action Keys), which clearly describes the state the application is in before the transition. The value sets the next controller to execute. The ActionMapper uses this information to determine which Controller is executed next.

controllerA?context?action = controllerB 

[views]

For each controller a view can be defined dependent on its context and action, which is described by its Smarty template (.tpl file). In the section views each action key can have a view template assigned (see Action Keys). The controller uses this information to determine its view.

controllerA?context?action = view 

[authorization]

The Authorization is based on action keys (see Action Keys), whereby the following actions can be defined by the individual parts of the key:

 controller?context?action ; an action in the application flow
 type?context?action       ; an action on a domain class (read, modify, delete, create)
 oid?context?action        ; an action on a domain object (read, modify, delete, create) 

To each of these actions different roles can be assigned (comma separated), for which a permission is granted (+) or denied (-). The role * stands for all roles.
If a permission is not explicitly granted, it is considered as denied. For not listed Aktion Keys the decision is made by the _defaultPolicy of the AuthUser. The RightsManager uses this information to authorize an AuthUser for an action.

The following code shows an example, where the creation of Category instances is only allowed for users having the administrators role:

Category??create = -authors +administrators 

[roleconfig]

Allows auto assignment of an additional configuration file for different user roles. If a user is added to a listed role, then the given configuration file will be automatically assigned by the UserManager (see also Configuration for individual users).

rolename = configurationfile 

For example if users of the administrators role should always use the admin.ini configuration file you could add the following entry:

administrators = admin.ini 

[cms]

This section refers to the general application configuration. The following keys are known to the framework::

 applicationTitle = application title
                  ; specifies the title which appears in the default application
                  ; used in: class.Controller.php, locale.php
 rootTypes        = array of domain classes
                  ; declaration of types, which don't have parent types to allow them to be created
                  ; on the top level of the default application
                  ; used in: class.DisplayController.php, class.TreeViewController.php, 
                  ;               class.XMLExportController.php, graph.php
 anonymous        = 0|1
                  ; indicates, if the user must authenticate himself upon application start.
                  ; If the value is 1 the rights management is also disabled.
                  ; used in: class.LoginController.php, class.RightsManager.php
 exportDir        = path (relative to main.php !)
                  ; sets the root directory for the export of static pages
                  ; used in: class.PageExportController.php
 htmlBaseDir      = path (relative to main.php !)
                  ; sets the root directory for the html output
                  ; used in: class.LinkConverter.php
 backupDir        = path (relative to main.php !)
                  ; sets the root directory for backups
                  ; used in: class.BackupController.php
 libDir           = path (relative to main.php !)
                  ; sets the root directory of the framework
                  ; used in: class.TreeViewController.php, resource.lib.php, class.FormUtil.php
 localeDir        = path (relative to main.php !)
                  ; sets the language directory of the application
                  ; used in: main.php, class.I18nUtil.php, po2array.php
 logDBActions     = 0|1
                  ; specifies, whether database access should be logged in the logfile
                  ; used in: main.php
 logSQL           = 0|1
                  ; specifies, whether the logging of the database layer is activated
                  ; ADOdb then logs all access in the table adodb_logsql
                  ; used in: class.NodeRDBMapper.php, class.NodeToSingleTableMapper.php, 
                  ;               class.LockManagerRDB.php, class.AuthUserRDB.php, class.UserManagerRDB.php
 logExecuteTime   = 0|1
                  ; specifies, whether to log the time each controller needs to execute
                  ; used in: class.ActionMapper.php
 debugView        = 0|1
                  ; specifies, whether Smarty should create debug output in a popup window
                  ; used in: class.Controller.php
 language         = language code (e.g. en_EN)
                  ; specifies the application's language (see Message::get)
                  ; used in: main.php, locale.php
 usegettext       = 0|1
                  ; specifies, whether the function gettext should be used for the localization of the
                  ; application (see Message::get).
                  ; used in: class.Message.php
 locking          = 0|1
                  ; specifies, whether data is locked when it's opened by another user
                  ; used in: class.LockManager.php
 

[htmlform]

The definition of the input controls, that are used in the application, is done in Smarty templates (see DefaultControlRenderer). In this section the templates are assigned to control names.
The following input controls are already defined by the framework:

 text
 textarea
 password
 select
 radio
 checkbox
 file
 fileex
 filebrowser
 linkbrowser
 fckeditor
 date 

Furthermore the following keys are known to the framework:

 maxFileSize             = number
                         ; specifies the maximum size of files to upload (in bytes)
                         ; used in: class.FormUtil.php, class.NodeUtil.php, 
                                         class.SaveController.php, class.FileUtil.php
 inputFieldNameDelimiter = char
                         ; specifies the separator, which is used for creation of inputfield names
                         ; (e.g. separator "-": "value-1-name-Author:0")
                         ; used in: class.SaveController.php, class.NodeUtil.php, 
                                         class.FormUtil.php
 

[htmldisplay]

The definition of the value display types, that are used in the application, is done in Smarty templates (see DefaultValueRenderer). In this section the templates are assigned to value type names.
The following value types are already defined by the framework:

 text
 image 

[smarty]

The smarty section contains configuration parameters for the Smarty Template Engine.

 compileCheck = 0|1
                ; specifies, whether Smarty should test for modifications
                ; in the templates upon each call
                ; used in: class.Controller.php
 templateDir  = path (relative to main.php !)
                ; specifies the smarty directory (the paths /smarty/templates_c
                ; and in case of caching=1 /smarty/cache must exist in that directory)
                ; used in: class.Controller.php
 caching = 0|1
                ; specifies, whether Smarty should use caching
                ; in case of a cms application caching is a good alternative to exporting 
                ; static pages
                ; used in: class.Controller.php
 cacheLifetime = -1|number of seconds
                ; specifies, the lifetime of the Smarty cache in seconds
                ; the value is ignored if caching is not enabled
                ; used in: class.Controller.php
 

[media]

In this section settings for the upload of media files are specified.

 imgWidth  = array of a number and 0|1
           ; sets - if specified - the width of an upload image
           ; the second parameter specifies if the value must be matched exactly (1)
           ; or if it is a maximum (0)
           ; e.g. {625, 0}
           ; used in: class.SaveController.php
 imgHeight = array of a number and 0|1
           ; sets - if specified - the height of an upload image
           ; the second parameter specifies if the value must be matched exactly (1)
           ; or if it is a maximum (0)
           ; e.g. {625, 1}
           ; used in: class.SaveController.php
 uploadDir = path (relative to main.php !)
           ; specifies the directory, into which the SaveController uploads media files
           ; used in: class.SaveController.php, class.FormUtil.php
 

Example of a configuration file

 
 [config]
 
 [classmapping]
 BackupController = wcmf/application/controller/admintool/class.BackupController.php
 AdminController = wcmf/application/controller/admintool/class.AdminController.php
 ConfigController = wcmf/application/controller/admintool/class.ConfigController.php
 PrincipalController = wcmf/application/controller/admintool/class.PrincipalController.php
 EditRightsController = wcmf/application/controller/admintool/class.EditRightsController.php
 MySQLBackupController = wcmf/application/controller/admintool/class.MySQLBackupController.php
 BatchController = wcmf/application/controller/class.BatchController.php
 LongTaskController = wcmf/application/controller/class.LongTaskController.php
 DeleteController = wcmf/application/controller/class.DeleteController.php
 DisplayController = wcmf/application/controller/class.DisplayController.php
 FailureController = wcmf/application/controller/class.FailureController.php
 InsertController = wcmf/application/controller/class.InsertController.php
 LoginController = wcmf/application/controller/class.LoginController.php
 PageExportController = wcmf/application/controller/class.PageExportController.php
 SimplePagingController = wcmf/application/controller/class.SimplePagingController.php
 SortController = wcmf/application/controller/class.SortController.php
 AssociateController = wcmf/application/controller/class.AssociateController.php
 ResourceTreeController = wcmf/application/controller/class.ResourceTreeController.php
 PagingController = wcmf/application/controller/class.PagingController.php
 SaveController = wcmf/application/controller/class.SaveController.php
 SimpleBatchController = wcmf/application/controller/class.SimpleBatchController.php
 SimpleLongTaskController = wcmf/application/controller/class.SimpleLongTaskController.php
 TreeViewController = wcmf/application/controller/class.TreeViewController.php
 ViewController = wcmf/application/controller/class.ViewController.php
 XMLExportController = wcmf/application/controller/class.XMLExportController.php
 CopyController = wcmf/application/controller/class.CopyController.php
 UserController = wcmf/application/controller/class.UserController.php
 ResourceListController = wcmf/application/controller/class.ResourceListController.php
 SearchController = wcmf/application/controller/class.SearchController.php
 SOAPController = wcmf/application/controller/class.SOAPController.php
 ChildrenListController = wcmf/application/controller/class.ChildrenListController.php
 NodeListController = wcmf/application/controller/class.NodeListController.php
 Controller = wcmf/lib/presentation/class.Controller.php
 UserRDB = application_1/include/model/wcmf/class.UserRDB.php
 UserRDBRDBMapper = application_1/include/model/wcmf/class.UserRDBRDBMapper.php
 RoleRDB = application_1/include/model/wcmf/class.RoleRDB.php
 RoleRDBRDBMapper = application_1/include/model/wcmf/class.RoleRDBRDBMapper.php
 NMUserRole = application_1/include/model/wcmf/class.NMUserRole.php
 NMUserRoleRDBMapper = application_1/include/model/wcmf/class.NMUserRoleRDBMapper.php
 Locktable = application_1/include/model/wcmf/class.Locktable.php
 LocktableRDBMapper = application_1/include/model/wcmf/class.LocktableRDBMapper.php
 Adodbseq = application_1/include/model/wcmf/class.Adodbseq.php
 AdodbseqRDBMapper = application_1/include/model/wcmf/class.AdodbseqRDBMapper.php
 LockManagerRDB = wcmf/lib/persistence/class.LockManagerRDB.php
 UserManagerRDB = wcmf/lib/security/class.UserManagerRDB.php
 View = wcmf/lib/presentation/class.View.php
 DefaultControlRenderer = wcmf/lib/presentation/class.DefaultControlRenderer.php
 DefaultValueRenderer = wcmf/lib/presentation/class.DefaultValueRenderer.php
 HTMLFormat = wcmf/lib/presentation/format/class.HTMLFormat.php
 JSONFormat = wcmf/lib/presentation/format/class.JSONFormat.php
 SOAPFormat = wcmf/lib/presentation/format/class.SOAPFormat.php

 [typemapping]
 UserRDB = UserRDBRDBMapper
 RoleRDB = RoleRDBRDBMapper
 NMUserRole = NMUserRoleRDBMapper
 Locktable = LocktableRDBMapper
 Adodbseq = AdodbseqRDBMapper
 
 [implementation]
 LockManager = LockManagerRDB
 UserManager = UserManagerRDB
 User = UserRDB
 Role = RoleRDB
 UserRole = NMUserRole
 View = View
 ControlRenderer = DefaultControlRenderer
 ValueRenderer = DefaultValueRenderer
 HTMLFormat = HTMLFormat
 JSONFormat = JSONFormat
 SOAPFormat = SOAPFormat
 
 [initparams]
 UserRDBRDBMapper = database
 RoleRDBRDBMapper = database
 NMUserRoleRDBMapper = database
 LocktableRDBMapper = database
 AdodbseqRDBMapper = database
 
 [converter]
 
 [actionmapping]
 ??fatal = FailureController
 ??delete = DeleteController
 DisplayController?? = DisplayController
 DisplayController??treeview = TreeViewController
 DisplayController??failure = FailureController
 DisplayController??definesearch = SearchController
 DisplayController??list = NodeListController
 DisplayController??edituser = UserController
 DisplayController??search = SearchController
 DisplayController??listchildren = ChildrenListController
 LoginController??ok = DisplayController
 UserController??ok = DisplayController
 ??cms = DisplayController
 ??display = DisplayController
 ??new = InsertController
 LoginController??failure = LoginController
 LoginController??dologin = LoginController
 ??login = LoginController
 ??logout = LoginController
 SimplePagingController?? = SimplePagingController
 ??sortup = SortController
 ??sortdown = SortController
 ??disassociate = AssociateController
 ??associate = AssociateController
 ResourceTreeController?? = ResourceTreeController
 ??browseresourcetree = ResourceTreeController
 ??save = SaveController
 TreeViewController?? = TreeViewController
 ??copy = CopyController
 UserController??save = UserController
 UserController?? = UserController
 ResourceListController?? = ResourceListController
 ResourceListController??delete = ResourceListController
 ??browseresources = ResourceListController
 SearchController?? = SearchController
 ??soapList = SOAPController
 ??soapCreate = SOAPController
 ??soapUpdate = SOAPController
 ??soapRead = SOAPController
 ??soapDelete = SOAPController
 ChildrenListController?? = ChildrenListController
 NodeListController?? = NodeListController
 
 [views]
 DisplayController?? = wcmf/application/views/displaynode.tpl
 FailureController?? = wcmf/application/views/displayfailure.tpl
 LoginController?? = wcmf/application/views/login.tpl
 ResourceTreeController?? = wcmf/application/views/resourcetree.tpl
 TreeViewController?? = wcmf/application/views/treeview.tpl
 UserController?? = wcmf/application/views/user.tpl
 ResourceListController?? = wcmf/application/views/resourcelist.tpl
 SearchController??definesearch = wcmf/application/views/searchpanel.tpl
 SearchController?? = wcmf/application/views/searchresult.tpl
 ChildrenListController?? = wcmf/application/views/childrenlist.tpl
 NodeListController?? = wcmf/application/views/nodelist.tpl
 
 [authorization]
 
 [roleconfig]
 administrators = admin.ini
 
 [database]
 dbType = mysql
 dbHostName = localhost
 dbName = wcmf
 dbUserName = wcmf
 dbPassword = geheim
 
 [smarty]
 templateDir = include/views/
 compileCheck = 1
 
 [cms]
 applicationTitle = DEFAULT
 localeDir = locale/
 libDir = ../wcmf/
 exportDir = ../../html/
 htmlBaseDir = ../../html/
 backupDir = backup/
 language = en_EN
 usegettext = 0
 debugView = 0
 logDBActions = 0
 logSQL = 0
 logExecuteTime = 0
 anonymous = 0
 locking = 1
 rootTypes = {}
 
 [media]
 uploadDir = ../../html/images/
 
 [htmlform]
 inputFieldNameDelimiter = -
 maxFileSize = 200000
 text = wcmf/application/views/forms/text.tpl
 textarea = wcmf/application/views/forms/textarea.tpl
 password = wcmf/application/views/forms/password.tpl
 select = wcmf/application/views/forms/select.tpl
 radio = wcmf/application/views/forms/radio.tpl
 checkbox = wcmf/application/views/forms/checkbox.tpl
 file = wcmf/application/views/forms/file.tpl
 fileex = wcmf/application/views/forms/fileex.tpl
 filebrowser = wcmf/application/views/forms/filebrowser.tpl
 linkbrowser = wcmf/application/views/forms/linkbrowser.tpl
 fckeditor = wcmf/application/views/forms/fckeditor.tpl
 
 [htmldisplay]
 text = wcmf/application/views/display/text.tpl
 image = wcmf/application/views/display/image.tpl
      
 

Back to the Overview | Previous section Points of extension | Next section Database scheme