forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From thors...@apache.org
Subject svn commit: r190207 - /forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml /forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml /forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml
Date Sun, 12 Jun 2005 03:35:29 GMT
Author: thorsten
Date: Sat Jun 11 20:35:28 2005
New Revision: 190207

URL: http://svn.apache.org/viewcvs?rev=190207&view=rev
Log:
Finished first version of the views howtos

Modified:
    forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml
    forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml
    forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml

Modified: forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml?rev=190207&r1=190206&r2=190207&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-contracts.xml Sat Jun 11
20:35:28 2005
@@ -51,7 +51,10 @@
   <prerequisites title="Prerequisites">
     <ul>
       <li>
-        You have a ready-to-go new seed 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 like 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>.
       </li>
       <li>
         Reading that how-to is as well a good idea to understand the used dir-structure in
this how-to.
@@ -86,8 +89,8 @@
     </source>
     <section id="enhanceMaintainment">
       <title>Enhance the maintainment</title>
-      <p>Now we can enhance the maintainment for the future and we started to
-give this code snippets contracts names (based on their functionality). This naming enables
us to keep
+      <p>Now we can enhance the maintainment for the future and we give this 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:
       </p>
@@ -114,14 +117,16 @@
     <section id="blankContract">
       <title>Explaining the blank forrest:contract</title>
       <p>
-        To start a new forrest:contract you can copy the "blank.ft" from
+        To start a new forrest:contract you can copy the 'blank.ft' from
         <code>org.apache.forrest.plugin.output.viewHelper.xhtml/resources/templates</code>.

-        It is a simple xml file with the following code which you can use to base new contracts

-        on (note to close the CDATA element before the <code><![CDATA[</usage>]]></code>!):
+        The exact file system path can be looked up at <code>http://localhost:8888/ls.contracts.html</code>.
+      </p>
+      <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">
   
@@ -131,7 +136,7 @@
   <description>
     {contract-name} will output {contract-funtion}. This is just a blank contract, it will
output *nothing*.
   </description>
-  <usage><![CDATA[<forrest:contract name="doNotUseJustDummy"/>]] ></usage>
+  <usage>]]>&lt;![CDATA[<![CDATA[<forrest:contract name="blank"/>]]>]]&gt;<![CDATA[</usage>
   <forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0"
     format="xhtml" name="blank" inputFormat="xsl" body="false" head="false">
     <xsl:stylesheet version="1.1" 
@@ -150,18 +155,27 @@
         to always met. All @name has to be file name of the contract without file extension!
       </note>
       <p>
-        The <code><![CDATA[<description/>]]></code> tag is self explaining.

-        Here we have to explain what this contract is doing.
-      </p>
+        The <code><![CDATA[<description/>]]></code> tag needs to
be filled in with some information
+        that is explaining the contract to the webdesigner. The better explained the more
efficient
+        for the webdesigner to pick the right contract.
+      </p>
+      <source><![CDATA[<description>
+  siteinfo-last-published-howto will output the last published date of the site with the
help of jscript.
+</description>]]>
+      </source>
       <p>
-        The <code><![CDATA[<usage/>]]></code> tag is self explaining.

-        Here we have to explain how the designer can use the contract in his view.
+        In the <code><![CDATA[<usage/>]]></code> tag we have to explain
how the designer can use 
+        the contract in his view.
       </p>
+      <source><![CDATA[<usage>]]>&lt;![CDATA[<![CDATA[<forrest:contract
name="siteinfo-last-published-howto"/>]]>]]&gt;<![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/>]]>. 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>"!!!
       </p>
       <note>
         It is possible to use contracts in different in/output-formats. 
@@ -187,8 +201,8 @@
         "naming do not say about layout position but functionality of the contract.".
       </fixme>
       <p> 
-				Now lets pick up the example we started with and create a "last-publish-howTo" contract.
-        Save the blank.ft to <code>{project.home}/src/documentation/resources/templates/last-publish-howTo.ft</code>.
+				Now lets 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:
@@ -199,43 +213,66 @@
   document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
  </script>
 </xsl:template>]]></source>
+			<p>
+        In this code we have to do the following steps to use it in our contract:
+			</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>
+      </ul>
+      <p>
+        The contract after this steps should look like:
+      </p>
+      <source>
+<![CDATA[<xsl:template name="siteinfo-last-publish-howto-body">
+debug string - 
+ <script type="text/javascript">
+  document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
+ </script>
+</xsl:template>]]></source>
+			<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 of the contract</li>
+        <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>
       </ul>
       <p>
-        The forrest:template after search/replace should look like:
+        As the result your code should look like this:
       </p>
