A new document has been created.
http://cocoon.zones.apache.org/daisy/cocooninaction/679.html
Document ID: 679
Branch: main
Language: default
Name: Design considerations
Document Type: Simple Document
Created: 8/22/05 1:34:07 PM
Creator (owner): Helma van der Linden
State: draft
Parts
=====
Content
-------
Mime type: text/xml
Size: 11619 bytes
Content:
<html>
<body>
<h1>Website Revision 1</h1>
<p>Before we can actually start coding, it is good to make some decisions first,
to avoid having to redo everything because you forgot to take some essentials
into account.</p>
<h2>Design decisions</h2>
<p>At first, the text is turned into webpages. The introduction text will be on
the home page, the addres on the contact page. Some decisions have to be made:
</p>
<ul>
<li>How to set up the pages</li>
<li>How to prepare for future multiple languages</li>
<li>How to set up the navigation</li>
</ul>
<h3>Page setup</h3>
<p>If you are not bound to a strict format, you can basically define your own
DTD or XML Schema that your pages have to validate against. You can make up your
page with HTML tags from the start, follow a standard or define your own tag or
any combination of all this. There are some arguments in favor of building your
own tags. First of all, the separation of concerns. This is high on Cocoon's
priority list and applies not only to the code but also to the content: i.e.
separate content from display. This basically rules out using HTML tags for your
content markup, as HTML is very limited in that regard. <br/>
You can follow a standard markup like Docbook, but that might be overkill in
this case. On the other hand, should a transformation to Docbook be required
later on, you can probably transform you home-grown tags into Docbook with a
clever XSLT stylesheet.</p>
<p>So, let's define a set of tags for the current pages.</p>
<p>Here is a definition of a typical page layout with an explanation between the
tags.</p>
<pre><page> <!-- this is the root element -->
<header>
<!-- this contains the title of the page, as displayed in the browser
title bar, specific CSS, JS
and other files that are only used in this page
-->
<title>Title as it will show up in the title bar of the
browser</title>
</header>
<content>
<banner>This will be the "name" of the page, the equivalent of the
title of a book chapter</banner>
<text>This will contain the main content of the page.
In this text regular HTML is used for basic layout such as paragraphs
(<p>),
lists (<ul>, <ol> and <li>) and emphasis
(<strong> and <em>). If this is not sufficient
to properly mark the type of the information, more tags will be added.
</text>
</content>
</page>
</pre>
<h3>Multiple languages</h3>
<p>Since we already know the site will be available in three different
languages, we might as well make sure this can be added without much
modification. Cocoon provides the Internationalisation functionality
<strong>i18n</strong>. It comes down to writing different catalogue files, one
for each language, that contain key/value pairs of the information that should
be translated. Although this is a great and flexible system, in my personal
opinion there are a few drawbacks:</p>
<ul>
<li>The catalogue files are cumbersome to maintain, i.e. you have to update (in
our case) three separate files when you want to add or modify a key.</li>
<li>If you use this system for all multi-lingual information, you are tucking
away content in files that are more system-related than content-related.</li>
<li>Currently, Cocoon (2.1.7) has a minor bug which requires a restart of Cocoon
to read the updated i18n catalogue files.</li>
</ul>
<p>That said, the i18n system is still useful for fixed concepts and short
messages, like page titles, button names, names of weekdays and months etc. The
"real" content will be entered in the pages as described above. This makes
translation of the actual content easier and all translations will be together
in one page, so there is less of a chance to forget to update a file.</p>
<p>To separate the different language sections, a new set of tags is defined:
</p>
<pre><langselect>
<select lang="en">English text here</select>
<select lang="nl">Nederlandse tekst komt hier</select>
<select lang="fr">Texte francaise est ici</select>
</langselect>
</pre>
<p>Later we will devise an XSLT stylesheet that will extract the selected
language and ignore the other. This way, it is possible to not only use these
tags as "toplevel" tags in the <text> section, but also in any lower level
tag. E.g. when a page mostly consists of standardized text, except for the last
paragraph, then it is much more efficient to use i18n tags for the standardized
text and only wrap the last paragraph in <langselect> tags.</p>
<h3>Navigation</h3>
<p>We want users to be able to switch to any language at any time, which means
we need to provide a language switch mechanism at each page.<br/>
We also want a simple lefthand side vertical menu. For now that would be
sufficient, but once the site grows, it is good to add a sitemap, so we want one
file that can be used as input to both the menu and the sitemap.<br/>
Of course the menu and the sitemap should be in three languages as well.</p>
<h3>Output</h3>
<p>We want the final output to be valid XHTML 1.0 Transitional. Layout is done
through CSS in separate CSS files, inline styles are only used for occasional
exceptions. All CSS used should be valid as well. And of course it should all be
UTF-8.</p>
<h3>Directory structure vs URL structure</h3>
<p>Cocoon allows a separation of the directory structure and the URL structure,
i.e. the URL does not have to match the underlying directory structure. It is in
fact even better to separate them, since it allows you to get the best of both
worlds: good looking URLs and an easy to use directory structure.</p>
<p>The website is currently very small and will probably not grow into an
enormous amount of pages. It is therefore a good idea to just keep it into a
flat structure with all pages at the same level. If we add the language to the
URL, it is flexible enough to directly point to the appropriate page.</p>
<p>Cocoon's sitemap allows you to map any directory structure to any URL
structure, which gives you the opportunity to create a directory structure that
is more geared towards the developer. This is a structure that works for me:</p>
<pre>/webapproot -- the toplevel of your webapp
/content -- holds all files that contain the actual content (in
text)
/images -- holds context-related images, e.g. a photo gallery
of a special event
/resources -- holds all resources, such as images, css files,
clientside javascripts
/img -- holds "static" images such as logo, layout
supporting images etc.
/css -- holds the necessary CSS files
/js -- clientside scripts
/system -- system files, i.e. files necessary to Cocoon to
render the proper output
/scripts -- serverside (flow) scripts (if necessary)
/forms -- Cocoon forms (if necessary)
/xsl -- XSLT files that transform your content into XHTML
pages</pre>
<h2>Let's get to work</h2>
<p>Now that decisions are made, it is time to put it all to work. First, fire up
Eclipse, open your <em>HealthyCocoon </em>project and create the directory
structure as outlined above under <em>/src/cocoon/webapp/healthycocoon</em> of
your project. Note that <em>healthycocoon </em>is the "root" directory under
<em>webapp</em> and thus <em>webapproot </em>in the description above. This
makes your project a subproject of the Cocoon webapp. This way, the project
sitemap can remain small. The "root" sitemap (i.e. the default sitemap installed
during the installation of Cocoon) remains untouched and provides a default
setup for most definitions and URLs.</p>
<h3>Create the home page</h3>
<p>The home page will contain the information about HealthyCocoon. It will be
the first page to be shown when the domainname is entered and where all
non-existing pages will be directed to.<br/>
Create a new XML file in <em>src/cocoon/webapp/healthycocoon/content</em> and
name it <em>home.xml</em>. Copy or type the page template, explained above and
set the <tt>title </tt>and <tt>banner </tt>to 'HealthyCocoon welcomes you'. Copy
or type the text about HealthyCocoon between the <tt>text </tt>tags. Save the
file.<br/>
It looks like this:</p>
<pre><page>
<header>
<title>HealthyCocoon Welcomes You</title>
</header>
<content>
<banner>HealthyCocoon Welcomes You</banner>
<text>
<p>
HealthyCocoon is a hip restaurant located in the centre of Maastricht,
The
Netherlands. Maastricht is practically on the Belgian border and only
some 30 km
from the German border, which explains our international clientele.
</p>
<p>
We intend to spoil our customers by serving them fresh, healthy and
nutritional
food served in eye-pleasing and tongue-caressing dishes. Not only do
we have ample
seating inside, but we also have tables and comfortable chairs set up
outside for
those nice days in spring, summer and autumn.
</p>
<p>If you are in a rush, you will find that our dishes are also
great for takeaway.</p>
</text>
</content>
</page></pre>
<h3>Create the contact page</h3>
<p>Repeat the steps above to create <em>contact.xml</em> which contains the
addres of HealthyCocoon. Choose an appropriate title and banner. It looks like
this:</p>
<pre><page>
<header>
<title>HealthyCocoon - Contact</title>
</header>
<content>
<banner>Where to find us</banner>
<text>
<p>
HealthyCocoon is located at:
</p>
<p>
Webappstreet 25<br/>
1234 AB Maastricht<br/>
The Netherlands<br/>
</p>
<p>
You can reach us:<br/>
By phone: +31 43 1234567<br/>
By fax: +31 43 1234568<br/>
By email: [EMAIL PROTECTED]<br/>
</p>
</text>
</content>
</page></pre>
<p class="note">Since these files are XML, you are required to write valid XML.
This means that using HTML tags also requires you to conform to valid XML, hence
the <tt><br/></tt> and the closing <em></p></em>.</p>
<h3>Putting it to screen</h3>
<p>Now that you have written the content to start with, it is time to focus on
how to get it to display on screen. For that we need two things:</p>
<ul>
<li>Something, an XSLT stylesheet, that transforms your pages into XHTML.</li>
<li>Something, a sitemap, that does the directory-to-URL mapping as discussed
before.</li>
</ul>
<h3>ToXHTML.xslt</h3>
<p>The XSLT stylesheet that transforms the internal markup to XHTML is
conveniently named <em>ToXHTML.xslt</em>. Create an XSL document in
<em>src/cocoon/webapp/healthycocoon/system/xsl</em>. For now we will create the
simplest stylesheet possible. Enhancements will be added later.<br/>
Create the stylesheet yourself and check if it matches the one below or simply
copy and paste.</p>
<p>[TODO:<br/>
- create xsl files that transform the xml<br/>
- explain about pipelines (enough to understand why there are different xsl
files)<br/>
- create a minor sitemap.xmap<br/>
- run cocoon -> test (only 2 pages, no menu, no language switch, only through
URL modification)<br/>
]</p>
</body>
</html>
Collections
===========
The document belongs to the following collections: ciatutorial
