Quicknavi |
|
Configuration
1. Introduction
To be able to implement reusable applications the aid of configuration is used in some places. To
have a generic "interface" for the loading of configuration files in the Windows INI style the
configurationManager was integrated into the framework. To improve handling of configuration
files the additional wrapper method is __getConfiguration() was included in the class
coreObject. This offers the ability in classes inheriting from coreObject to load
configurations in that easy way. Because the configurationManager is initialized and
accessed in the singleton mode each configuration is internally cached by the module. Hence, accessing
one single configuration file frequently is no bottleneck. As are already mentioned the configuration
files are build up like Windows INI files and contain sections and key-value-pairs. A typical INI
file is showed by the following code example:
[Section1]
Param1 = "Value1"
Param2 = "Value2"
...
[Section2]
Param1 = "Value1"
Param2 = "Value2"
...
The sections and key value pairs contained in the configuration file are freely eligible by the
developer. Merely the structure of the already existing components are given and the used sections
and configuration keys are well-defined.
2. Naming convention for paths and files
With the name of the files and paths some basic conditions are to be followed. To make applications
or modules (=software parts which can be used in several applications) reusable for different projects
a configuration file is composed of different "parts":
-
Namespace:
The namespace is a path to a basic folder that contains all configuration file of a specific
module or class. The namespace often corresponds with the namespace of the module or class.
All configuration files are located under the folder apps/config to separate
configuration from the program code.
-
Context:
To realize reusabity, another differentiating factor is introduced. Each configuration file path
is extended by the current context of the application. This introduces the possibility to include
module A in website B or C without changing the progranm code but only by adding another
configuration file under the current context of project C.
-
Environment:
The third distinguishing feature is the enviroment the modul is executed in. This patameter
renders possible to create configuration files for different environments such as test server or
production environment. The environment variable is therefor handled by the registry and can be
manipulated in the bootstrap file if desired. For more details, please have a look at the
basics chapter, section 3.3.
-
Name:
The name of the configuration file should be self-explanatory. The file must be equipped with the
prefix {ENVIRONMENT} und the suffix .ini. If the developer wants to store his
configuration params in a file called myconfig and the environment variable was
not modified, the configurationManager expects the file to be named DEFAULT_myconfig.ini.
The context of an application can be influenced while creating the page controller or front controller
instances:
2.1. Context while using the front controller
$fC = &Singleton::getInstance('Frontcontroller');
$fC->set('Context','sites::mysite');
$fC->start('sites::mysite::pres::templates','mywebsite');
Here the internal variable "Context" is supplied by the explicit call of the set() method
after creating the front controller instance. The context will be "transmitted" to other objects of
the DOM tree of the presentation layer or to service objects of the business and data layer
automatically.
2.2. Context while using the page controller
By the use of the page controller the context is implicitly filled with the first argument of the
call of the method loadDesign(). Besides, the context can also be set manually by adding
$Page->set('Context','sites::myspecialsite');
to the following code lines:
$Page = new Page('mywebsite');
$Page->loadDesign('sites::mysite','pres/templates/mywebsite');
echo $Page->transform();
Now the context of the application is "sites::mysite". Setting the context manually it receives the
value "sites::myspecialsite".
Let us assume, that we have the following index.php file:
$Page = new Page('mywebsite');
$Page->set('Context','sites::myapp');
$Page->loadDesign('sites::mysite::pres::templates','mywebsite');
echo $Page->transform();
If in any module configurationManager is called by
$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
it would expect the configuration file to reside in the folder
/apps/config/modules/mymodule/sites/myapp/
and to be named
DEFAULT_mymoduleconfig.ini
In case of non existing configuration files, the developer is noticed by the configurationManager.
Additionally a error message is printed that contains the expected configuration file so that this
error can be corrected by the engineer.
3. Service objects
Because configurations are often used in the business and data layer, the context must be confessed
to these both layers of the application. By the use of the front controller the topical context is
given to every action and these are thus able to call service objects of the business layer with
this context. The page controller provides the context to every node of the DOM tree. If a document
controller likes to generate a business component, or get a reference on this, the methods
__getServiceObject() or __getAndInitServiceObject() must always be used. Both
functions ensure that every service object receives the right context. Implementing details and
documentation of the parameters are found in the API documentation. As a rule it is adequate to create
a service layer like this:
$GuestbookID = '1';
$oGuestbookManager = &$this->__getServiceObject('modules::guestbook::biz','guestbookManager');
$Guestbook = $oGuestbookManager->loadGuestbook($GuestbookID);
To get a initialized instance of the desired serice layer please use
$GuestbookID = '1';
$oGuestbookManager = &$this->__getAndInitServiceObject(
'modules::guestbook::biz',
'guestbookManager',
$GuestbookID
);
$Guestbook = $oGuestbookManager->loadGuestbook();
The last example premises, that the guestbookManager has the init() function
implemented.
4. Reading configuration
To read the values of a configuration several methods of the central configuration object are
available. These are getConfiguration(), getSection() and getValue().
With these the complete configuration, a single section or the value of a section can be returned
either.
Example:
We assume a configuration file with the following content was created:
[Section1]
Key1 = "Value1"
Key2 = "Value2"
Key3 = "Value3"
[Section2]
Key1 = "Value1"
Key2 = "Value2"
Key3 = "Value3"
So the developer can fetch the content of the configuration file by placing the code
$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo printObject($Config->getConfiguration());
in any component of the application. The "echo" results in
Array
(
[Section1] => Array
(
[Key1] => Value1
[Key2] => Value2
[Key3] => Value3
)
[Section2] => Array
(
[Key1] => Value1
[Key2] => Value2
[Key3] => Value3
)
)
Withe the use of
$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo printObject($Config->getSection('Section2'));
the array
Array
(
[Section2] => Array
(
[Key1] => Value1
[Key2] => Value2
[Key3] => Value3
)
)
is printed and
$Config = &$this->__getConfiguration('modules::mymodule','mymoduleconfig');
echo $Config->getValue('Section1','Key2');
displays
Value2
to the screen. The function printObject() is only used for cosmetic reasons. The values can
be directly used in the application code as desired.
5. Case study: multi language applications
To be able to implement multilanguage applications the language is held in every GUI object of the
framework. Thus the topically used language is always known and partial trees can also be equipped
with different languages if desired. The realisation of the multilingual facility in application
is provided by the tag <html:getstring /> and
<template:getstring />. These read in the language-dependent contents from
a configuration file specified in the tag attributes and print them to template files or HTML
templates.
To realize this two conditions must be fulfilled::
5.1. Creation of a config file
As described in chapter 2, please take care of the current context of the application when creating
the configuration file. Under the acceptance, that the topically discussed application is stored
under the namespace
/apps/modules/mymodule/
and the current context is sites::myapp, the language dependent configuration file
must be storend under the folder
/apps/modules/mymodule/sites/myapp/
The filename should be
DEFAULT_mymodule_lang.ini
whereas mymodule is replaced by the real name of the module. The file's content can
be filled out freely by the developers. It must be considered that the sections of the configuration
file must be named with two letter ISO language codes. For details please refer to
http://de.wikipedia.org/../ISO-L%C3%A4ndercode
or to
http://www.iso.org/../list-en1.html.
The following example shows a common example:
[de]
Form.Name = "Ihr Name"
Form.EMail = "Ihre E-Mail-Adresse"
Form.Subject = "Betreff"
..
[en]
Form.Name = "Your name"
Form.EMail = "Your email adress"
Form.Subject = "Subject"
..
5.2. Display of language-dependent texts
To provide language-dependent texts two alternatives exist in the framework design. On the one hand
the XML tags <html:getstring /> and <template:getstring />
can be used to display language-dependent content in template files or HTML templates. On the other
hand the method __getConfiguration() of the configurationManager component can be
uses directly (e.g. setting the display name of a form button). First the integration of the
configuration file via XML tags described on top should be explained:
To provide language dependent areas the template
<html:template name="MyTemplate">
[..]
Ihr Name: <template:placeholder name="Name" />
<br />
Ihre E-Mail-Adresse: <template:placeholder name="EMail" />
<br />
[..]
</html:template>
must be changed to
<html:template name="MyTemplate">
[..]
<template:getstring namespace="modules::mymodule" config="mymodule_lang" entry="Form.Name" />:
<template:placeholder name="Name" />
<br />
<template:getstring namespace="modules::mymodule" config="mymodule_lang" entry="Form.EMail" />:
<template:placeholder name="EMail" />
<br />
[..]
</html:template>
Here the statical texts are exchanged with XML tags that print the values configuration keys
"Form.Name" and "Form.EMail". If any language-dependent values are needed within a document controller
(e.g. for email dipatching) these values can be gathered by placing the following code in your
controller
$Config = &$this->__getConfiguration('modules::mymodule','mymodule_lang');
echo '<br />Form.Name: '.$Config->getValue($this->__Language,'Form.Name');
echo '<br />Form.EMail: '.$Config->getValue($this->__Language,'Form.EMail');
echo '<br />Form.Subject: '.$Config->getValue($this->__Language,'Form.Subject');
The echo provided here is just placed there to demonstrate the functionality. In real life
applications, the values printed out are used to fill place holders in templates such as
<html:template name="MyTemplate">
<div class="FormHeader">
<template:placeholder name="FormHeader" />
</div>
</html:template>
by writing down the code
// Read configuration
$Config = &$this->__getConfiguration('modules::mymodule','mymodule_lang');
// Get the reference of the template
$Template__MyTemplate = &$this->__getTemplate('MyTemplate');
// Fill placeholder "FormHeader"
$Template__MyTemplate->setPlaceHolder('FormHeader',$Config->getValue($this->__Language,'Form.Name'));
More examples can be seen in the guestbook tutorial.
Comments
Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.
|
