Author: thorsten
Date: Fri Nov 11 10:12:42 2005
New Revision: 332623
URL: http://svn.apache.org/viewcvs?rev=332623&view=rev
Log:
finished the contract refactoring. still missing the structurer, update notes
for v1 and ...
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-contracts.xml
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-dsl.xml
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-install.xml
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-contracts.xml
URL:
http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-contracts.xml?rev=332623&r1=332622&r2=332623&view=diff
==============================================================================
---
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-contracts.xml
(original)
+++
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-contracts.xml
Fri Nov 11 10:12:42 2005
@@ -28,19 +28,25 @@
<audience title="Intended Audience">
<warning>
-NEED REFACTORING FOR DISPATCHER!!!
+The "Dispatcher" (aka "Views") is new functionality which is still in
development phase. That is why it is in the
+"whiteboard" section of the Forrest distribution. This HowTo is a good start
but still needs more work.
</warning>
-<warning>
-"the dispatcher" are new functionality which is still in development phase.
That is why it is in the
-"whiteboard" section of the Forrest distribution.
-This HowTo is a good start but still needs more work.
-</warning>
-
<p>
Devs and skin developer that wants to get started with forrest:contract
development.
To really understand this how-to you need basic and sometimes advanced
understanding of
the "old fashion" skin development process.
</p>
+ <note>
+ For the moment we will use a special seed template called seed-v2. We
still
+ need to fix issues of the dispatcher that it really can replace old
+ fashion skins. Like performance, standalone contracts, other testing
output/input formats - using POJO based
+ processing will help solving this. All this will ATM happen in the v2
seed-target till the dispatcher will
+ be realesed to the stable plugins. So make regular updates of your
forrest-trunk to keep track.
+ </note>
+ <warning>
+ The way we develope contracts will/may change with introduction of java
based processing rather then xsl. Please keep this in mind
+ and help updating the documentation by sending patches. TIA. ;-)
+ </warning>
</audience>
<purpose title="Purpose">
@@ -53,14 +59,12 @@
<prerequisites title="Prerequisites">
<ul>
<li>
- You have a ready-to-go new seed (newSeed) based on the dispatcher like
described in <a href="site:howto/view/install">Install</a>.
- </li>
- <li>
- This includes as well all additional plugins that are mentioned in <a
href="site:howto/view/install">Install views</a>.
+ You have a ready-to-go new seed-v2 (v2) based on the dispatcher like
described in <a href="site:howto/dispatcher/install">Install</a>.
</li>
<li>
Reading that how-to is as well a good idea to understand the used
directory structure in this how-to.
</li>
+ <li>Installing a mozilla browser and the forrestbar helps a lot in
developing.</li>
</ul>
</prerequisites>
@@ -70,7 +74,7 @@
consolidation of this thread. It is mainly based on the thread "[RT] Why
using views" -
in comparison with "old fashion" skins - usecase i18n</note>
<p>
- By working on the i18n integration for "pelt" we again encountered the
reasons for using views. ;-)
+ By working on the i18n integration for "pelt" we again encountered the
reasons for using the dispatcher. ;-)
The maintenance problem was to change the captions of the skin features
(contracts) to enable
support for i18n. The case is that the <code>site2xhtml.xsl</code> has a
lot of repeating code.
</p>
@@ -122,36 +126,40 @@
To start a new forrest:contract you can copy the 'blank.ft' from
<code>org.apache.forrest.plugin.output.themer/resources/themes/common/html/blank.ft</code>.
</p>
- <warning>
-NEED REFACTORING FOR DISPATCHER!!!
-</warning>
<p>
The 'blank.ft' is a simple xml file with the following code which you
can use to base new contracts
on:
</p>
<source>
<![CDATA[<forrest:contract
+ xmlns:i18n="http://apache.org/cocoon/i18n/2.1";
xmlns:forrest="http://apache.org/forrest/templates/1.0";
name="blank" type="nugget">
<!--NOTE:
- When using the blank template as copy-and-paste master,
- just search and replace 'blank' by the {contract-name}!-->
+ When using the blank template as c'n p master just search and replace
'blank' by the {contract-name}!-->
<description>
- {contract-name} will output {contract-funtion}.
- This is just a blank contract, it will output *nothing*.
+ {contract-name} will output {contract-funtion}. This is just a blank
contract, it will output *nothing*.
</description>
<usage>]]><![CDATA[<![CDATA[<forrest:contract
name="blank"/>]]>]]><![CDATA[</usage>
<forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0";
- format="xhtml" name="blank" inputFormat="xsl" body="false" head="false">
+ format="html" name="blank" inputFormat="xsl" body="false" head="false">
<xsl:stylesheet version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";>
- <!--Add here the needed templates-->
+ <!--
+ Add here the needed templates.
+ Remember to set the forrest:template @attributes!
+ -->
+ <!--
+ <xsl:template name="blank-head">
+ </xsl:template>
+ <xsl:template name="blank-body">
+ </xsl:template>
+ -->
</xsl:stylesheet>
</forrest:template>
-</forrest:contract>
-]]>
+</forrest:contract>]]>
</source>
<p>
The most important is the name of the contract
<code><![CDATA[<forrest:contract name="blank"/>]]></code>.
@@ -171,21 +179,25 @@
</source>
<p>
In the <code><![CDATA[<usage/>]]></code> tag we have to explain how
the designer can use
- the contract in his view.
+ the contract in his structurer.
</p>
<source><![CDATA[<usage>]]><![CDATA[<![CDATA[<forrest:contract
name="siteinfo-last-published-howto"/>]]>]]><![CDATA[</usage>]]>
</source>
<p>
<code><![CDATA[<forrest:template name="blank" body="false"
head="false">]]> </code>
That leads to the template attribute @body="true" and
- @head="false". In xhtml a contract can add
content to the <![CDATA[<body/>]]> or/and
- <![CDATA[<head/>]]> part of
<![CDATA[<html/>]]>. These values need to be changed when adding an actual
template.
+ @head="false". In html a contract can add content to the
<![CDATA[<body/>]]> or/and
+ <![CDATA[<head/>]]> part of <![CDATA[<html/>]]>. These values need to
be changed when adding an actual template.
Besides this, a xsl-template needs to indicate this in the naming. A
template that adds content to the
html body needs to end with "<code>-body</code>"!!!
</p>
+ <warning>
+ The last paragraph about <![CDATA[<forrest:template name="blank"
body="false" head="false">]]> is due to change.
+ Please be aware that this part of the dispatcher is the main moving
target right now!!!
+ </warning>
<note>
It is possible to use contracts in different in/output formats.
- We are focussing for now on format="xhtml" as output and the
inputFormat="xsl".
+ We are focussing for now on format="html" as output and the
inputFormat="xsl".
</note>
<p>
A <![CDATA[<forrest:template />]]> has the child
<![CDATA[<xsl:stylesheet/>]]> where we can create
@@ -202,13 +214,13 @@
</section>
<section id="newContract">
<title>Create a new contract</title>
- <fixme author="thorsten">
- We need to explain basic naming convention for contracts. Like
- "naming does not say anything about layout position, but functionality
of the contract.".
- </fixme>
+ <note >
+ We use basic naming convention for contracts. Like
+ "naming does not say anything about layout position, but functionality
of the contract".
+ </note>
<p>
- Now let us pick up the example we started with
and create a "siteinfo-last-published-howto" contract.
- Save the blank.ft to
<code>{project.home}/src/documentation/resources/templates/siteinfo-last-published-howto.ft</code>.
+ Now let us pick up the example we started with and create a
"siteinfo-last-published-howto" contract.
+ Save the blank.ft to
<code>{project.home}/src/documentation/resources/themes/common/html/siteinfo-last-published-howto.ft</code>.
</p>
<p>
Now the maintenance-optimized code (xpath="/html/body/*") was:
@@ -219,9 +231,9 @@
document.write("<i18n:text >Last Published:</i18n:text> " +
document.lastModified);
</script>
</xsl:template>]]></source>
- <p>
+ <p>
In this code we have to do the following steps to use it in our
contract:
- </p>
+ </p>
<ul>
<li>Search and replace "siteinfo-last-published" with
"siteinfo-last-publish-howto-body"</li>
<li>Add a "debug string - " to the template</li>
@@ -236,7 +248,7 @@
document.write("<i18n:text >Last Published:</i18n:text> " +
document.lastModified);
</script>
</xsl:template>]]></source>
- <p>Now we have to do some last steps in the
siteinfo-last-publish-howto.ft</p>
+ <p>Now we have to do some last steps in the
siteinfo-last-publish-howto.ft</p>
<ul>
<li>Search and replace "blank" with "siteinfo-last-publish-howto"</li>
<li>Add description and usage of the contract</li>
@@ -255,7 +267,7 @@
<forrest:template
xmlns:i18n="http://apache.org/cocoon/i18n/2.1";
xmlns:forrest="http://apache.org/forrest/templates/1.0";
- format="xhtml" name="siteinfo-last-published-howto" inputFormat="xsl"
body="true" head="false">
+ format="html" name="siteinfo-last-published-howto" inputFormat="xsl"
body="true" head="false">
<xsl:stylesheet version="1.1"
xmlns:i18n="http://apache.org/cocoon/i18n/2.1";
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";>
@@ -268,26 +280,25 @@
</forrest:contract>]]>
</source>
</section>
- <section id="viewContract">
+ <section id="structurerContract">
<title>Activating the contract</title>
<p>
- To see whether the new contract works we need to add it to our view.
+ To see whether the new contract works we need to add it to our
structurer.
The contract usage contains the contract-tag
<code><![CDATA[<forrest:contract
name="siteinfo-last-published-howto"/>]]></code>
- Please see <a href="site:howto/view/DSL">Getting started with
forrest:view DSL</a> for more details.
+ Please see <a href="site:v0.80//howto/dispatcher/structurer">Getting
started with the "structurer"</a> for more details.
</p>
- <fixme author="thorsten">
- Let us now look into advanced features of the dispatcher.
- I will write a how-to for advanced contracts soon. :)
- </fixme>
+ <note>
+ Next to write are parameter-contracts with advanced features of the
dispatcher.
+ </note>
</section>
</steps>
<extension title="Further Reading">
<p>
- Congratulations you are now able to work with view contracts.
- From here we recommend to read the following How-To's:
+ Congratulations you are now able to work with structurer contracts.
+ From here we recommend to read the following How-To's (if not already
done):
</p>
<ul>
- <li><a href="site:howto/view/DSL">Getting started with forrest:view
DSL</a> </li>
+ <li><a href="site:v0.80//howto/dispatcher/structurer">Getting started
with the "structurer"</a> </li>
</ul>
</extension>
<feedback title="Feedback">
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-dsl.xml
URL:
http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-dsl.xml?rev=332623&r1=332622&r2=332623&view=diff
==============================================================================
---
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-dsl.xml
(original)
+++
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-structurer-dsl.xml
Fri Nov 11 10:12:42 2005
@@ -32,14 +32,23 @@
NEED REFACTORING FOR DISPATCHER!!!
</warning>
<warning>
-"Views" are new functionality which is still in development phase. That is why
it is in the
-"whiteboard" section of the Forrest distribution.
-This HowTo is far from being finished.
+The "Dispatcher" (aka "Views") is new functionality which is still in
development phase. That is why it is in the
+"whiteboard" section of the Forrest distribution. This HowTo is a good start
but still needs more work.
</warning>
-
<p>
- This part of the views is dedicated to webdesigner and user with some
knowlegde of css.
+ This part of the the dispatcher is called the structurer and is
dedicated to webdesigner and user with some knowlegde of css.
</p>
+ <note>
+ For the moment we will use a special seed template called seed-v2. We
still
+ need to fix issues of the dispatcher that it really can replace old
+ fashion skins. Like performance, standalone contracts, other testing
output/input formats - using POJO based
+ processing will help solving this. All this will ATM happen in the v2
seed-target till the dispatcher will
+ be realesed to the stable plugins. So make regular updates of your
forrest-trunk to keep track.
+ </note>
+ <warning>
+ The way we develope contracts will/may change with introduction of java
based processing rather then xsl. Please keep this in mind
+ and help updating the documentation by sending patches. TIA. ;-)
+ </warning>
</audience>
<purpose title="Purpose">
@@ -52,24 +61,26 @@
<prerequisites title="Prerequisites">
<ul>
<li>
- You have a ready-to-go new seed (newSeed) based on views as described
in <a href="site:howto/view/install">Install views</a>.
- </li>
- <li>
- This includes as well as all additional plugins that are mentioned in
<a href="site:howto/view/install">Install views</a>.
+ You have a ready-to-go new seed-v2 (v2) based on the dispatcher like
described in <a href="site:howto/dispatcher/install">Install</a>.
</li>
<li>
Reading that how-to is as well a good idea to understand the used
directory structure in this how-to.
</li>
+ <li>Installing a mozilla browser and the forrestbar helps a lot in
developing.</li>
</ul>
</prerequisites>
<steps title="Steps">
<note>
- When developing with views we assume you are using 'forrest run' and the
following workflow:<br/>
+ When developing with the dispatcher we assume you are using 'forrest
run' and the following workflow:<br/>
change files -> refresh browser
</note>
+ <note>
+ Installing a mozilla browser and the forrestbar helps a lot in
developing. Many instructions assumes that you have the
+ forrestbar installed.
+ </note>
<p>
- We developed<strong> forrest:view</strong> to let the user decide where
to place elements in e.g. html pages.
+ We developed<strong> the structurer</strong> to let the user decide
where to place elements in e.g. html pages.
We started this work with the <code>skinconf.xml</code> where you could
configure certain elements and
their positions. These elements were known under certain names. It was
up to the skin designer to support
this configuration and the elements.
@@ -83,10 +94,20 @@
</a>
</p>
<p>
- Around this contracts we developed a configuration Domain Specific
Language and called it<strong>forrest:view</strong>.
- These <strong>forrest:view</strong>s allows us to define the order in
which <strong>forrest:contract</strong>s appear, and also to group
+ Around this contracts we developed a configuration Domain Specific
Language - called <strong>the structurer</strong>.
+ The <strong>structurer</strong> allows us to define the order in which
<strong>forrest:contract</strong>s appear, and also to group
them using <strong>forrest:hook</strong>s.
</p>
+ <note>
+ The structurer is as well a configuration file for the dispatcher. The
new think on the dispatcher is that one can include any content
+ from any given business service by dispatching a request against it. In
"old fashion" skins and in v1 contracts we assumed a given data
+ model. In the dispatcher there is <strong>no</strong> given data model
any more. All data has to be defined in the structurer that
+ they can be dispatched.
+ </note>
+ <warning>
+ For now we are using jx to include the raw data into the presentation
model and generating an alias-xsl stylesheet. That is heavy on
+ performance and we will change this ASAP. Mind the warning at the start
of the howto.
+ </warning>
<p>
<strong>forrest:hook</strong>s are containers that are only used for
layout reasons. They <strong>do not</strong> add
any content or functionality to the output. They add
<strong>only</strong> layout information to
@@ -100,50 +121,64 @@
</p>
<section id="emptyView">
<title>Empty view file</title>
- <source><![CDATA[<forrest:views
xmlns:forrest="http://apache.org/forrest/templates/1.0";>
- <forrest:view type="xhtml">
+ <source><![CDATA[<forrest:views
+ xmlns:forrest="http://apache.org/forrest/templates/1.0";
+ xmlns:jx="http://apache.org/cocoon/templates/jx/1.0";>
+ <forrest:view type="html">
</forrest:view>
</forrest:views>]]>
</source>
<p>
- <strong> forrest:view</strong> is designed to be open for any format
that can use<strong> forrest:view</strong> as configuration file.
- The only format we implemented is xhtml for now. This is as well true
for the delivered contracts.
+ <strong> The structurer</strong> is designed to be open for any format
that can use<strong> forrest:view</strong> as configuration file.
+ The only format we implemented is html for now. This is as well true for the
delivered contracts.
</p>
<p>
- Now let us start to skin our site.
+ Now let us start to theme our site.
</p>
</section>
<section id="firstView">
- <title>Creating your first view</title>
- <p>
- In this section we will create a new view. We
will override the default view of the view-plugin
- for the index page of the <a
href="site:howto/view/install">newSeed</a>.
+ <title>Creating your first view</title>
+ <p>
+ In this section we will create a new structurer. We will override the
default structurer of the themer-plugin
+ for the index page of the <a
href="site:howto/dispatcher/install">v2</a>.
For that we will create a file called <code>index.fv</code> and save
it in our xdocs directory.
This will make <strong>only</strong> the index.html page look
different from the rest of the project.
- </p>
+ </p>
<p>
Remember: pointing your browser to
<code>http://localhost:8888/ls.contracts.html</code> will
show a page with all contracts that you can use in your project.
</p>
<p>
- Let use the blank view from the earlier step and add the content-main
contract. In
- ls.contracts.html we find the information for how to use the contract
in our view. Our
+ Let us use the blank structurer from the earlier step and add the
content-main contract. In
+ ls.contracts.html we find the information for how to use the contract
in our structurer. Our
<code>index.fv</code> should look like:
</p>
- <source><![CDATA[<forrest:views
xmlns:forrest="http://apache.org/forrest/templates/1.0";>
- <forrest:view type="xhtml">
- <forrest:contract name="content-main"/>
+ <source><![CDATA[<forrest:views
+ xmlns:forrest="http://apache.org/forrest/templates/1.0";
+ xmlns:jx="http://apache.org/cocoon/templates/jx/1.0";>
+ <forrest:view type="html">
+ <forrest:contract name="content-main">
+ <forrest:properties contract="content-main">
+ <forrest:property name="content-main" nugget="get.body">
+ <jx:import uri="cocoon://#{$cocoon/parameters/getRequest}.body.xml"/>
+ </forrest:property>
+ </forrest:properties>
+ </forrest:contract>
</forrest:view>
</forrest:views>]]>
</source>
+ <note>
+ The structurer is based on jx templates to allow simple presentation
logic (all
+ code starting with "jx:"). Please refer to the cocoon documentation
about jx.
+ </note>
<p>
Lets try our new view by pointing to
<code>http://localhost:8888/index.html</code>.
We will see only the main content. Now let us add the section
navigation to our view.
The contract usage in the view can be looked up in ls.contracts.html.
Our view now looks like:
</p>
<source><![CDATA[<forrest:views
xmlns:forrest="http://apache.org/forrest/templates/1.0";>
- <forrest:view type="xhtml">
+ <forrest:view type="html">
<forrest:contract name="content-main"/>
<forrest:contract name="nav-section"/>
</forrest:view>
@@ -156,12 +191,12 @@
</p>
</section>
<section id="hookView">
- <title>Hooks in views</title>
+ <title>Hooks in the structurer</title>
<p>
We will use now the first time a <code><![CDATA[<forrest:hook
name="layoutId"/>]]></code>.
- Hooks are the styling side of views. We can imitate arbitrary html
skeleton
- with their help. Before we explain how to use your own css in views,
we will use the default css.
- In the default.css we can find
+ Hooks are the styling side of the dispatcher. We can imitate arbitrary
html skeleton
+ with their help. Before we explain how to use your own css in the
structurer, we will use the default css.
+ In the common.css we can find
</p>
<source>/* menu */
#leftbar {
@@ -182,12 +217,14 @@
<source><![CDATA[<forrest:hook name="leftbar">
<forrest:contract name="nav-section"/>
</forrest:hook>]]>
- </source>
+ </source>
<p>
Our view will then look like:
</p>
- <source><![CDATA[<forrest:views
xmlns:forrest="http://apache.org/forrest/templates/1.0"; >
- <forrest:view type="xhtml">
+ <source><![CDATA[<forrest:views
+ xmlns:forrest="http://apache.org/forrest/templates/1.0";
+ xmlns:jx="http://apache.org/cocoon/templates/jx/1.0";>
+ <forrest:view type="html">
<forrest:hook name="leftbar">
<forrest:contract name="nav-section"/>
</forrest:hook>
@@ -197,15 +234,19 @@
</source>
</section>
<section id="cssView">
- <title>CSS in views</title>
+ <title>CSS in the structurer</title>
<p>
- We now know how to place contracts and hooks in our view. Until this
stage we only used the default.css.
- CSS-support of views is as easy as placing contracts/hooks. To
override the default.css
- stylesheet we use another tag within our view
<code><![CDATA[<forrest:css url="default.css"/>]]></code>.
+ We now know how to place contracts and hooks in our view. Until this
stage we only used the common.css.
+ CSS-support of the structurer is as easy as placing contracts/hooks.
To override the common.css
+ stylesheet we use another tag within our view
<code><![CDATA[<forrest:css url="common.css"/>]]></code>.
</p>
<p>
- We will now create a file in
<code><![CDATA[{project:skins-dir}{path}/{name}.css]]></code>. In our case
- we will save a file called howTo.css in
newSeed/src/documentation/skins/css/howTo.css containing only
+ We will now create a file in <code><![CDATA[<!--
+ {1} name
+ {2} extension (note we assume e.g. PATH/css/{1}.css)
+ -->
+<location src="{project:themer}/resources/themes/{project:theme}/{2}/{1}.{2}"
/>]]></code>. In our case
+ we will save a file called howTo.css in
v2/src/documentation/resources/themes/common/css/howTo.css containing only
the following css:
</p>
<source>/* menu */
@@ -218,16 +259,18 @@
</source>
<p>
We just changed the border-style to 'solid', the background to
'#CCCCFF' and the color to '#000000'.
- Now we have to add a new tag to tell that we want to override the
default.css. We are doing this
+ Now we have to add a new tag to tell that we want to override the
common.css. We are doing this
by adding the tag <code><![CDATA[<forrest:css
url="howTo.css"/>]]></code> to our view.
</p>
<note>
<code><![CDATA[<forrest:css url="howTo.css"/>]]></code> needs to be
the direct child of
- <code><![CDATA[<forrest:view type="xhtml">]]></code>
+ <code><![CDATA[<forrest:view type="html">]]></code>
</note>
- <source><