Forrest Config

[Anil Ramnanan <li...@peppersauce.org>]

Here is some documentation of the config session. I have included the 
first part of the discussion which concerns the configuration. I did not 
document the part of the discussion about the processing yet.

Suggestions for new Forrest Configuration
============================

Forrest Instance
-----------------
This is a single instance of forrest. A single instance can have 
multiple project associated with it. A single Forrest instance can have 
multiple Forrest Projects.
  - Instance configuration File
      - Webapp Configuration
      - Pointer to File with sub sites


Forrest Projects
-----------------
A single Forrest Project contains the configurations specific to that 
project.
It should contain:
- Project Name
- site/
    - LocationMap
    - Site.xml
    - Tabs.xml
- Can point to a sub site which is another Forrest Project
- Forrest Project Configuration (forrest.xml)
    - Points to Plugins
    - Points to Skins/Views/Themes for particular project
    - Points to locationmap
      (Basically the bits that are project specific from forrest.properties
      and skinconf.xml)


Use Case
=========

Here is a use case for the new configuration using Apache sites.


            Single Forrest Instance
                            |
    -------------------------------------------------
    |                        |                    |                |
    (apache.org)    (Jakarta)    (XML)        (Forrest)
    Forrest        Forrest        Forrest        Forrest
    Project        Project        Project        Project
                        |
    --------------------------------
    |                    |                |
    (Sub site)    (Sub site)    (Sub site)
    Forrest        Forrest        Forrest
    Project        Project        Project



How the current configuration changes
=====================================
Here is how the current configuration files can be changed.

forrest.properties
------------------
Forrest Properties can be split up with general configurations places in 
the Forrest Instance and configurations specific to the project places 
in each project's Project Configuration file e.g. Skins and plugins to 
be used.

skinconf.xml
------------------
Skinconf.xml configurations has skin configurations that can be done 
with views. Configurations that are not on views can go into the Project 
Configuration.

status.xml
----------
Status can be treated as a content file instead of a configuration. The 
file can be located anywhere and placed in the locationmap. The Project 
Info Plugin can also be extended to pull status from status.xml or other 
status files.


sitemap.xmap
-------------
Project Sitemap should become a Block to be loaded dynamically by 
cocoon. Using a block means that the system does not need to be restarted.

Classes
-------------
Classes will be in the block


Conf
-------------
This is relevant to the generation of static sites. Not sure how to 
handle this.

Resources
-------------
There can be a Resources location for the default layout for a fresh 
site. The locationmap can be used to customise the resources after.

Site
-------------
Here is where you store the locationmap of the content, the site.xml and 
tabs.xml
- LocationMap
- Site.xml
- Tabs.xml

Re: Forrest Config

[Ross Gardler <rg...@apache.org>]

Anil Ramnanan wrote:
> Suggestions for new Forrest Configuration
> ============================

All config files should be XML and should have a defined schema to 
facilitate the creation of editors. I propose that someone (Anil?) 
creates these DTD's as this discussion proceeds and keeps them updated 
in SVN. It would also be useful to maintain a document there describing 
the outcomes of this thread as they come about (I'd recommend using HTML 
so that we can easily view it in SVN)

This will be a tough task to do at the end of the discussion but if we 
start doing it as the discussion progresses and we make changes as 
necessary we will have a nice history of changes in SVN. We need not 
worry about getting it write first time, we just need to worry about 
capturing the discussion in a concise form. When discussion dies down we 
can use the DTD's to verify what we have done.

Please be sure to put copious comments from this thread into the DTD. 
This will allow cross referencing with the discussion when we try to 
work out why we did it a particular way.

The DTD's should go into FORREST_HOME/whiteboard/config/schema

> 
> Forrest Instance
> -----------------
> This is a single instance of forrest. A single instance can have 
> multiple project associated with it. 
>  - Instance configuration File
>      - Webapp Configuration

what do we find in here?

>      - Pointer to File with sub sites

Would this file really be separate? Can we not have the location of 
subsites defined within the same config file?

---

I see the instance config file as being like the httpd.conf file of 
Apache HTTPD server. This would make the sub sites analogous to 
<virtualHost> in httpd.conf

The forrest instance should also define defaults for the sub sites in 
the same way httpd.xonf does. These defaults can be used to serve an 
admin application from the instance. This app would do things like 
deploy a new site, broken links reporting, log access etc.

If we think of the forrest instance having its own site then the forrest 
instance will use the same config file as the sub-sites since all 
subsites can each have a sub-site.

Furthermore, using the exact same file would allow sub-sites to be their 
own instance. That is, if Apache serves Jakarta (with sub-sites) and 
Incubator (with sub-sites) we will need an instance file for Apache, one 
for Jakarta and one for Incubator.

Using the same file format for both the instance and sub-sites means 
that Jakarta and Incubator can be built independently of the main Apache 
site (important for testing).

