You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/07/17 08:58:59 UTC
svn commit: r219374 - in
/forrest/trunk/site-author/content/xdocs/docs_0_80/howto:
howto-view-contracts.xml howto-view-dsl.xml
Author: crossley
Date: Sat Jul 16 23:58:59 2005
New Revision: 219374
URL: http://svn.apache.org/viewcvs?rev=219374&view=rev
Log:
Minor text tweaks and grammar stuff.
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-contracts.xml
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-dsl.xml
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-contracts.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-contracts.xml?rev=219374&r1=219373&r2=219374&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-contracts.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-contracts.xml Sat Jul 16 23:58:59 2005
@@ -23,7 +23,7 @@
<abstract>
This How-To will explain how we wrote the contracts for views and hope afterwards you will be able to do the same.
</abstract>
- <last-modified-content-date date="2005-06-06"/>
+ <last-modified-content-date date="2005-07-17"/>
</header>
<audience title="Intended Audience">
@@ -31,7 +31,7 @@
<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 a good start but still needs proof-reading.
+This HowTo is a good start but still needs more work.
</warning>
<p>
@@ -57,7 +57,7 @@
This includes as well all additional plugins that are mentioned in <a href="site:howto/view/install">Install views</a>.
</li>
<li>
- Reading that how-to is as well a good idea to understand the used dir-structure in this how-to.
+ Reading that how-to is as well a good idea to understand the used directory structure in this how-to.
</li>
</ul>
</prerequisites>
@@ -65,18 +65,18 @@
<steps title="Steps">
<note>The following content is from many mails around the topic, this how-to tries to be the
- consolidation of this thread. It is mainly based on the [RT] Why using views -
+ 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 crossed again the whys for using views. ;-)
- The maintainment problem was to change the captions of the skin features (contracts) to enable
+ By working on the i18n integration for "pelt" we again encountered the reasons for using views. ;-)
+ 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>
<p>
For example the "last-publish"-contract could be found 2 times in the code.
- This is not the only contract that was (is) double in the code. The problem with that is that
- we needed to search the code for each caption and senseless repeat the following
- maintainment step of adding the <![CDATA[<i18n:text/>]]>-tags.
+ This is not the only contract that was (is) doubled in the code. The problem with that is that
+ we needed to search the code for each caption and senselessly repeat the following
+ maintenance step of adding the <![CDATA[<i18n:text/>]]>-tags.
</p>
<source>
<![CDATA[
@@ -87,9 +87,9 @@
+ Published:</i18n:text> " + document.lastModified);
]]>
</source>
- <section id="enhanceMaintainment">
- <title>Enhance the maintainment</title>
- <p>Now we can enhance the maintainment for the future and we give this code snippets
+ <section id="enhanceMaintenance">
+ <title>Enhance the maintenance</title>
+ <p>Now we can enhance the maintenance for the future and we give these code snippets
contracts names (based on their functionality). This naming enables us to keep
the contract separate from the position code itself. In xsl you would
simply do:
@@ -106,7 +106,7 @@
</xsl:template>]]>
</source>
<p>
- This allows us in a next maintainment just change the code of
+ This allows us in a next maintenance to just change the code of
<![CDATA[<xsl:template name="siteinfo-last-published"/>]]> and apply it in any position where
it is placed.
</p>
@@ -131,10 +131,12 @@
name="blank" type="nugget">
<!--NOTE:
- When using the blank template as c'n p master just search and replace 'blank' by the {contract-name}!-->
+ When using the blank template as copy-and-paste 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"
@@ -151,8 +153,8 @@
The most important is the name of the contract <code><![CDATA[<forrest:contract name="blank"/>]]></code>.
This name is the same as the file name of the contract (without file extension) <code>blank.ft</code>.
</p>
- <note>This is a <strong>naming convention</strong> that you have
- to always met. All @name has to be file name of the contract without file extension!
+ <note>This is a <strong>naming convention</strong> that you need
+ to always meet. All @name attributes must be the file name of the contract without file extension.
</note>
<p>
The <code><![CDATA[<description/>]]></code> tag needs to be filled in with some information
@@ -173,16 +175,16 @@
<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/>]]>. This values have to be change when adding an actual template.
- Besides this a xsl-template has to indicate this in the naming. A template that add content to the
- html body has to end with "<code>-body</code>"!!!
+ <![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>
<note>
- It is possible to use contracts in different in/output-formats.
- We are focusing for now on format="xhtml" as ouput and the inputFormat="xsl".
+ 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".
</note>
<p>
- A <![CDATA[<forrest:template />]]> has the son <![CDATA[<xsl:stylesheet/>]]> where we can create
+ A <![CDATA[<forrest:template />]]> has the child <![CDATA[<xsl:stylesheet/>]]> where we can create
templates for the html-head and html-body. For adding content into the body of the final
document change @body="true" and add:
</p>
@@ -198,14 +200,14 @@
<title>Create a new contract</title>
<fixme author="thorsten">
We need to explain basic naming convention for contracts. Like
- "naming do not say about layout position but functionality of the contract.".
+ "naming does not say anything about layout position, but functionality of the contract.".
</fixme>
<p>
- Now lets pick up the example we started with and create a "siteinfo-last-published-howto" contract.
+ 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>.
</p>
<p>
- Now the maintainment optimized code (xpath="/html/body/*") was:
+ Now the maintenance-optimized code (xpath="/html/body/*") was:
</p>
<source>
<![CDATA[<xsl:template name="siteinfo-last-published">
@@ -235,7 +237,7 @@
<li>Search and replace "blank" with "siteinfo-last-publish-howto"</li>
<li>Add description and usage of the contract</li>
<li>Set @body="true"</li>
- <li>Copy the maintainment optimized code to the contract.</li>
+ <li>Copy the maintenance optimized code to the contract.</li>
</ul>
<p>
As the result your code should look like this:
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-dsl.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-dsl.xml?rev=219374&r1=219373&r2=219374&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-dsl.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-view-dsl.xml Sat Jul 16 23:58:59 2005
@@ -22,9 +22,9 @@
<title>How to use the forrest:view config-DSL</title>
<abstract>
This How-To describes the usage of the forrest:view config Domain Specific Language
- to create beautiful website in no time.
+ to create beautiful websites in no time.
</abstract>
- <last-modified-content-date date="2005-06-06"/>
+ <last-modified-content-date date="2005-07-17"/>
</header>
<audience title="Intended Audience">
@@ -42,21 +42,21 @@
<purpose title="Purpose">
<p>
- This how-to will show you how to write a<strong> forrest:view</strong> from ground on.
- We will focus on html as output format. As well it will show how to add your own css implementation to the view.
+ This how-to will show you how to write a <strong>forrest:view</strong> from the ground up.
+ We will focus on html as the output format. As well it will show how to add your own css implementation to the view.
</p>
</purpose>
<prerequisites title="Prerequisites">
<ul>
<li>
- You have a ready-to-go new seed (newSeed) based on views like described in <a href="site:howto/view/install">Install views</a>.
+ 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 all additional plugins that are mentioned in <a href="site:howto/view/install">Install views</a>.
+ This includes as well as all additional plugins that are mentioned in <a href="site:howto/view/install">Install views</a>.
</li>
<li>
- Reading that how-to is as well a good idea to understand the used dir-structure in this how-to.
+ Reading that how-to is as well a good idea to understand the used directory structure in this how-to.
</li>
</ul>
</prerequisites>
@@ -67,9 +67,9 @@
change files -> refresh browser
</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> forrest:view</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. This elements was known under certain names. It was up to the skin-designer to support
+ their positions. These elements were known under certain names. It was up to the skin designer to support
this configuration and the elements.
</p>
<p>
@@ -77,30 +77,30 @@
we added as @attributes e.g. <code><![CDATA[<div id="content-main"/>]]> </code>. That made it
possible to use the same elements in different skins. For the full list refer to the
<a href="http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/main/webapp/skins/leather-dev/contracts.inicial.txt">
- inicial contract list
+ initial contract list
</a>
</p>
<p>
- Around this contracts we developed a configuration Domain Specific Language and called it<strong> forrest:view</strong> .
- <strong> forrest:view</strong> 's 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.
+ 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
+ them using <strong>forrest:hook</strong>s.
</p>
<p>
- <strong>forrest:hook</strong>'s are container that are only used for layout reasons. They <strong>do not</strong> add
- any content nor functionality to the output. They add <strong>only</strong> layout information to
+ <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
the output. Actually a <code><![CDATA[<forrest:hook name="layoutId"/>]]></code> will be transformed
to <code><![CDATA[<div id="layoutId"/>]]> </code>
</p>
<p>
- <strong>forrest:contract</strong>'s are functionality or extra content that a skin can use to display the requested
+ <strong>forrest:contract</strong>s are functionality or extra content that a skin can use to display the requested
document (content-main). Sometimes a contract delivers <strong>format-specific markup</strong>, other times it delivers
a <strong>format-independent string</strong>.
</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">
- </forrest:view>
+ <source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0">
+ <forrest:view type="xhtml">
+ </forrest:view>
</forrest:views>]]>
</source>
<p>
@@ -108,7 +108,7 @@
The only format we implemented is xhtml for now. This is as well true for the delivered contracts.
</p>
<p>
- Now lets start to skin our site. :)
+ Now let us start to skin our site.
</p>
</section>
@@ -126,29 +126,29 @@
</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 how to use the contract in our view. Our
+ ls.contracts.html we find the information for how to use the contract in our view. 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">
+ <source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0">
+ <forrest:view type="xhtml">
<forrest:contract name="content-main"/>
- </forrest:view>
+ </forrest:view>
</forrest:views>]]>
</source>
<p>
- Let's try our new view by pointing to <code>http://localhost:8888/index.html</code>.
- We will see only the main content. :) Now let's add the section navigation to our view.
+ 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">
+ <source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0">
+ <forrest:view type="xhtml">
<forrest:contract name="content-main"/>
<forrest:contract name="nav-section"/>
- </forrest:view>
+ </forrest:view>
</forrest:views>]]>
</source>
<p>
- We find now the main content and the section navigation after each other and in the order
+ We now find the main content and the section navigation after each other and in the order
we placed them in the view, but we want it next to each other
(left: nav-section; right: content-main).
</p>
@@ -158,7 +158,7 @@
<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.
+ 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
</p>
<source>/* menu */
@@ -174,7 +174,7 @@
and add contracts into that container.
</p>
<p>
- If we want to put the nav-section contract into the left side position
+ If we want to put the nav-section contract into the left-hand side position
of the site we need to place the contract into that hook. Like:
</p>
<source><![CDATA[<forrest:hook name="leftbar">
@@ -197,7 +197,7 @@
<section id="cssView">
<title>CSS in views</title>
<p>
- We know now how to place contracts and hooks in our view, till this stage we only used the default.css.
+ 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>.
</p>
@@ -220,8 +220,8 @@
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> has to be direct son of
- <code><![CDATA[<forrest:view type="xhtml">]]></code>!!!
+ <code><![CDATA[<forrest:css url="howTo.css"/>]]></code> needs to be the direct child of
+ <code><![CDATA[<forrest:view type="xhtml">]]></code>
</note>
<source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0" >
<forrest:view type="xhtml">
@@ -234,8 +234,8 @@
</forrest:views>]]>
</source>
<p>
- Now you see a white page where the menu is sourrounded by a solid border with the defined background.
- As second example let us change as well the content-main by adding another hook
+ Now you see a white page where the menu is surrounded by a solid border with the defined background.
+ As a second example, let us change as well the content-main by adding another hook
<code><![CDATA[<forrest:hook name="content"/>]]></code> We need to add the new layout container
to our howTo.css:
</p>
@@ -248,7 +248,8 @@
}
</source>
<p>
- Then we have to add the 'content-main' contract to the 'content' hook, the resulting view looks like:
+ Then we have to add the 'content-main' contract to the 'content' hook.
+ The resulting view looks like:
</p>
<source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0" >
<forrest:view type="xhtml">
@@ -263,7 +264,7 @@
</forrest:views>]]>
</source>
<p>
- We are now able to place contracts into layout container and add custom css to the view.
+ We are now able to place contracts into the layout container and add custom css to the view.
</p>
<fixme author="thorsten">
Let us now look into advanced features of views.
@@ -275,7 +276,7 @@
<extension title="Further Reading">
<p>
Congratulations you are now able to work with the view DSL.
- From here we recommend to read the following How-To's:
+ From here we recommend to read the following How-Tos:
</p>
<ul>
<li><a href="site:howto/view/contracts">Create your own contract implementation</a> </li>