**********************************************************

    config/page.txt
    
    $Id$
    
    @author gERD Schaufelberger <gerd@exit0.net>
    @copyright 2004/2005 Wombat Web Bench
    @link http://wombat.exit0.net
    @package wombatSite
    @subpackage manual

**********************************************************

PAGE CONFIGURATION
==================
While the global configuration unlikely need to be changed once Wombat is 
up and running, the page definitions may change during the livetime of the 
website. Therefore the configuration for each page is located in a separate 
file in the subfolder "pages" in your configuration folder. 

As described in manual.txt the request-parameter "path", respective "page" will
be used to resolve the page's name. This name must have an corresponding xml-file
in the pages directory. For example, if the user requests a page called "about",
Wombat tries to load the page definitions from "pages/about.xml". If this failes
(for example, the file does not exist),  Wombat will try to load the page
definition for the default page. (If this fails, you are in trouble! - This will
result in an fatal error.)


Common Page
-----------
The following listing shows a common page definition. For this page, the 
defined content parts "title", "head" and "maincontent" have specific actions, 
to create the content. 

Besides that, there are no further parameters set. Hence the default 
authentication methods are used and so on...

-----------------8<-----------------8<-----------------8<-----------------
<configuration>
    <xinc href="/defines.xml" once="yes" />
    
    <page:page>
        <page:content>
            <part name="menu">
                <page:action>loadModule</page:action>
                <page:href>TreeMenu</page:href>
            </part>
            <part name="title">
                <page:action>staticString</page:action>
                <page:href>index title</page:href>
            </part>
            <part name="head">
                <page:action>staticString</page:action>
                <page:href>index head</page:href>
            </part>
            <part name="maincontent">
                <page:action>staticString</page:action>
                <page:href>index content</page:href>
            </part>
        </page:content>
    </page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

Using default content
---------------------
Lazy people may not want to define each content part for each page. Those 
people may find the default content useful. This feature allows you to skip 
parts as long as you want to display the default content. E.g. the module
TreeMenu display the site menu - it makes sense to display the site menu on
every page.

-----------------8<-----------------8<-----------------8<-----------------
<configuration>
    <xinc href="/defines.xml" once="yes" />
    <page:page>
        <page:content>
            <part name="head">
                <page:action>staticString</page:action>
                <page:href>This is not default</page:href>
            </part>
        </page:content>
    </page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

Action And Href
---------------
For each part there are two required tags <page:action> and <page:href>. While
"action" tells wbSite how to get the actual content from, "href" describes the
source of the content. 

The current version of wbSite is capable to process five different actions:
staticSting, staticTemplate, cmsHtml, loadModule and loadExtension. 

staticString:
This is the most simple action. It means, the actual content is just a bunch of
characters. Because this is so simple, those characters are defined in "href". 

Example:
-----------------8<-----------------8<-----------------8<-----------------
            <part name="head">
                <page:action>staticString</page:action>
                <page:href>That's easy</page:href>
            </part>
-----------------8<-----------------8<-----------------8<-----------------

staticTemplate:
This action tells wbSite to load the template defined in "href" from the static
template folder. This is very useful to include html. Of course, the loaded
files are still templates and therefore not static at all. That means, all
global template variables are available. 

Example:
-----------------8<-----------------8<-----------------8<-----------------
            <part name="maincontent">
                <page:action>staticTemplate</page:action>
                <page:href>nice</page:href>
            </part>
-----------------8<-----------------8<-----------------8<-----------------
Following the example above, wbSite will load templates from
templates/static/nice.tmpl and insert the content of the template named
"maincontent".

cmsHtml:
In order to use the build-in CMS (including online HTML-editor) the action
cmsHtml has to be used. In such a case, href defines the container - where to
store the HTML content. (Please note, that the container will be initilazed
automatically with "Blank content" when it is used the first time.)

To change the actual content, the CMS-Browser must be used.

The benefit of cmsHtml is that end-users (site administrators) can use the
CMS-Browser to maintain content with a WYSIWYG-like editor.