-      <source><![CDATA[<forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0"
-  format="xhtml" name="last-publish-howTo" 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-->
-  </xsl:stylesheet>
-</forrest:template>]]>
-      </source>
-      <p>
-        Now copy the maintainment optimized code after the comment and rename the template

-        regarding the naming conventions. As the result your code should look like this:
-      </p>
-      <source><![CDATA[<forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0"
-  format="xhtml" name="last-publish-howTo" inputFormat="xsl" body="true" head="false">
-  <xsl:stylesheet version="1.1" 
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-    <!--Add here the needed templates-->
-    <xsl:template name="last-publish-howTo-body">
-     <script type="text/javascript">
-      document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
-     </script>
-    </xsl:template>
-  </xsl:stylesheet>
-</forrest:template>]]>
+      <source><![CDATA[<forrest:contract xmlns:forrest="http://apache.org/forrest/templates/1.0"
+  name="siteinfo-last-published-howto" type="nugget">
+  <description>
+    siteinfo-last-published-howto will output the last published date of the site with the
help of jscript.
+  </description>
+  <usage>]]>&lt;![CDATA[<![CDATA[<forrest:contract name="siteinfo-last-published-howto"/>]]>]]&gt;<![CDATA[</usage>
+  <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">
+    <xsl:stylesheet version="1.1" 
+        xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+        <xsl:template name="siteinfo-last-published-howto-body">
+          debug string - 
+          <script type="text/javascript">document.write("<i18n:text >Last Published:</i18n:text>&#160;"
+ document.lastModified);</script>
+        </xsl:template>
+    </xsl:stylesheet>
+  </forrest:template>
+</forrest:contract>]]>
       </source>
     </section>
     <section id="viewContract">
       <title>Activating the contract</title>
-      <fixme author="thorsten">Link to DSL now. I will give more example after DSL-howto
is finished</fixme>
+      <p>
+        To see whether the new contract works we need to add it to our view.
+        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.
+      </p>
+ 			<fixme author="thorsten">
+        Let us now look into advanced features of views. 
+        I will write a how-to for advanced contracts soon. :)
+      </fixme>
     </section>
   </steps>
   <extension title="Further Reading">

Modified: forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml?rev=190207&r1=190206&r2=190207&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-dsl.xml Sat Jun 11 20:35:28
2005
@@ -41,22 +41,33 @@
   </audience>
   
   <purpose title="Purpose">
-    
     <p>
-      This how-to will show you how to write a forrest:view from ground on. 
+      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.
     </p>
   </purpose>
 
   <prerequisites title="Prerequisites">
     <ul>
-      <li>You have a ready-to-go new seed based on views (like described in <a href="site:howto/view/install">Install
views</a>). </li>
+      <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>.
+      </li>
+      <li>
+      	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.
+      </li>
     </ul>
   </prerequisites>
 
   <steps title="Steps">
+    <note>
+      When developing with views we assume you are using 'forrest run' and the following
workflow:<br/>
+      change files -> refresh browser
+    </note>
     <p>
-      We developed forrest:view 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 
       this configuration and the elements.
@@ -70,20 +81,20 @@
       </a>
     </p>
     <p>
-     Around this contracts we developed a configuration Domain Specific Language and called
it forrest:view.
-     forrest:view's allows us to define the order in which forrest:contract's appear, and
also to group
-     them using forrest:hook's.
+     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.
     </p>
     <p>
-     forrest:hook's are container that are only used for layout reasons. They <strong>do
not</strong> add 
+     <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 
      the output. Actually a <code><![CDATA[<forrest:hook name="layoutId"/>]]></code>
will be transformed
      to <code><![CDATA[<div id="layoutId"/>]]> </code>
     </p>
     <p>
-     forrest:contract's are functionality or extra content that a skin can use to display
the requested
-     document (content-main). Sometimes a contact delivers format specific markup, other
times it delivers
-     a format-independent string.
+     <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>
@@ -93,7 +104,7 @@
 </forrest:views>]]>
       </source>
       <p>
-        forrest:view is designed to be open for any format that can use forrest:view as configuration
file.
+       <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.
       </p>
       <p>
@@ -101,33 +112,6 @@
       </p>
     </section>
 
