********************************************************** config/global.txt $Id$ @author gERD Schaufelberger @copyright 2004/2005 Wombat Web Bench @link http://wombat.exit0.net @package wombatSite @subpackage manual ********************************************************** GLOBAL CONFIGURATION ===================== On of the benfits of the Wombat is, that almost everything is configurable and can be adjusted to the needs of the specific site. On the other hand, these massive amount of configuration options may scare (new) users to use the Wombat at all. The good news is, that the basic framework runs out of the box! So, you don't need a database or even user-authetication. Therefore you don't have to care about all those configuration options - the default should be fine! BASIC CONFIGURATION =================== The basic configuration is split in two parts. This is done to solve the hen-egg-conflict. In case of the Wombat, the wbFactory is the required hen to get eggs from. Before producing eggs, wbFactory has to be set up properly, after that, the wbFactory is able to process even XML files to read more complex configuration from. Setup the hen ------------- The wbFactory provides a static interface to recieve instances of all the objects you need. As mentioned above, the factory must be configured, as well. For example the wbFactory is able to include classes - therefore it needs some information where those classes can be found. It also needs to know whether it runs in debugging-mode or not. Also there are even more options, that you may want to adjust. Luckily, wbFactory usually is able to figure out all vital configuration parameters automatically (and comes with a reasonable default set of parameters). As the wbFactory is a class that only provides static functions, there is no constructor. Therefore you need to call wbFactory::configure(). This function tries to include the first configuration file: config.php, located in the configuration directory ("/conf/config.php"). Typically the framework is started like this: -----------------8<-----------------8<-----------------8<----------------- process(); ?> -----------------8<-----------------8<-----------------8<----------------- As mentioned before, wbFactory is not able to process XML files before calling "configure()". Therefore the configuration file for the first step is just a native PHP file. The following listing shows a typical configuration file. As it shows, there is not much beside comments! in fact, only a single command will be executed: wbFactory::setParam( 'debug', 1 ); (As you might guess, this turn on the debugging mode) If the site does not meant to run in debugging mode, this file can be empty! file: wb.php -----------------8<-----------------8<-----------------8<----------------- -----------------8<-----------------8<-----------------8<----------------- As this example shows, the static function setParam() is used to change the configuration parameters during runtime. After processing this file, the configure-function starts the debugger and error handler and loads the main configuration value - usually stored in "/conf/config.xml". From this point you are able to recieve eggs from the hen - or in other words, to use the wbFactory. Main configuration ------------------ For better maintainability, all other configuration files are stored in XML format. This allows you, on the one hand to store nested and related information and still uses plain text files. The cost of it is, of course, that the XML-files have to be transformed to something more suitable for PHP-programms: arrays. The Wombat uses patConfiguration to do this job. Using patConfiguration also allows you to define your own tags (and namespaces) which makes the system even more flexible. Furthermore, patConfiguration also caches the processed XML files, which almost eliminates the disadvantages of XML files. The following source code shows a common configuration file. Please note, that the definition of the XML-tags is completely configurable, as well! In this case, patConfiguration loads the definitions from "/conf/defines.xml". (See the Project homepage of patConfiguration at http://www.php-tools.net for more information, also there are some PHP files in the test-folder that may dump the array representation of the configuration.) file: config.xml -----------------8<-----------------8<-----------------8<----------------- localhost/wombat/htdoc mysql://wombat:wombat123@localhost/wombat tables.xml index page error C wombatsite C de_DE fr_FR loadModule TreeMenu staticString default content test staticString default content staticString default content Null enabled,approved,!new Null staticString Permission denied staticString Permission denied -----------------8<-----------------8<-----------------8<----------------- As mentioned, some configuration values are not used in a basic setup (e.g. the database connection) or usually don't need to be changed (layout, errortemplate). Furthermore most sited don't need user authentication or logins - therefore, just use the authorization handler to "Null" and everything works fine, unless you don't expect to be able to login... (see authentication.txt for details). Define content parts -------------------- In order to adjust Wombat to fit the client's needs, the content parts usually have to be adjusted. Therefore the configuration parameter "content" is used (in the example the tag ""). This configuration option makes it possible to define as many content parts as you want. The definition of those parts will be used to populate these areas with dynamic content. In other words, the Wombat walks through all those parts (here: "menu", "title", "head" and "maincontent"), fetches the content for this part and inserts it at the corresponding place in the layout template. Besides the global content which is available all over the page (see manual.txt: REQUEST LIFECYCLE, Step 7) the rest of the page is like a static html page. The definition of the parts also includes an action and href (and optional some parameters). These are the content defaults - they define the content that will be inserted if there is no page (see config/page.txt) specific content.