Example:
-----------------8<-----------------8<-----------------8<-----------------
            <part name="maincontent">
                <page:action>cmsHtml</page:action>
                <page:href>another_container</page:href>
            </part>
-----------------8<-----------------8<-----------------8<-----------------

loadModule:
Modules provide "real" dynamic content. Dynamic in a sence, that modules are
php-classes that implement the method getHtml(). Modules are part of Wombat,
hence they are common web-applications like weblogs (Blogger), photo-galleriey
(Gallery) or contact-forms (Contact). 

Usually modules use templates to format their output in the site's look and
feel. 

Example:
-----------------8<-----------------8<-----------------8<-----------------
            <part name="maincontent">
                <page:action>loadModule</page:action>
                <page:href>Blogger</page:href>
            </part>
-----------------8<-----------------8<-----------------8<-----------------

loadExtension:
Extensions behave like modules in many ways. While modules suit general needs,
extensions are client specific applications. Hence they are not part of Wombat.
Still, Wombat can run those extensions the recieve the content they provide. 
Using extensions works pretty much the same way as modules.

Example:
-----------------8<-----------------8<-----------------8<-----------------
            <part name="maincontent">
                <page:action>loadExtension</page:action>
                <page:href>OpalMiner</page:href>
            </part>
-----------------8<-----------------8<-----------------8<-----------------


Parameter
---------
Client specific extensions as well as modules classes to provide dynamic
content. Furthermore, modules should be very flexible - otherwise they are not
reusable (and not worth to be called module). To increse flexibility (without
guessing) most modules accept configuration parameter. Even of the should
provide a reasonable set of fallback values for those parameters, at least some
parameter are likely to be adjusted.

Wombat provides an easy way to pass those parameters to the called module or
extension. All that have to be done, is to add the <page:params> tag which can
hold as many parameter in <page:param> tags into the corresponding part.

Example:
-----------------8<-----------------8<-----------------8<-----------------
<configuration>
    <xinc href="/defines.xml" once="yes" />
    <page:page>
        <page:content>
            <part name="head">
                <page:action>loadModule</page:action>
                <page:href>Gallery</page:href>
				<page:params>
				    <page:param name="gallery">mining</page:param>
				    <page:param name="mode">picture</page:param>
				    <page:param name="picture">random</page:param>
				</page:params>
            </part>
            <part name="maincontent">
                <page:action>loadModule</page:action>
                <page:href>Gallery</page:href>
				<page:params>
				    <page:param name="gallery">mining</page:param>
				    <page:param name="mode">album</page:param>
				</page:params>
            </part>
        </page:content>
    </page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------
The example above will call the same module "Gallery" twice. First for "head"
and second for "maincontent" - this time with different parmeters! 


More than content
-----------------
Of course, specifying the content is main reason of the page definitions. 
Furthermore, some other configuration parameter may be overwritten in a page 
wide scope. 

These are: 
 - layout
 - auth 

Thangeing the layout means to load a different template to display the page
content. To do so, just create multiple template files, each representing a
specified layout. This feature is very handy, if some pages should be displayed
in a small popup-window instead as "full page" for example.

The following page definition selects the layout "page_popup". This forces
wbSite to load a templatefile called "templates/page_popup.tmpl".
-----------------8<-----------------8<-----------------8<-----------------
<configuration>
    <xinc href="/defines.xml" once="yes" />
    <page:page>
        <layout>page_popup</layout>
    
        <page:content>
            <!-- define the content here -->
        </page:content>
    </page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

The authorization options allow to provide special content for special people.
As in global configuration, wbSite asks the authorization module whether the
current user may view this page. 

The example below uses the module "Group". Therefore, only "German" people may
see the very secret content of this page!
-----------------8<-----------------8<-----------------8<-----------------
<configuration>
    <xinc href="/defines.xml" once="yes" />
    <page:page>
        <auth>
            <auth:module>Group</auth:module>
            <auth:param>German</auth:param>
        </auth>
    
        <page:content>
            <!-- define the secret content here -->
        </page:content>
    </page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------