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>
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.