---
We need names for these files. I'm going to suggest names as I reply to 
this mail, and I will use them in this mail for brevity. However, please 
do suggest better names as you spot them.

For this config I will suggest "forrest_site.xconf"

> Forrest Projects
> -----------------
> A single Forrest Project contains the configurations specific to that 
> project.
> It should contain:
> - Project Name
> - site/
>    - LocationMap
>    - Site.xml
>    - Tabs.xml
> - Can point to a sub site which is another Forrest Project

I see these as being part of the forrest_site.xconf file. Each sub site 
has its own forrest_site.xconf file in which any values specified 
override those defined in the parent file.

This implies that sub-site files need to have a pointer back to the 
location of the parent site forrest_site.xconf so that they can retrieve 
the defaults. This in turn implies that the forrest_site.xconf of parent 
sites must be available via http:, file:, resource: or similar protocols.

> - Forrest Project Configuration (forrest.xml)
>    - Points to Plugins
>    - Points to Skins/Views/Themes for particular project
>    - Points to locationmap
>      (Basically the bits that are project specific from forrest.properties
>      and skinconf.xml)

I don't see this as being separate from the forrest_site.xconf either. 
It is likely that sub-sites will use the same view, plugins etc. as the 
parent. However, they need to have the ability to override these.

Note, skinconf.xml is a different beast, see below.

> Use Case
> =========
> 
> Here is a use case for the new configuration using Apache sites.
> 
> 
>            Single Forrest Instance
>                            |
>    -------------------------------------------------
>    |                        |                    |                |
>    (apache.org)    (Jakarta)    (XML)        (Forrest)
>    Forrest        Forrest        Forrest        Forrest
>    Project        Project        Project        Project
>                        |
>    --------------------------------
>    |                    |                |
>    (Sub site)    (Sub site)    (Sub site)
>    Forrest        Forrest        Forrest
>    Project        Project        Project
> 
> 
> 
> How the current configuration changes
> =====================================
> Here is how the current configuration files can be changed.
> 
> forrest.properties
> ------------------
> Forrest Properties can be split up with general configurations places in 
> the Forrest Instance and configurations specific to the project places 
> in each project's Project Configuration file e.g. Skins and plugins to 
> be used.
> 
> skinconf.xml
> ------------------
> Skinconf.xml configurations has skin configurations that can be done 
> with views. Configurations that are not on views can go into the Project 
> Configuration.

Yes, even with my unified forest_site.xconf suggestion much of skinconf 
will be a separate file, a *.fv file (or whatever it ends up being 
named) and a *.css file.

If forrest_site.xconf points to the default *.fv file for this site and 
all subsites we will, in many cases, be able to simply reuse *.fv files 
from the root site.

For example, all Jakarta sites would use the jakarta default.fv simply 
by *not* defining this element in their own sites forrest_site.xconf

> status.xml
> ----------
> Status can be treated as a content file instead of a configuration. The 
> file can be located anywhere and placed in the locationmap. The Project 
> Info Plugin can also be extended to pull status from status.xml or other 
> status files.

Status.xml already has nothing to do with core, it is already moved into 
the projectInfo plugin. We need not consider it in this thread.

> sitemap.xmap
> -------------
> Project Sitemap should become a Block to be loaded dynamically by 
> cocoon. Using a block means that the system does not need to be restarted.

There is no need to restart Forrest when the project sitemap is loaded. 
Furthermore, once we are able to update Cocoon to SVN head there is a 
really cool enhancement to the way sitemaps are loaded that I will be 
utilising.

I'm not at all sure we should be looking at a forrest site as being a 
block. But then again, I don't see any reason why we shouldn't be doing 
so. Perhaps someone who understands blocks better can tell us what would 
be involved with this, that is how would it affect the config system?

> Classes
> -------------
> Classes will be in the block
> 
> 
> Conf
> -------------
> This is relevant to the generation of static sites. Not sure how to 
> handle this.

I assume this refers to cli.xconf

This needs to be a completely different thread I think

> Resources
> -------------
> There can be a Resources location for the default layout for a fresh 
> site. The locationmap can be used to customise the resources after.

OK, that seems to be what I suggest above but with a slight twist. We 
also need the ability to cascade the locationmap resolving. That is if 
we fail to find a resource using our site locationmap we try with our 
parent sites locationmap and so on until we reach the root. If we fail 
in the root locationmap then we throw an error.

> Site
> -------------
> Here is where you store the locationmap of the content, the site.xml and 
> tabs.xml
> - LocationMap
> - Site.xml
> - Tabs.xml

OK (although we will surely visit site.xml and tabs.xml at some point 
soon as well!)


jetty.conf
----------

Currently we are able to override jetty.conf at a project level, but 
this will also need a fall-back mechanism to parent configs.

Ross