-    <section id="availableContracts">
-    <title>Available contracts</title>
-    <p> 
-     To start your skin you need to know which contracts you can use. 
-     For this we will install another plugin <code>org.apache.forrest.plugin.input.viewHelper.xhtml.ls</code>.
-     The setup is:
-    </p>
-    <source>
-cd {forrest-trunk}
-svn up
-cd whiteboard/plugins/org.apache.forrest.plugin.input.viewHelper.xhtml.ls/
-ant local-deploy
-</source>
-			<p>
-        The newly installed plugin will show the available contracts as html page.
-        First we have to tell forrest that we are planing to use the new plugin. We will
do that
-        by editing the forrest.properties of the <a href="site:howto/view/install">newSeed</a>

-        to <strong>add</strong> the plugin:
-      </p>
-      <source>
-project.required.plugins=org.apache.forrest.plugin.input.viewHelper.xhtml.ls
-      </source>
-      <p>
-        Now point your browser to <code>http://localhost:8888/ls.contracts.html</code>.

-        On this page you will find all contracts that you can use in your project.
-      </p>
-    </section>
     <section id="firstView">
 			<title>Creating your first view</title>
 			<p>
@@ -137,6 +121,10 @@
         This will make <strong>only</strong> the index.html page look different
from the rest of the project.
 			</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 how to use the contract in our view. Our

         <code>index.fv</code> should look like:
@@ -222,29 +210,66 @@
 #leftbar {
     width: 25%;
     float: left;
-    background: #eae8e3;
+    background: #CCCCFF;
     border: thin solid #000000;
 }
       </source>
       <p>
-        We just changed the border-style to 'solid' and the color to '#000000'. In our we
we have to add
-        a new tag to tell that we want to override the default.css. We are doing this by
adding the tag 
-        <code><![CDATA[<forrest:css url="howTo.css"/>]]></code> to
our view.
+        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 
+        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>!!!
       </note>
-      <fixme author="thorsten">This section is next to be writen</fixme> <!--
       <source><![CDATA[<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0"
>
   <forrest:view type="xhtml">
+  	<forrest:css url="howTo.css"/>
     <forrest:hook name="leftbar">
       <forrest:contract name="nav-section"/>
     </forrest:hook>
     <forrest:contract name="content-main"/>   
   </forrest:view>  
 </forrest:views>]]>
-      </source>-->
+      </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

+         <code><![CDATA[<forrest:hook name="content"/>]]></code>
We need to add the new layout container
+         to our howTo.css:
+      </p>
+      <source>
+/* The actual content */
+#content {
+    margin-left: 25%;
+    padding: 0 20px 0 20px;
+    background: #B9D3EE;
+}
+      </source>
+      <p>
+        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">
+  	<forrest:css url="howTo.css"/>
+    <forrest:hook name="leftbar">
+      <forrest:contract name="nav-section"/>
+    </forrest:hook>
+    <forrest:hook name="content">
+      <forrest:contract name="content-main"/>
+    </forrest:hook>  
+  </forrest:view>  
+</forrest:views>]]>
+      </source>
+      <p>
+        We are now able to place contracts into layout container and add custom css to the
view.
+      </p>
+      <fixme author="thorsten">
+        Let us now look into advanced features of views. 
+        I will write a how-to for advanced contracts soon. :)
+      </fixme>
+      <!--<fixme author="thorsten">This section is next to be writen/finished</fixme>-->

     </section>
   </steps>
   <extension title="Further Reading">

Modified: forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml?rev=190207&r1=190206&r2=190207&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs/howto/howto-view-install.xml Sat Jun 11 20:35:28
2005
@@ -122,6 +122,33 @@
 way. You will see you do not have to build your project to see the
 changes on your pages when working with *.fv. </note>
     </section>
+    <section id="availableContracts">
+	    <title>Available contracts</title>
+	    <p> 
+	     To start working with views you need to know which contracts you can use. 
+	     For this we will install another plugin <code>org.apache.forrest.plugin.input.viewHelper.xhtml.ls</code>.
+	     The setup is:
+	    </p>
+	    <source>
+cd {forrest-trunk}
+svn up
+cd whiteboard/plugins/org.apache.forrest.plugin.input.viewHelper.xhtml.ls/
+ant local-deploy
+</source>
+			<p>
+        The newly installed plugin will show the available contracts as html page.
+        First we have to tell forrest that we are planing to use the new plugin. We will
do that
+        by editing the forrest.properties of the <a href="site:howto/view/install">newSeed</a>

+        to <strong>add</strong> the plugin:
+      </p>
+      <source>
+project.required.plugins=org.apache.forrest.plugin.input.viewHelper.xhtml.ls
+      </source>
+      <p>
+        Now point your browser to <code>http://localhost:8888/ls.contracts.html</code>.

+        On this page you will find all contracts that you can use in your project.
+      </p>
+    </section>
   </steps>
   <extension title="Further Reading">
     <p>



Mime
View raw message