********************************************************** manual.txt @author gERD Schaufelberger @copyright 2004/2005 Wombat Web Bench @link http://wombat.exit0.net @package wombatSite @subpackage manual ********************************************************** INTRODUCTION ============ In order to ease web-site developer's life, Wombat Web Bench implements a flexible framework which manages common tasks of dynamic web-sites. Therefore it provides a dispatcher which handles all requests and delegates them to specified extensions which are responsible for creating the content. Also Wombat is able to display HTML templates by itself (this is another, easy way suitable for static content). At the end the Wombat combines the content and displays the collection as descrribed in the site layout. It also manages basic error-management and has several debugging features. As mentioned above, Wombat is a framework - it is not a single class or file that can be included elsewhere in your code. It works the other way around: Your code runs within the framework. :-) Features --------- Basic: - rapid development: developers focus on small bits and pieces - framework wide factory for instanciating objects and including classes dynamically (Avoid juggling with references) - user defined, unlimited content areas for dynamic content - default content for each content area - versatile configuration options - XML-based configuration - cached configuration and other data - integrated session management using patSession - tolerant and robust - hopefully :-) - uses open-source libraries (pear http://pear.php.net, pat http://www.php-tools.net) - allows dynamical change of configuration values Extensions and Modules: - plenty of modules are ready to use and provide common applications (e.g. web-blog, photo-gallery, contact-form) - client specific extensions implement specialized applications. - Both, creating modules and extensions is very easy. Simple modules/extensions just inherit from the base-class and implement a single method. - Extensions/modules may use all classes etc. of the framework (or even pat- or pear-classes). - Usefull basic funktionality e.g. load (html) templates, check for reload - Some static tools to add javascript-code or debugging messages. Site Administration: - easy to use web interface for site administration - secure user handling Passwords are stored encrypted. "Secure" way to renew forgotten admin password. - create and maintain single pages - maintain site menu - WYSIWYG-like content editor (using HTMLArea ) - WYSIWYM functions of content editor that allows to insert dynamic content. - cute wombat on every page! :-) Design/Layout: - template based HTML output using patTemplate3 - allows to switch between layout-templates (eihter per page or global) Debugger: - static debugger that is available everywhere - hide system errors from visitor - nice debugging output - well, if someone designs it... Service Provider Features: - run multiple, independent sites inside the same directory - allows single site or multi-site installation - comes with make-a-like tool to maintain site setup and wombat itself Enhanced Authentication and Authorisation features: - user management (login, subscribe, logout, per-page permission) - user administration (edit/add/delete/... users/groups and maintain group-membership) - user-groups to realize rolls - user-register: automatic user registration interface that allows to insert users in default groups - configurable permissions and authorisation modules - permissions configurable per page and global - configurable "permission denied content" - extensible authorisation modules - switch of authentication handler Available Actions ----------------- - staticString Content is represented in "href" - staticTemplate "href" defines which template will be displayed - cmsHtml "href" defines the title/name of the content part to be included - loadExtension name the extension with the "href"-tag - loadModule use any wombat module to greate some dynamic content Buildin Extensions -------------------- - user authentication (wbSite::_handleLogin() ) Wombat Modules -------------- Modules are small php-classes to insert dynamic content into your site. Those modules are flexible in design and cover often requested functionality therefore they are part of the framework itself. See: module.txt Wombat Custom Extensions ------------------------ Of course, generic modules cannot satisfy all your clients requirements. Therefore Wombat comes with an interface to include your own custom code into your site. This is done by extensions. EBasicly extensions work like modules, and can be written very easily. See: extensions.txt Available Authorisation Plugins ------------------------------- - False - Null - User - Group - Userflags A more detailed documentation about the authorisation process and modules can be found in "auth.txt" and the folder "auth" Whishlist --------- - content-based caching - support for URL-rewriting (e.g. /2134345/mypage => index.php?PHPSESSID=2134345&page=mypage) - additional debugging options and messaging system (for application and development errors) - admin interface for page configuration - dynamic navigation (tree-menu?) and page-path display - multiple Database-connections - Benchmarking - Improved CMS - cmHTML: support for images, selecteable tags, ... - cmXML: Custom, featured XML editor - Media-Gallery for global storage of all kind of files (pdf, zip, images, ...) - custom authentication handler REQUEST LIFECYCLE ================= In order to work with the framework and to develop custom sites it is essntial to know how the components (of the framework) work together. The description of an example request will be used to show what happens inside the "black box" Please notice, that the following description will only cover a sample request. This should be enough, to give a basic understanding of the framework. It will not describe all the features or configuration options - please refere the other manuals. 1) Request ---------- At the beginning there is a HTTP-rquest. In this case the user typed in an URL or followed a link: http://www.yoursite.com/index.php?PHPSESSID=123456789&path=example/extensiontest The file which catches this request will look like: -----------------8<-----------------8<-----------------8<----------------- process(); ?> -----------------8<-----------------8<-----------------8<----------------- The first thing this script does is to load the factory. The factory is very important and must be included as long as you want to use the framework. Once the wbFactory is loaded and configured (with wbFactory::configure() ) you are out of the wood. wbFactory::configure() executes the file "conf/config.php" (as long as no other file is specified). This file may be used to set some configuration parameters for the factory itself (like switching to debug mode or use a different global configuration file). After that, the factory loads the global configuration from "conf/config.xml" (again, as long as no other file is specified, the factory was told NOT to load the configuration). Now the factory is set up correctly and has all the information to instanciate all kind of objects. (E.g. a database connection or template engine.) In this case the index.php instanciates a wbSite object and starts the process function. 2) wbSite->process() -------------------- The function "process" is the main processing function of the site manager. This function starts the processing of the site and runs the framework. Step by step, processing the site means: 1. read the main configuration 2. recieve all HTTP GET and POST values 3. start a session 4. select the page and load the corresponding configuration 5. handle user login (if user attempts to login) 6. run the autorisation module(s) the figure out which content's parts may be displayed 7. add some global content to the template engine 8. run through defined content parts, collect the content and insert the content into the layout 9. add additional javascript-code (if required) 10. display the HTML-output 11. append debugging output if the framework runs in debugging mode So everything is done within these 11, easy to understand steps with a little magic in steps 1 to 11. :-) Step 1 - read the configuration -------------------------------- Actually the framework-wide configuration is already read by the wbFactory (see above). In this example the wbSite will recieve the values of the configuration file "conf/config.xml" which contains the following settings: The default page is called "index" The default layout is named "page" There are three content parts defined: - title - head - maincontent Remember those parts - they become important when the framework fills those areas with dynamic content. There is a default content for each content part - in this case all three parts use the same stupid string "default content" as fallback. The authentication handler, named "Wombat" requires the flags: "approved", "enabled" and NOT "new" to login to the system. The autzorization module that will be used is called "Null" - in other words, authorization is switched off. In case of access denied (by the authorization module) the content of the parts: "title" and "maincontent" will be overwritten by the string "Permission denied". You may want to open the configuration file conf/config.xml to compare the actual values with the statements above. Step 2 - recieve all HTTP GET and POST values --------------------------------------------- Well that's easy, wbSite collects all request values from GET and POST and merge them to a single array. Forthermore the wbSite passes those variables to all extensions (site specific classes). This makes sure, that the request variables are available everywhere but still under controll of the framework. Step 3 - start a session ------------------------ Sessions are required for user login and other purposes. The wbSite automatically starts the session on every request. So, sessions are available and can be uses in every extension, module or any other part of the framework. Step 4 - select the page and load the corresponding configuration ----------------------------------------------------------------- After those global issues were done, wbSite figures out which page should be displayed. The framework supports two ways to that: The old-fashioned way reads the request-parameter: "page". Let's say, it is set to "extensiontest". That means, wbSite will now try to display a page called "extensiontest". The shiny new and improved method to select a page is using the request- parameter: "path". In our case, path is set to "example/extensiontest". Now, wbSite splits the path by "/" and knows that each word represents a named page. The page to be displayed is simply the last word. Hence, wbSite ignores everything in the path, but sets page to "extensiontest". In this stage, there is no need to bother about the rest of "path". As it does not affect the selected page. Just this for now: the path allows you to find yourself in the site menu. As every node in a tree can be identified by the path how to get there. But, this is a different topic, let's go back to wbSite. Now the framework tries to load the page configuration, this is supposed to be in: "conf/pages/extensiontest.xml" If this file does not exists, the default page "index" will be used. Anyway, the page configuration will overwrite the global configuration. In this case, the file "extensiontest.xml" defines the content for the parts: "title", "head" and "maicontent". This will overwrite the default content for those parts. Besides that, there are no other specifications made - everything else still remain as defined in global scope. Step 5 - handle user login -------------------------- If a user sends a login-request, the framework has to handle the login without interfering normal processing. Therefore the login/logout process must be handled before the actual page content will be processed (and before any output is sent). In this case the authentication handler "Wombat" will be started. If the user request a login or logout, those actions will be performed. Please note, that logging in or out may result in new session-id! Please refere patSession's manual about security and session handling. Otherwise the authentication handler won't do anything special. Still, it has to answer the questiomn whether a user is logged in or not. Step 6 - run authorisation module -------------------------------- Now it is time to check wheter the visitor of this page has the permission to view the content at all! Therefore the configured authorisation module will be asked, whether access is granted. In this case, the module "Null" is asked - This module will always return a positive result. In other words, the visitor is allowed to view the content of this page. Step 7 - add some global content to the template engine ------------------------------------------------------- There are some global variables and values that are important for every page. For example the session-name and the session-id, and, of course, the URL of to the dispatcher skript ("index.php" - in our case). Those variables will be added in the global scope of the template engine - this makes it very easy to insert hyperlinks to different pages of the framework. Step 8 - run through defined content parts ------------------------------------------ In this step, the actually content for each part will be created. Following the example, the gsSite will step through each defined part: "title", "head" and "maincontent". For each part, it will just follow the "action"-command of the configuration. For the part "title" the action is defined as "loadExtension". Therefore, the framework knows, that it has to load an extension to recieve the HTML content for this part. The name of the extension is defined in the "href" parameter - which is "Test" in this case. That means, the wbSite will instanciate the class "wbExtension_Text" which is located in "Text.php" in the extension folder. Actually, wbSite does not instanciate or include any classes - it delegates those tasks to the factory. To recieve the content of the part "title" it will just call the function "getTitle()" which return a (HTML) string. The next part is called "head". The defined action for this part is "loadExtension", as well. The extension is named "Text", again, but in this thim the function "getHead()" will be called. Those steps repeat for the part "maincontent", too. Step 9 - add additional javascript-code --------------------------------------- Sometimes the include of additional javascript files or code is necessary. This can be managed by wbSite, as well. This feature can be very handy while developing custom extensions or modules. Step 10 - display the HTML-output --------------------------------- After collecting the content for each defined part, wbSite populates the layout template and displays the whole page. Step 11 - append debugging output --------------------------------- If the framework runs in debugging mode, wbSite will automatically appends the debugger's output at the end of the page. Besides Notices, Warnings and Errors, the debuger output also contains some handy information about the build process of the page as well as some benchmarks. Furthermore the debugging messages will get more important as soon as you start to develop your own extension or module.