You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lenya.apache.org by an...@apache.org on 2007/11/16 16:12:50 UTC
svn commit: r595691 [18/28] - in /lenya/sandbox/pubs/docu: config/
content/authoring/ content/authoring/0033e320-8731-11dc-ae46-9e7b5d14892d/
content/authoring/018a9980-8731-11dc-ae46-9e7b5d14892d/
content/authoring/02f9e0f0-8731-11dc-ae46-9e7b5d14892d...
Added: lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.1195221898575.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.1195221898575.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.1195221898575.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.1195221898575.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!-- $Id: index.xml 55543 2004-10-26 00:14:59Z gregor $ --><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>Working with Documents</title>
+ </header>
+ <body>
+
+ <p>
+ This document shows some simple scenarios to access the Lenya repository.
+ For more information, refer to the <a href="lenya-document:35e35370-8731-11dc-ae46-9e7b5d14892d">repository documentation</a>.
+ </p>
+
+ <section>
+ <title>The Session</title>
+ <p>
+ An <code>o.a.l.cms.repository.Session</code> is a temporary container for
+ repository nodes which you want to work with. If you want to change or remove
+ nodes - for instance in a usecase handler - you have to start a transaction.
+ To avoid overriding or losing someone else's changes, you should lock any nodes
+ which are potentially affected or read during your transaction.
+ </p>
+ <p>
+ A convenient way to get the session which is attached to the current request
+ is provided by the <code>RepositoryUtil</code>:
+ </p>
+ <source xml:space="preserve">Session session = RepositoryUtil.getSession(this.manager, request);</source>
+ </section>
+
+ <section>
+ <title>The Document Factory</title>
+ <p>
+ The <code>o.a.l.cms.publication.DocumentFactory</code> is the main entry point to the content
+ repository. It is tied to a session. You get the document factory which is
+ attached to the current session this way:
+ </p>
+ <source xml:space="preserve">DocumentFactory factory = DocumentUtil.getDocumentFactory(this.manager, request);</source>
+ </section>
+
+ <section>
+ <title>Browsing Content and Site Structure</title>
+ <p>
+ From the document factory, you can access a publication:
+ </p>
+ <source xml:space="preserve">
+String webappUrl = ServletHelper.getWebappUrl(request);
+URLInformation info = new URLInformation(webappUrl);
+Publication pub = factory.getPublication(info.getPublicationId());
+</source>
+
+ <p>
+ The publication provides access to all areas (pun intended).
+ An area object enables you to obtain documents by their UUID.
+ </p>
+ <source xml:space="preserve">
+Area authoring = pub.getArea("authoring");
+Document[] docs = authoring.getDocuments();
+Document doc = authoring.getDocument(uuid, language);
+</source>
+
+ <p>
+ If you want to obtain a document by its path in the site structure,
+ get the site structure from the area:
+ </p>
+ <source xml:space="preserve">
+SiteStructure site = authoring.getSite();
+SiteNode node = site.getNode("/tutorial");
+String[] languages = node.getLanguages();
+Link link = node.getLink(language);
+Document doc = link.getDocument();
+</source>
+
+ <p>You can also browse the document structure in a bottom-up way:</p>
+ <source xml:space="preserve">
+Document doc = ...;
+doc.area().getPublication();
+String area = doc.getLink().getNode().getStructure().getArea();
+</source>
+
+ <p>
+ The Document class allows to access different language and area versions
+ of the document:
+ </p>
+ <source xml:space="preserve">
+if (doc.existsTranslation("en")) {
+ englishVersion = doc.getTranslation("en");
+}
+if (doc.existsVersion("live", doc.getLanguage()) {
+ addInfoMessage("Live version exists!");
+ liveVersion = doc.getVersion("live", doc.getLanguage());
+}
+</source>
+ </section>
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221898575.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221898575.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221898575.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221898575.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Working with Documents</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/988cb350-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221898575" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221887690"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910794458" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910766600"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781626788" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.1195221894590.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.1195221894590.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.1195221894590.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.1195221894590.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>Authoring and Live Mode</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Introduction</title>
+
+ <p>Lenya has two modes it can run in:</p>
+ <ul>
+ <li>In Authoring mode it is a web application enabling editors
+ to interactively manipulate the structure as well as the content of a publication.</li>
+ <li>In Live mode it will render a publication as a website.</li>
+ </ul>
+
+ <section>
+
+ <title>Authoring Mode</title>
+
+ <p>Authoring a publication involves a number of different tasks:</p>
+ <ul>
+ <li>Creating new documents</li>
+ <li>Moving documents around in the sitetree</li>
+ <li>Editing a document's content</li>
+ <li>Editing a document's metadata</li>
+ </ul>
+
+ <p>but also:</p>
+
+ <ul>
+ <li>Editing a publication's metadata</li>
+ <li>Managing the resource types and editors available</li>
+ <li>Maintaining access control policies both for editing and for the live publication</li>
+ </ul>
+
+ <p>Transactions that manipulate the publication are implemented through usecases, using the
+ Usecase Framework. There are for example usecases that:</p>
+
+ <ul>
+ <li>Create a new document</li>
+ <li>Delete a document</li>
+ <li>Edit a document's metadata</li>
+ <li>Call an editor to edit the document's content</li>
+ </ul>
+
+ </section>
+
+ <section>
+
+ <title>Live Mode</title>
+
+ <p>The Live Mode is all about presenting a publication to the viewer.</p>
+ <p>HTTP requests are passed through a Cocoon sitemap which will then
+ use the appropriate generators, transformers and serializers which will
+ return a page to the browser in reply to the request.</p>
+
+ <section>
+ <title>Serving a Lenya publication with plain Cocoon only?</title>
+ <p>The fact that Live Mode is all about serving pages controlled by
+ a sitemap often raises the question if it was possible to serve a
+ publication that has been edited with Lenya from a plain Cocoon instance.</p>
+ <p>Sometimes this might be a requirement if the production site offers Cocoon
+ hosting but not Lenya hosting for example. Also some architects feel better
+ if the editor portion is not at all installed on an outside facing prodction
+ server.</p>
+ <p>While it would theoretically be possible, at the time of writing a Lenya
+ publication will need Lenya even for Live mode. The reason is that the sitemaps
+ use some custom Cocoon components that are part of Lenya, such as the PageEnvelope
+ input module for example.</p>
+ <p>Again, it would be possible to extract these components from Lenya and package
+ them with a plain instance of Cocoon to achive to goal of having a "Live mode only"
+ version of Lenya that will not allow any editing. Yet this work has not yet been done.</p>
+ </section>
+
+ </section>
+
+ </section>
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221894590.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221894590.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221894590.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221894590.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Authoring and Live mode</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/99b1f970-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221894590" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221881082"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910792322" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910765397"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781618688" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.1195221911662.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.1195221911662.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.1195221911662.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.1195221911662.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>WYSIWYG</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Why WYSIWYG is good ...</title>
+
+ <p>WYSIWYG (pronounce "vee-zee-weeg") stands for "What you see is what you get". To make most
+ people who's personal experience with computers does not at least date back into the 80ies, a little
+ history lesson is needed here. In case you have even used punch cards or you are a *IX person who
+ knows why vi is considered a visual editor (compared to ed), this section will not contain a lot of
+ news for you and you can safely skip to the next section. Anyone who grew up with windows
+ and mice read on.</p>
+
+ <section>
+
+ <title>Editing without WYSIWYG</title>
+
+ <p>An electronic document - for example an HTML page - is nothing but a file on your system
+ which contains a character stream. You can edit an HTML page with a simple text editor such as
+ vi or Notepad. In that case, you have to put HTML tags into your text and ensure yourself that
+ the resulting file is valid and can be rendered by the browser.</p>
+
+ <p>This has nohting to do with WYSIWYG at all, as what you see on your screen while editing
+ looks entirely different than what you will see later in your browser when the HTML file is rendered.</p>
+
+ <p>While many people might have written their first HTML pages in a text editor, today it's hard
+ to imagine that early word processors worked the same way. You could not just select a word and hit
+ a button to make the world bold and immediately see the result, but you had to put control
+ characters into your text and could only see the result on paper after you printed the text to paper.
+ In the early days of word processing, the software did not even understand the control characters
+ but just sent them to the printer. Introducing printer independent control characters, which
+ were than mapped to the specific escape codes for a specific make and model of a printer
+ was already the first step of abstraction, which was considered an innovation when it was introduced.</p>
+
+ <p>Early word processors operated in text only mode which means that you cannot display different fonts,
+ font sizes of even bold or italic script on the screen at all. Later there have been graphic cards that
+ were able to display attributes such as bold or italic type, but it was never possible to display different
+ font sizes in text mode. Some word processors tried to compensate this by using colors.</p>
+
+ </section>
+
+ <section>
+
+ <title>WYSIWYG hides complexity from the user</title>
+
+ <p>The introduction of graphical user interfaces probably was the single most important enabler
+ to WYSIWYG word processors as well as any other kind of WYSIWYG editors, for example for spreadsheets,
+ presentation slides or illustrations.</p>
+
+ <p>With WYSIWYG (together with some other technologies such as Postscript or TrueType fonts) it was
+ possible to display a text exactly the way it will be printed later. You don't see any control
+ characters any more on your screen (though they are still in the character stream) but you can
+ select a part of the text and assign a font, font size or attributed such as bold or italics. And
+ afterwards, you get an immediate visual feedback of what you have done and you can decide if this
+ is really what you intended to do.</p>
+
+ <p>WYSIWYG has two obvious advantages:</p>
+ <ul>
+ <li>The user does not have to learn any control characters or tags, but he or she can manipulate
+ the document through clicking on intuitive buttons and other GUI widgets, for example a drop down
+ list of available fonts.</li>
+ <li>You don't have to imagine how your document will look like later but you can see it building up
+ in front of your eyes. For example, you can type a text first and then mark and format the headlines.
+ Editing a large text document or even a graphical document without WYSIWYG requires a lot of imagination
+ or a lot of experience with similar document types to avoid having too many interations of putting something
+ in, than having to render it for preview and then going back to the source code.</li>
+ </ul>
+
+ <p>The introduction of WYSIWYG word processors lead to a whole wave of WYSIWYG tools. It became next to
+ impossible to sell any new application that could not claim it was WYSIWYG. Besides word processors, it
+ was HTML editors and page layout systems (DTP) which became increasingly popular.</p>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>... and why WYSIWYG can be bad as well</title>
+
+ <p>If you are looking for an example of the limits of WYSIWYG, take a look at the idea of "visual programming".</p>
+
+ <p>Some of the most powerful software companies as well as some smaller innovative companies have tried to
+ deliver on the promise that it will be possible to replace writing of source code with clicking together
+ components visually using the mouse. Aside from very specific aspects such as GUI design and linking data to a
+ GUI nobody ever really made it.</p>
+
+ <p>Depending on who you ask and depending on your personal point of view, you may pick from one of these two
+ explainations:</p>
+ <ul>
+ <li>It cannot be done.</li>
+ <li>It does not make sense.</li>
+ </ul>
+
+ <p>The idea of visual programming is a bit like trying not to write a letter or a novel character by
+ character but by choosing text blocks from a library. It can certainly be done but you are very limited
+ in the thoughts that you can express. If you try to express a thought that is new and has never been
+ expressed with this system before, you cannot.</p>
+
+ <p>Taking it back on a technical level, there is a danger that indifferent application of the WYSIWYG
+ idea leads to either oversimplifying things or having to build a GUI that is overly complex and not intuitive
+ at all.</p>
+
+ </section>
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221911662.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221911662.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221911662.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221911662.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>WYSIWYG</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/9ae06750-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221911662" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221891472"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910794005" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910766409"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781620303" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.1195221902283.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.1195221902283.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.1195221902283.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.1195221902283.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,244 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>Overview of the Lenya Sitemaps</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Introduction</title>
+ <p>Lenya is based on Apache Cocoon. To understand how Lenya works, you should have at least some basic
+ Cocoon knowlege. Make sure you know what a Cocoon sitemap is and you understand matchers, generators,
+ transformers and serializers at least.</p>
+ <p>Lenya uses some more Cocoon components, but if you can spot the matchers, generators, transformers and
+ serizalizers, you will be able to get a good first overview of the Lenya sitemaps.</p>
+ <p>But Lenya is much more than just a collection of sitemaps and some XSLT stylesheets. Lenya builds on
+ the Cocoon foundation and extends the Cocoon framework with custom</p>
+ <ul>
+ <li>Matchers</li>
+ <li>Actions</li>
+ </ul>
+
+ <p>Beyond these components, Lenya also defines two proprietary schemes:</p>
+ <ul>
+ <li>lenya:</li>
+ <li>fallback:</li>
+ </ul>
+
+ <p>These schemes are linked to a custom input module that comes with Lenya, the</p>
+ <ul>
+ <li>PageEnvelope input module</li>
+ </ul>
+ </section>
+
+ <section>
+ <title>Authoring Area, Live Area, CMS GUI and several Publications</title>
+ <p>A Lenya installation aggregates a number of different parts into
+ a single Cocoon application. By default, one instance of Lenya can be used
+ to edit and render an arbitrary number of publications which are entirely
+ independent of each other.</p>
+ <p>There are different concepts of what a publication is, but for now,
+ let's assume each publication represents an independent website.</p>
+ <p>Inside each publication, there are</p>
+ <ul>
+ <li>The authoring area</li>
+ <li>The live area</li>
+ <li>The CMS GUI components (Drop Down Menu, CMS screens, editos, ...)</li>
+ </ul>
+ <p>The URI space is used to organize all this.</p>
+
+ </section>
+
+ <section>
+ <title>The Lenya URI space</title>
+ <p>If you run Lenya in built-in Jetty servlet container, the Lenya webapp
+ is the root application of the container. Therefore http://localhost:8888/ will
+ already hit the Lenya root sitemap.</p>
+ <p>In case you deployed lenya into a non-root context of any servlet container, the first
+ part of the URI will be handled by the container itself to match the responsible webapp.</p>
+ <p>If you deployed lenya.war into Tomcat for example, you will most likely have to use
+ http://localhost:8080/lenya/ to get into the Lenya root sitemap.</p>
+ <p>For the rest of this document, we pretend Lenya is the root webapp in your container
+ as this is the case with the built-in Jetty. Let's examine , what Lenya does in order to
+ render the document you see when you enter this URL:
+ <code>http://localhost:8888/default/authoring/tutorial/new_doctype.html</code>
+</p>
+
+ <section>
+ <title>Part 1: The publication ID</title>
+ <p>The first part is the publication id <code>default</code> which selects the <em>Default
+ Publication</em>. There is a difference between the publication ID and the name of the publication.
+ The ID should be compatible to both the filesystem implementation as well as the URI encoding
+ because it will become both the name of the publication directory and a part of the URL. Therefore
+ it is good practice to stick to 7-bit ASCII with no spaces or special characters.</p>
+ <p>In contrast, the display name of the publication (which will show up in the list of publications
+ on the main Lenya entry screen) can be longer and it can contain spaces as well as any
+ Unicode characters.</p>
+ <p>The publication ID is used to mount the publication specific sitemap.xmap from
+ <code>$LENYA_HOME/pubs/{publication-id}</code>. The <code>map:mount</code> will strip the publication ID
+ from the URL, so the publication sitemap will just see the
+ <code>authoring/tutorial/new_doctype.html</code> portion. Nevertheless a publication has its ID
+ available through the page envelope. More on that later as we're not yet really inside the publication's
+ content.</p>
+ </section>
+
+ <section>
+ <title>Part 2: The area</title>
+ <p>There are two possible areas.</p>
+ <ul>
+ <li>Authoring</li>
+ <li>Live</li>
+ </ul>
+ <p>You can think of areas as of modes, as in "live mode" and "authoring mode". Live mode is
+ the view of the publication as it is supposed to be displayed on the website to the site
+ visitor. The authoring mode is used by editors and reviewers to edit the publication's content.</p>
+ <p>Technically speaking, the first major difference between the authoring area and the live area is just
+ that in authoring mode the CMS menus are displayed. Following the WYSIWYG principle of Lenya,
+ the publication content is rendered the same way in authoring mode as it would be in live mode.</p>
+ <p>Besides displaying the CMS menus or not, there are different copies of the underlying content
+ repository for the authoring and live areas. This allows the editors to edit a working copy
+ without affecting the live site. When a document is published after it was reviewed, it is
+ just beeing copied over to the live repository.</p>
+ <p>If you're using the default filesystem repository of Lenya, you will find the two different
+ repositories under <code>$LENYA_HOME/lenya/pubs/content/authoring</code> and
+ <code>$LENYA_HOME/lenya/pubs/content/live</code>.</p>
+ <p>As well as the publication ID the area is also stored in the page envelope. This will make
+ the actual area available to both the sitemap through the page envelope input module as well as
+ to the components in the Java layer of Lenya.</p>
+ <p>At this point, Lenya parsed the URL to the point that is knows:</p>
+ <ul>
+ <li>which publication the request belongs to</li>
+ <li>which repository is to be used, authoring or live</li>
+ <li>wether to display the CMS menus or not</li>
+ </ul>
+ <section>
+ <title>CMS Menus, Usecases and CMS screens</title>
+ <p>Prior to finally turning over to the actual publication content, some remarks
+ on the CMS menus and CMS screens.</p>
+ <p>Lenya uses so-called usecases to perform actions. There are usecases such as</p>
+ <ul>
+ <li>submit (a document)</li>
+ <li>publish (a document)</li>
+ <li>...</li>
+ </ul>
+ <p>The CMS menus are nothing but a convenience mechanism for the CMS user to trigger usecases.
+ As an alternative to choosing the "Workflow"->"Submit" menu option, you could as well append
+ <code>?lenya.usecase=workflow.submit</code> to the document URL. As soon as Lenya finds a lenya.usecase
+ request parameter it will branch into the <code>lenya/usecases/usecase.xmap</code> sitemap.</p>
+ <p>All usecases start in the Lenya core. The core contains most of the common access control,
+ workflow and editing usecases. A publication can introduce publication specific usecases.</p>
+ <p>Some usecases require CMS screens to be displayed. These are rendered through the usecase
+ sitemap portions as well. That way one could for example introduce a new skin for the CMS
+ screens just by means of the Cocoon sitemap.</p>
+ <p>For details on usecases, have a look at the
+ <a href="lenya-document:9ffa4030-8730-11dc-ae46-9e7b5d14892d">Lenya Usecase Framework</a>.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <title>Part 3: The document URL</title>
+ <p>Now it's the publication sitemap's task to take the document URL portion of the
+ original URL (<code>tutorial/new_doctype.html</code> in our example) and generate and
+ render the content page. This sounds easy, but turns out to be quite complex. This
+ portion is actually the heart and soul of every CMS. This is also where differnt
+ CMS have a lot of differences in terms of features and configurability.</p>
+ <p>The easiest way to deal with this would be:</p>
+ <ul>
+ <li>Choose the appropriate content repository (authoring or live)</li>
+ <li>Use the document URL to look for a file with that name and generate it.</li>
+ <li>If necessary: Apply an XSLT stylesheet and serialize the result.</li>
+ </ul>
+ <p>Lenya can do a lot more here, such as:</p>
+ <ul>
+ <li>Use a publication specific mapper class to map the document URL to a backend
+ repository URL. This will allow you to hide the actual repository structure from
+ the website visitor.</li>
+ <li>Apply some intelligence to decide what language version of the document to use.
+ For example, it no specific language version is requested, Lenya will choose the
+ default language. If there is a specific language requested, Lenya will apply a mapping
+ to built a back-end respository path to query for the requested language and generate this
+ if it is available. If the document is not available in the requested language, Lenya will
+ fall back to the default language again.</li>
+ <li>Choose among a selection of different rendering pipelines based on the source document's
+ resource type. A resource type can be XHTML, but also any other XML format such as RSS,
+ SVG, SlideML or whatever.</li>
+ </ul>
+ <p>Most of this logic is implemented in the Java layer. The components are Avalon components
+ which are configured on a per-publication basis. In other words: One could implement and plug
+ in custom versions of these components.</p>
+ <p>Only the mapping between input URL and the path used to access the repository in the backend
+ is implemented as an Avalon component in Java. The actual rendering of the document is done
+ by the means of Cocoon sitemaps, thus allowing anyone with Cocoon knowledge to make changes to
+ the rendering pipelines whithout having to write Java code.</p>
+ <p>An example of an entirely different mapping between the document URL and the repository
+ is the Lenya Weblog publication that comes as a second sample with the Lenya distribution.</p>
+ </section>
+
+ <section>
+ <title>Part 4: The usecase parameter (optional)</title>
+ <p>Right after the document URL there may be
+ an additional parameter,
+ <code>lenya.usecase=$USECASE</code>.</p>
+ <p>For an explaination of this usecase parameter, see the
+ <a href="lenya-document:9ffa4030-8730-11dc-ae46-9e7b5d14892d">usecase framework</a>.</p>
+ </section>
+
+<section>
+<title id="head-fbc9e3a3c8fa10b2383dbed3e8d0afbfc73fa211">The "lenya:" scheme</title>
+
+<p>When reading the sitemaps in Lenya 2.0 you probably came across the lenya-scheme, often also referred to as the lenya protocol. For example, in the doctypes.xmap, you will find this section: </p>
+
+<source xml:space="preserve">
+ <!-- parametrized doctype matcher -->
+ <!-- pattern="{rendertype}/{area}/{doctype}/{document-path}" -->
+ <map:match pattern="*/*/*/**.xml">
+ <map:generate src="lenya:/{4}.xml"/>
+ <map:transform src="fallback://xslt/{3}2xhtml.xsl">
+
+</source>
+<p>The lenya: scheme just needs the document path to locate the source document, i.e. lenya:/concepts/index_en.xml. All other elements of the actual storage location of the document (publication id and area) will be read from the page envelope and interpreted in the LenyaSourceFactory. </p>
+<p>In other words: The lenya: scheme hides the storage implementation details from the sitemap. </p>
+
+<section>
+<title id="head-6e96c3b9146b3a1dcac05ffbfa66643b3bf9a363">What is a scheme?</title>
+
+<p>The lenya scheme is a virtual protocol in Cocoon, similar to the cocoon and context scheme. </p>
+<p>Note: In case you are not familiar with the latest official naming of the components of a URI or you still think that a URL is the same as a URI, please read this: <a href="http://www.bernzilla.com/item.php?id=100"> http://www.bernzilla.com/item.php?id=100</a>. </p>
+<p>The two sentence summary: </p>
+
+<p>The URI <a href="http://lenya.apache.org/"> http://lenya.apache.org/</a> is a URL. The URL is a special case of a URI. "http" is the scheme, which in a URL referes directly to a TCP/IP protocol. The part left of the colon (http) defines how the part right of the colon (//lenya.apache.org/) is to be interpreted by selecting an appropriate handler. </p>
+<p>The JDK provides build-in mechanisms to handle many common schemes such as file, http, ftp and some more. But Cocoon adds an additional layer through its Excalibur SourceResolver system, see: <a href="http://excalibur.apache.org/sourceresolve/index.html"> http://excalibur.apache.org/sourceresolve/index.html</a>. </p>
+<p>Lenya hooks in there with the LenyaSourceFactory which defines the lenya schema. The actual implementation is in the org.apache.lenya.cms.cocoon.source.LenyaSourceFactory class, see </p>
+<ul>
+<li>
+<p> <a href="http://lenya.apache.org/apidocs/1.4/org/apache/lenya/cms/cocoon/source/LenyaSourceFactory.html">LenyaSourceFactory JavaDoc</a> </p>
+
+</li>
+<li>
+<p> <a href="http://svn.apache.org/viewcvs.cgi/lenya/trunk/src/java/org/apache/lenya/cms/cocoon/source/LenyaSourceFactory.java"> LenyaSourceFactory source code</a> </p>
+</li>
+</ul>
+</section>
+</section>
+</section>
+
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902283.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902283.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902283.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902283.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Overview of Lenya Sitemaps</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/9c1ae320-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221902283" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221881283"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910785225" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910769614"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781624283" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.1195221902344.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.1195221902344.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.1195221902344.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.1195221902344.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>The Lenya Content Repository</title>
+ </header>
+ <body>
+
+ <section>
+ <title>The Lenya Repository API</title>
+ <p>
+ The Lenya repository API comprises the following interfaces:
+ </p>
+ <dl>
+ <dt>
+<strong>Repository</strong>
+</dt>
+ <dd>The repository object is the entry point to the Lenya repository. It provides access to
+ the document type registry and allows to create sessions.</dd>
+ <dt>
+<strong>Session</strong>
+</dt>
+ <dd>A session provides access to the publications and methods for transaction handling. Pending
+ changes are not written to the repository until the session is committed.</dd>
+ <dt>
+<strong>Publication</strong>
+</dt>
+ <dd>A publication consists of an arbitrary set of areas.</dd>
+ <dt>
+<strong>Area</strong>
+</dt>
+ <dd>An area consists of a set of content nodes with a site structure associated to them.</dd>
+ <dt>
+<strong>Document</strong>
+</dt>
+ <dd>
+ A document is a language version of a content item. A document is identified
+ within the area by
+ <ul>
+ <li>
+ the <acronym title="Universally Unique Identifier">UUID</acronym> which is shared
+ by all translations of a document, and
+ </li>
+ <li>the language.</li>
+ </ul>
+ <p>
+ Furthermore, documents have the following properties:
+ </p>
+ <ul>
+ <li>the <em>resource type</em> which specifies the content model of the document,</li>
+ <li>the mime type,</li>
+ <li>the content length, and</li>
+ <li>the last modification date.</li>
+ </ul>
+ The document provides access to its content via the methods <code>getInputStream()</code>
+ and <code>getOutputStream()</code>.
+ </dd>
+ <dt>
+<strong>Resource Type</strong>
+</dt>
+ <dd>The resource type of a document denotes the type of contents which may be stored
+ in its documents. A resource type is identified by a unique name. It may provide a
+ schema, which can be used to validate XML contents upon saving.
+ For more information, refer to the <a href="lenya-document:2d466e50-8731-11dc-ae46-9e7b5d14892d">resource types</a>
+ documenation.
+ </dd>
+ <dt>
+<strong>Meta Data</strong>
+</dt>
+ <dd>For more information, refer to the <a href="lenya-document:a7ac0200-8730-11dc-ae46-9e7b5d14892d">meta data</a> documentation.</dd>
+ <dt>
+<strong>SiteStructure</strong>
+</dt>
+ <dd>This interface provides access to the site structure.</dd>
+ <dt>
+<strong>SiteNode</strong>
+</dt>
+ <dd>The site structure is a tree consisting of site nodes. Each site node has an ID which
+ is unique among its siblings. Thus, a site node can be located using a unique path
+ of the form <code>/sections/news/message003</code>. A site node can reference exactly
+ one UUID, but it is possible to have multiple site nodes point to the same UUID.
+ A site node contains a <code>Link</code> object for each translation.
+ This means that <code>/en/news</code> and <code>/de/nachrichten</code> can point to different
+ translations of the same document.
+ </dd>
+ </dl>
+ </section>
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902344.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902344.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902344.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221902344.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Repository</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/9d47ca60-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221902344" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221881339"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910785484" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910770130"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781624476" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.1195221895100.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.1195221895100.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.1195221895100.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.1195221895100.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 1999-2004 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!-- $Id: index.xml 55543 2004-10-26 00:14:59Z gregor $ --><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>Access Control Specification</title>
+ </header>
+ <body>
+ <section id="ac-intro">
+ <title>Access Control Specification</title>
+ <ul>
+ <li>Possibility to deny permissions</li>
+ </ul>
+ </section>
+ <section id="Terminology">
+ <title>Terminology</title>
+ <ul>
+ <li>An accreditable is either a user, a group, an IP range, or the world.</li>
+ <li>A credential is an assignment of a role to an accreditable.</li>
+ </ul>
+ </section>
+ <section id="Names">
+ <title>We use the following names.</title>
+ <ul>
+ <li>n - a node</li>
+ <li>parent(n) - the parent node of n</li>
+ <li>n.c1, ..., n.ci - the credentials of the node n</li>
+ <li>acc(c) - the accreditable which the credential refers to</li>
+ <li>role(c) - the role which the credential assignes to the accreditable</li>
+ <li>method(c) - the method of the credential</li>
+ </ul>
+ </section>
+ <section id="Concept">
+ <title>Concept</title>
+ <ul>
+ <li>Credential methods can be grant or deny.</li>
+ <li>The order of credentials at a node is important.</li>
+ <li>To find out if a certain accreditable a has a role r for the node n, use the following algorithm:
+ <ul>
+ <li>Search for the first matching credential, starting with the first credential of the node n.</li>
+ <li>If no credential of n matches the accreditable, continue with the parent node.</li>
+ <li>When a credential is found which assigns the role r to the accreditable a, return the method of the credential.</li>
+ <li>When a credential is found which assigns the role r to the accreditable a, return the method of the credential.</li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+ <section id="resolving">
+ <title>Role resolving algorithm</title>
+ <ul>
+ <li>while not matched:
+ <ul>
+ <li>for c : n.ci to n.c1: + if acc(c) = a and role(c) = r, return method(c)</li>
+ <li>n := parent(n)</li>
+ </ul>
+ </li>
+ <li>return deny</li>
+ </ul>
+ </section>
+ <section id="gui">
+ <title>User interface</title>
+ <p>The user interface has to allow the following operations:</p>
+ <ul>
+ <li>add/remove credentials for users, groups, world</li>
+ <li>set the credential method</li>
+ <li>change credential order (move up/down)</li>
+ </ul>
+ </section>
+ <section id="samples">
+ <title>Examples</title>
+ <p>Like stated above the order of the credential is important. Credentials are builded
+ from policies. Imaginge you are trying to access
+ http://localhost:8888/default/introduction.html </p>
+ <p>The defined policy (with highest priority) would be:
+ config/ac/policies/introduction.html/subtree-policy.acml. Imaginge you have
+ defined:</p>
+ <source xml:space="preserve"><![CDATA[<policy xmlns="http://apache.org/cocoon/lenya/ac/1.0">
+ <world>
+ <role id="visit" method="deny"/>
+ </world>
+ <group id="editor">
+ <role id="edit" method="grant"/>
+ </group>
+</policy>]]> </source>
+ <p>Then you try to login in with user "lenya" who is in the editor group. However you will
+ not be successful, because everybody always is world. Since the DENY of world is
+ coming first nobody will now be able to see the page. Changing above policy to </p>
+ <source xml:space="preserve"><![CDATA[<policy xmlns="http://apache.org/cocoon/lenya/ac/1.0">
+ <group id="editor">
+ <role id="edit" method="grant"/>
+ </group>
+ <world>
+ <role id="visit" method="deny"/>
+ </world>
+</policy>]]> </source>
+ <p>Let all user of the group editor access the page.</p>
+ <p>Best practise is to deny access early in a node tree of policies for e.g. WORLD.
+ Meaning to define it e.g. in config/ac/policies/authoring/subtree-policy.acml</p>
+ </section>
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221895100.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221895100.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221895100.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221895100.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Access Control Specification</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/9e75ea20-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221895100" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221882033"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910783425" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910768355"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781619728" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.1195221900296.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.1195221900296.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.1195221900296.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.1195221900296.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,472 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>The Usecase Framework</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Introduction</title>
+ <p>A usecase in Lenya means a user triggered action. In most cases, a usecase is triggered by a CMS menu option on
+ a specific document of the publication. This document is the object of the usecases' action (such as edit, delete, publish, ...).</p>
+ <p>There are usecases which are independent of a specific document, such as the <code>ac.logout</code> usecase. In that case it does
+ not matter on what document the usecase is triggered. The part of the request which specifies the document is simply ignored
+ by usecases that are document independent.</p>
+ <p>The CMS menus trigger usecases by setting the <code>lenya.usecase</code> request parameter on the current document. If for example
+ the user selects the <em>Publish</em> option from the <em>Workflow</em> menu, a request will be triggered such as:
+
+<code>
+ GET http://www.server.com/lenya/default/authoring/tutorial.html?&lenya.usecase=publish
+</code>
+</p>
+ <p>The Lenya <code>global-sitemap.xmap</code> will redirect requests with a <code>lenya.usecase</code> request parameter to the
+ <code>$LENYA_WEBAPP/lenya/usecase.xmap</code>
+ sub-sitemap. From version 2.0 on, the following pipeline in this sitemap is used to recognonize usecases which are implemented
+ in Java using the new 2.0 usecase framework:</p>
+<source xml:space="preserve"><![CDATA[
+<map:pipeline>
+ <map:match type="registered-usecase">
+ <map:mount src="usecases/usecase.xmap" uri-prefix="" check-reload="yes" reload-method="synchron"/>
+ </map:match>
+</map:pipeline>]]>
+</source>
+ <p>The <code>registered-usecase</code> matcher's default implementation
+ (<code>org.apache.lenya.cms.cocoon.matching.UsecaseRegistrationMatcher</code>) will use the Avalon
+ component resolver mechanism to resolve the name of the usecase to a an Avalon component. In case it cannot
+ resolve the usecase to an Avalon component, sitemap processing will continue and the usecase is treated in the
+ traditional way using the <code>usecase</code> and <code>step</code> matchers
+ (<code>org.apache.cocoon.matching.WildcardRequestParameterMatcher</code>). In order for this to work
+ correctly, there should be a <code>lenya.step</code> parameter in the request.</p>
+ <p>If the usecase could be resolved successfully into an Avalon component, processing will continue in the
+ <code>$LENYA_WEBAPP/lenya/usecases/usecase.xmap</code> (as opposed to <code>$LENYA_WEBAPP/lenya/usecase.xmap</code>) with
+ the new JX and Java based 2.0 usecase framework.</p>
+ <p>
+ The <em>usecase framework</em> in Lenya 2.0 is a simple framework to implement usecases using JX templates and Java.
+ This approach is an "85% solution". It enables the user to implement a big range of common usecases.
+ </p>
+ <note>
+ Some special complex usecases might require a custom flowscript, in this case you can't use this framework.
+ </note>
+ </section>
+
+ <section>
+ <title>Directory Structure</title>
+
+ <section>
+ <title>The Lenya Core</title>
+<source xml:space="preserve">
+$LENYA_WEBAPP
+ /lenya/usecases usecase-related files
+ /usecase.xmap usecase dispatching sitemap
+ /usecases.js flowscript for usecase control flow
+ /admin Lenya admin usecases
+ /addUser.jx JX templates for usecase views
+ ... more Lenya core usecases
+</source>
+ </section>
+
+ <section>
+ <title>Your Publication</title>
+<source xml:space="preserve">
+$PUB_HOME
+ /lenya/usecases usecase-related files
+ /editHeadline.jx JX templates for usecase views
+ /java/src/... usecase handler classes
+</source>
+ </section>
+
+ </section>
+
+
+ <section>
+ <title>Architecture</title>
+ <p>
+ A usecase request - denoted by the request parameter <code>lenya.usecase</code> - is dispatched by <code>$LENYA_WEBAPP/lenya/usecases/usecase.xmap</code>.
+ All usecases are handled by a single flowscript <code>$LENYA_WEBAPP/lenya/usecases/usecases.js</code>. This keeps javascript maintenance costs at a minimum.
+ </p>
+ <p>
+ The flowscript <code>usecases.js</code> determines the usecase handler class using the <code>org.apache.lenya.cms.usecase.UsecaseResolver</code>.
+ All business code operations are delegated to the usecase handler class.
+ </p>
+ <figure alt="Usecase framework architecture" src="lenya-document:682c4030-8731-11dc-ae46-9e7b5d14892d"/>
+
+ </section>
+
+ <section>
+ <title>The Contract Between Flowscript And Usecase Handler</title>
+ <p>
+ The usecase handler class has to implement the interface <code>org.apache.lenya.cms.usecase.Usecase</code>.
+ The methods of this interface are called in a certain order when the usecase is invoked:
+ </p>
+ <ol>
+ <li>
+<code>setSourceURL(String sourceUrl)</code>
+ <br/>
+ <code>setName(String)</code>
+ <p>Initialize the handler.</p>
+ <br/>
+ </li>
+ <li>
+<code>Passing request parameters</code>
+ <br/>
+ <p>
+ In the next step, all request parameters are passed as parameters to the usecase,
+ except the following reserved parameters:
+ </p>
+ <ul>
+ <li>
+<code>lenya.usecase</code>
+</li>
+ <li>
+<code>lenya.continutation</code>
+</li>
+ <li>
+<code>submit</code>
+</li>
+ </ul>
+ <p>
+ If the request parameter value is a string, the value can be accessed inside the usecase
+ handler using <code>getParameterAsString(name)</code>. If the request parameter
+ is a part of a multipart request, e.g., in a file upload form, it will be available
+ using <code>getPart(name)</code>.
+ </p>
+ <br/>
+ </li>
+ <li>
+<code>checkPreconditions()</code>
+ <p>
+ This method is called to check the pre-conditions of the usecase. The pre-conditions
+ are checked before the usecase is started, i.e., before the first screen is presented
+ to the user. To denote that a condition does not comply, add an appropriate error message
+ using <code>addErrorMessage(String)</code>. If an error message was added, the usecase
+ is not started. Alternatively, you can provide information to the user using
+ <code>addInfoMessage(String)</code>. This doesn't prevent the usecase from being executed.
+ </p>
+ <br/>
+ </li>
+ <li>
+<code>lockInvolvedObjects()</code>
+ <p>
+ This method is called to lock all objects which could be changed during the usecase.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ <p>
+ The following methods are called in a loop while the user interacts with the usecase,
+ until a request parameter with the name <code>submit</code> was sent.
+ </p>
+
+ <ol>
+ <li>
+<code>getView()</code>
+ <p>
+ Requests the next view to be displayed. The view may be <code>null</code> if no
+ screen should be presented to the user.
+ </p>
+ <br/>
+ </li>
+ <li>
+<code>advance()</code>
+ <p>
+ This method is called to advance the usecase after the a user interaction.
+ In contrast to <code>execute()</code>, this method is not called when the
+ <code><input type="submit" name="submit"></code> was pressed, but for every
+ other submitting of the form. A typical usecase is the <em>multiple forms editor</em> where
+ <code>advance()</code> is used to update the document when the user switched to
+ another element.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ <p>
+ When the form is submitted using the <code><input type="submit" name="submit"></code>
+ button, the usecase is finished:
+ </p>
+
+ <ol>
+ <li>
+<code>checkExecutionConditions()</code>
+ <p>
+ This method is called before the usecase is actually executed. A typical example
+ is the validation of form data.
+ </p>
+ <br/>
+ </li>
+ <li>
+<code>execute()</code>
+ <p>
+ This method actually executes the final step of the usecase.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ <p>
+ When the form is submitted using the <code><input type="submit" name="cancel"></code>
+ button, the usecase is cancelled:
+ </p>
+
+ <ol>
+ <li>
+<code>cancel()</code>
+ <p>
+ This method cancels the usecase. The transaction is rolled back.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ </section>
+
+ <section>
+ <title>Implementing a Custom Usecase</title>
+
+ <section>
+ <title>Prerequisites</title>
+ <ol>
+ <li>Choose a name to identify the usecase, e.g. editHeadline. It is possible to group usecases
+ using "." as delimiter, for instance <code>article.editHeadline</code>.
+ </li>
+ </ol>
+ </section>
+
+ <section>
+ <title>Add a Menu Item</title>
+ <note>
+ This step is necessary if you want to call the usecase from the Lenya menubar.
+ </note>
+ <ol>
+ <li>Add the corresponding menu item:
+ <source xml:space="preserve"><![CDATA[<item uc:usecase="article.editHeadline">Edit Headline</item>]]></source>
+ </li>
+ </ol>
+ </section>
+
+ <section>
+ <title>Implement the Usecase Handler Class</title>
+ <ol>
+ <li>Choose a name for your business logic class, e.g. <code>org.myproject.lenya.usecases.EditHeadline</code>.</li>
+ <li>The class must implement the interface <code>org.apache.lenya.cms.usecase.Usecase</code>.</li>
+ <li>
+ To simplify development, you can extend one of the following classes:
+ <ul>
+ <li>
+<code>org.apache.lenya.cms.usecase.AbstractUsecase</code>
+</li>
+ <li>
+<code>org.apache.lenya.cms.usecase.DocumentUsecase</code> (only for usecases invoked on document pages)</li>
+ <li>
+<code>org.apache.lenya.cms.usecase.SiteUsecase</code>
+</li>
+ </ul>
+ They have built-in support for the unit-of-work pattern (which will evolve into
+ an ACID transaction someday) as well as functionality specific to the area they are
+ supposed to be used with, e.g. the site area.
+ </li>
+ <li>
+ Add the usecase handler class declaration to an XPatch file, e.g.
+ <code>$PUB_HOME/config/cocoon-xconf/usecases.xconf</code>:
+<source xml:space="preserve"><![CDATA[<xconf xpath="/cocoon/usecases"
+ unless="/cocoon/usecases/component-instance[@name = 'article.editHeadline']">
+ <component-instance name="article.editHeadline"
+ logger="lenya.usecases.editHeadline"
+ class="org.myproject.lenya.usecases.EditHeadline"/>
+</xconf>]]></source>
+ </li>
+ </ol>
+ </section>
+
+ <section>
+ <title>Implement the View</title>
+ <p>
+ The view of a usecase is optional. If you omit the view declaration, no screen is presented
+ to the user. The view is declared in the usecase configuration:
+ </p>
+<source xml:space="preserve"><![CDATA[ <component-instance ...>
+ <view template="usecases/article/editHeadline.jx" menu="false">
+ <parameter name="title" value="Edit Headline"/>
+ <parameter name="..." value="..."/>
+ </view>
+ </component-instance>]]></source>
+
+ <p>
+ The <code><view></code> element takes an optional <code>menu</code> attribute
+ which denotes if the menubar should be visible when the usecase screen is presented.
+ If omitted, it defaults to <code>false</code>.
+ </p>
+ <p>
+ The <code><view></code> element can contain an arbitrary number of <code><parameter></code>
+ elements, each containing a <code>name</code> and <code>value</code> attribute. These
+ parameters can be accessed in the JX template using
+ <code>${usecase.getView().getParameter('...')}</code>.
+ </p>
+ <p>
+ One option is to implement view for a usecase as a JX template. The location of the
+ JX template is defined using the <code><view></code> element's <code>template</code>
+ attribute (relatively to the <code>context://lenya</code> directory).
+ The output of the template has to be a Lenya page:
+ </p>
+<source xml:space="preserve"><![CDATA[<page:page
+ xmlns:jx="http://apache.org/cocoon/templates/jx/1.0"
+ xmlns:page="http://apache.org/cocoon/lenya/cms-page/1.0"
+ xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+ >
+
+ <page:title>
+ <i18n:text><jx:out value="${usecase.getView().getParameter('title')}"/></i18n:text>
+ </page:title>
+ <page:body>
+
+ <form>
+ <input type="hidden" name="lenya.continuation" value="${continuation.id}"/>
+ <input type="hidden" name="lenya.usecase" value="${usecase.getName()}"/>
+
+ ...
+
+ </form>
+
+ </page:body>
+</page:page>]]></source>
+ <p>
+ Take care of adding the hidden <code>lenya.usecase</code> and <code>lenya.continuation</code> fields as shown above.
+ </p>
+
+ <p>
+ If you don't want to display a form, but output arbitrary XML, text, an SVG-generated image
+ or something like that, you can use a <code>uri</code> attribute instead of the <code>template</code>
+ attribute. In this case, the <code>menu</code> attribute can be omitted.
+ </p>
+
+ <source xml:space="preserve"><![CDATA[ <component-instance ...>
+ <view uri="cocoon://modules/reports/generateReport.pdf" />
+ </component-instance>]]></source>
+
+
+ </section>
+ <section>
+ <title>Displaying Usecases in Tabs</title>
+ <p>
+ It is possible to use a tab-based layout to assemble a set of usecases.
+ The admin and site areas are displayed using this style.
+ To add a tab-based usecase to a tab set, two steps are required:
+ </p>
+
+ <ol>
+ <li>
+ Add the tab to the GUI manager configuration:
+<source xml:space="preserve"><![CDATA[<xconf xpath="/cocoon/gui-manager/tab-group[@name = 'admin']"
+ unless="/cocoon/gui-manager/tab-group[@name = 'admin']/tab[@name = 'search']">
+
+ <tab name="search" label="Search" usecase="admin.search"/>
+
+</xconf>]]></source>
+ </li>
+ <li>
+ Add the tab configuration to the usecase view declaration:
+<source xml:space="preserve"><![CDATA[<component-instance name="admin.search" logger="lenya.admin" class="org.apache.lenya.cms.usecase.DummyUsecase">
+ <view template="usecases/admin/search.jx" menu="true">
+ <tab group="admin" name="search"/>
+ </view>
+ <exit usecase="admin.search"/>
+</component-instance>]]></source>
+ </li>
+ </ol>
+ </section>
+ <section id="dyn_exit">
+ <title>Dynamically Setting the Exit URL</title>
+ <p> Like you see above you can specify the "exit" URL of the
+ usecase via the component configuration, however this is
+ sometimes not enough because you may need to set the exit URL
+ of a usecase dynamically.</p>
+ <p>Consider the use case is that you have a form and you need two
+ possibilities to exit the usecase. </p>
+ <ol>
+ <li>Pressing on "submit" will save and exit to the same page in
+ the authoring area. </li>
+ <li>The other exit point could be a dynamic link based on a <code><![CDATA[<a href=""/>]]></code>
+ where the user get redirected after submitting the form (e.g. to edit the linked document
+ with the <a href="lenya-document:23061260-8731-11dc-ae46-9e7b5d14892d">BXE</a> editor).</li>
+ </ol>
+ <p>First you need to add another request parameter (e.g.,
+ <code>TRANSFER_FIELD</code>) denoting that the user clicked the link. This
+ could be e.g. a hidden field which contains the URL to transfer
+ the request. Further you need to override
+ <code>Usecase.getTargetURL()</code> to return the BXE usecase URL if the
+ <code>TRANSFER_FIELD</code> parameter is set, and <code>super.getTargetURL()</code>
+ otherwise.</p>
+ <source xml:space="preserve"><![CDATA[public String getTargetURL(boolean success) {
+ String tmpTransfer = getParameterAsString("TRANSFER_FIELD", null);
+ if (!tmpTransfer.equals("") & tmpTransfer != null)
+ return tmpTransfer;
+ else
+ return super.getTargetURL(success);
+}]]></source>
+ </section>
+ </section>
+
+ <section>
+ <title>Overriding Core Usecases in Publications</title>
+
+ <section>
+ <title>Overriding Usecase Handler Classes</title>
+
+ <p>
+ The usecase resolver, which is responsible for obtaining the handler class for a usecase,
+ looks first if the current publication overrides the core usecase handler.
+ This can be done by declaring a usecase called <code><![CDATA[<pub-id>/<usecase-name>]]></code>,
+ for instance <code>mypub/admin.addUser</code>. To implement a core usecase using a custom
+ handler class, you need to
+ </p>
+ <ol>
+ <li>Implement the handler class and put it in <code>$PUB_HOME/java/src</code>.
+ In most cases, you will extend the core usecase handler class to inherit the basic functionality.</li>
+ <li>
+ Declare it in an <em>xpatch</em> file, for instance
+ <code>$PUB_HOME/config/cocoon-xconf/usecases.xconf</code>:
+<source xml:space="preserve"><![CDATA[<xconf xpath="/cocoon/usecases" unless="/cocoon/usecases/component-instance[@name = 'mypub/admin.addUser']">
+ <component-instance name="mypub/admin.addUser"
+ logger="lenya.usecases.editHeadline"
+ class="org.myproject.lenya.usecases.AddUser"/>
+</xconf>]]></source>
+ </li>
+ </ol>
+ <p>
+ Now, when the usecase is invoked from inside the publication mypub, the custom
+ handler class will be used.
+ </p>
+ </section>
+
+ <section>
+ <title>Overriding JX Templates</title>
+ <p>
+ Overriding the JX template of a usecase follows the
+ <a href="lenya-document:a3a1c460-8730-11dc-ae46-9e7b5d14892d">publication templating</a> principle.
+ You just have to put a JX template with the same name in <code>$PUB_HOME/lenya/usecases</code>,
+ for instance <code>$PUB_HOME/lenya/usecases/admin/addUser.jx</code>.
+ </p>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Added: lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221900296.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221900296.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221900296.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.meta.1195221900296.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://apache.org/lenya/metadata/1.0">
+<element-set namespace="http://purl.org/dc/elements/1.1/">
+<element key="title">
+<value>Overview</value>
+</element>
+</element-set>
+<element-set namespace="http://apache.org/lenya/metadata/document/1.0">
+<element key="extension">
+<value>xml</value>
+</element>
+<element key="mimeType">
+<value>application/xml</value>
+</element>
+<element key="resourceType">
+<value>forrestDocument20</value>
+</element>
+<element key="contentType">
+<value>xml</value>
+</element>
+</element-set>
+</metadata>
Modified: lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.rcml
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.rcml?rev=595691&r1=595690&r2=595691&view=diff
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.rcml (original)
+++ lenya/sandbox/pubs/docu/content/authoring/9ffa4030-8730-11dc-ae46-9e7b5d14892d/en.rcml Fri Nov 16 07:11:58 2007
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<XPSRevisionControl xmlns="">
+<CheckIn backup="true" identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221900296" version="3"/>
+<CheckOut identity="lenya" session="fde084c0-944b-11dc-8f2e-e6c0ff9903ab" time="1195221890404"/>
<CheckIn backup="true" identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910794859" version="2"/>
<CheckOut identity="lenya" session="1f12dc80-8860-11dc-ba66-cfbbb816bd0d" time="1193910766881"/>
<CheckIn backup="true" identity="lenya" session="60798970-8730-11dc-ae46-9e7b5d14892d" time="1193781619177" version="1"/>
Added: lenya/sandbox/pubs/docu/content/authoring/a1297160-8730-11dc-ae46-9e7b5d14892d/en.1195221904892.bak
URL: http://svn.apache.org/viewvc/lenya/sandbox/pubs/docu/content/authoring/a1297160-8730-11dc-ae46-9e7b5d14892d/en.1195221904892.bak?rev=595691&view=auto
==============================================================================
--- lenya/sandbox/pubs/docu/content/authoring/a1297160-8730-11dc-ae46-9e7b5d14892d/en.1195221904892.bak (added)
+++ lenya/sandbox/pubs/docu/content/authoring/a1297160-8730-11dc-ae46-9e7b5d14892d/en.1195221904892.bak Fri Nov 16 07:11:58 2007
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+ <header>
+ <title>The AbstractUsecase Class</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Introduction</title>
+ <p>
+ When you implement a custom usecase, you're very likely to extend
+ <code>org.apache.lenya.cms.usecase.AbstractUsecase</code>. This class provides a set of
+ functionality to simplify the implementation of usecases.
+ </p>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <p>
+ The usecase is configured in <code>cocoon.xconf</code>.
+ A typical configuration looks like this:
+ </p>
+
+<source xml:space="preserve"><![CDATA[
+<component-instance name="edit.forms" logger="lenya.publication"
+ class="org.apache.lenya.cms.editors.forms.FormsEditor">
+ <transaction policy="pessimistic"/>
+ <view template="edit/forms/forms" menu="false"/>
+</component-instance>
+]]></source>
+
+ <p>
+ The following configuration options are available:
+ </p>
+
+ <ul>
+ <li>Element <code><transaction></code> (optional)
+ <ul>
+ <li>Attribute <code>policy = (optimistic | pessimistic)</code>
+</li>
+ </ul>
+ <br/>
+ <p>
+ This element is used to determine the transaction policy of the usecase
+ (<em>optimistic</em> or <em>pessimistic offline lock</em>). It can be omitted,
+ the default is optimistic behaviour.
+ You should only use pessimistic behaviour for complex usecases when the user
+ can't afford to lose all changes.
+ </p>
+ <br/>
+ </li>
+
+ <li>Element <code><parameter></code> (arbitrary number)
+ <ul>
+ <li>Attribute <code>name</code>
+</li>
+ <li>Attribute <code>value</code>
+</li>
+ </ul>
+ <br/>
+ <p>
+ An arbitrary number of initial parameters can be passed to the usecase.
+ </p>
+ <br/>
+ </li>
+
+ <li>Element <code><view></code> (optional)
+ <ul>
+ <li>Attribute <code>template</code> (required)</li>
+ <li>Attribute <code>menu = (true | false)</code> (optional)</li>
+ <li>Element <code><parameter name="..." value="..."/></code> (arbitrary number)</li>
+ </ul>
+ <br/>
+ <p>
+ This element declares the view of the usecase. The <code>template</code> attribute
+ points to the JX template to use, relatively to the <code>lenya/usecases</code>
+ directory. The suffix <code>.jx</code> is added automatically. The attribute <code>menu</code>
+ determines if the menu should be visible. It can be omitted and defaults to <code>false</code>.
+ </p>
+ <br/>
+ </li>
+
+ <li>Element <code><exit></code> (optional)
+ <ul>
+ <li>Attribute <code>usecase</code> (required)</li>
+ <li>Element <code><parameter name="..." value="..."/></code> (arbitrary number)</li>
+ </ul>
+ <br/>
+ <p>
+ This element declares the exit usecase. By default, a usecase exits on the
+ URL it was started from, without any request parameters. Using this method,
+ is is possible to specify a usecase that should be called after this usecase
+ has exited. Additional parameter elements can be supplied.
+ </p>
+ <br/>
+ </li>
+ </ul>
+
+ </section>
+
+ <section>
+ <title>Extending AbstractUsecase</title>
+
+ <p>
+ The following methods of the <code>AbstractUsecase</code> class are meant to be overridden
+ or invoked by subclasses:
+ </p>
+
+ <ul>
+ <li>
+ <code>protected void initParameters()</code>
+ <p>
+ This method is called to initialize the parameters of the usecase. For instance, if
+ your usecase shall display meta data on the view screen, <code>initParameters()</code>
+ reads the meta data from the document and puts them into the parameter map using
+ <code>setParameter(String, Object)</code> to make them available to the JX template.
+ </p>
+ <p>
+ Note that you can't access the request parameters in this method yet, because it
+ is executed before the request parameters are passed to the usecase.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckPreconditions()</code>
+ <p>
+ The method <code>checkPreconditions()</code> is a template method which calls this
+ method. For details on <code>checkPreconditions()</code>, see section
+ <a href="index.html">Overview</a>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckExecutionConditions()</code>
+ <p>
+ The method <code>checkExecutionConditions()</code> is a template method which calls this
+ method. For details on <code>checkExecutionConditions()</code>, see section
+ <a href="index.html">Overview</a>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckPostconditions()</code>
+ <p>
+ The method <code>checkPostonditions()</code> is a template method which calls this
+ method. For details on <code>checkPostonditions()</code>, see section
+ <a href="index.html">Overview</a>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doExecute()</code>
+ <p>
+ The method <code>execute()</code> is a template method which calls this
+ method. For details on <code>execute()</code>, see section
+ <a href="index.html">Overview</a>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>public void advance()</code>
+ <p>
+ For details on <code>advance()</code>, see section
+ <a href="index.html">Overview</a>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected Transactionable[] getObjectsToLock()</code>
+ <p>
+ This method is supposed to return all objects which should be locked before
+ the usecase is started. If the transaction policy is <em>pessimistic offline lock</em>,
+ these objects are checked out immediately.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void setExitParameter(String name, String value)</code>
+ <p>
+ Call this method to set a parameter that should be added to the exit request.
+ For instance, imagine a usecase which edits a user's groups. The exit usecase
+ might be <em>userProfile</em>, with the additional parameter <em>userId</em>.
+ </p>
+ </li>
+
+ </ul>
+
+ </section>
+
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@lenya.apache.org
For additional commands, e-mail: commits-help@lenya.apache.org