A document has been updated:
http://cocoon.zones.apache.org/daisy/cocooninaction/677.html
Document ID: 677
Branch: main
Language: default
Name: The first pages (unchanged)
Document Type: Simple Document (unchanged)
Updated on: 8/22/05 1:33:39 PM
Updated by: Helma van der Linden
A new version has been created, state: draft
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 1040 bytes (previous version: 12629 bytes)
Content diff:
(31 equal lines skipped)
<p>[TBD]</p>
--- <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>
Fields
======
no changes
Links
=====
no changes
Custom Fields
=============
no changes
Collections
===========
no changes
