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/05/25 17:26:26 UTC
svn commit: r541690 - in /lenya/docu/src/documentation/content/xdocs: ./
docs/1_4/tutorials/newpublication/ docs/1_4/tutorials/resourcetype/
images/live/resourcetype/
Author: andreas
Date: Fri May 25 08:26:25 2007
New Revision: 541690
URL: http://svn.apache.org/viewvc?view=rev&rev=541690
Log:
Added tutorial about creating a resource type
Added:
lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/
lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part1.xml
lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part2.xml
lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part3.xml
lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/
lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/create-screen.png (with props)
lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/new-document.png (with props)
Modified:
lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/newpublication/index.xml
lenya/docu/src/documentation/content/xdocs/site.xml
Modified: lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/newpublication/index.xml
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/newpublication/index.xml?view=diff&rev=541690&r1=541689&r2=541690
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/newpublication/index.xml (original)
+++ lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/newpublication/index.xml Fri May 25 08:26:25 2007
@@ -21,7 +21,7 @@
<document>
<header>
- <title>Create a New Publication</title>
+ <title>Creating a New Publication</title>
</header>
<body>
Added: lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part1.xml
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part1.xml?view=auto&rev=541690
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part1.xml (added)
+++ lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part1.xml Fri May 25 08:26:25 2007
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 1999-2006 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: metadata.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>Creating a Resource Type, Part 1: Prerequisites and Declaration</title>
+ </header>
+ <body>
+ <p>
+ This section explains how to create a new resource type. For more information
+ on resource types, refer to the <a href="site:resource-types">resource types reference</a>.
+ For the sake of simplicity, we'll test the resource type with the default publication.
+ </p>
+ <p>
+ Our resource type will support storing details (name, address, etc.) of people.
+ We'll call it <em>person</em>. Since we're too lazy (and too smart) to invent our
+ own XML schema, we'll just use the one provided by the
+ <a href="http://www.foaf-project.org/"><acronym title="Friend of a Friend">FoaF</acronym></a>
+ project.
+ </p>
+
+ <section>
+ <title>Prerequisites</title>
+ <p>
+ We'll use the following directory layout:
+ </p>
+ <source xml:space="preserve">$HOME/
+ apache/
+ lenya-1.4/ The Lenya installation directory, we'll call it $LENYA_HOME.
+ src/
+ lenya/ The home directory of your Lenya-related sources.
+ modules/ Our modules.
+ person/ Our "person" resource type module ($MODULE_HOME).</source>
+
+ </section>
+
+ <section>
+ <title>Adding a Module</title>
+ <p>
+ We'll add a module which will contain the resource type. This makes it
+ self-contained, and it will be very easy to re-use our resource type
+ in different publications. Create the <em>person</em> directory (see section
+ <em>Prerequisites</em>) with the following directory layout:
+ </p>
+
+ <source xml:space="preserve">person/
+ config/ Configuration of the module.
+ menu.xsp The resource type menu items.
+ module.xml Module descriptor.
+ cocoon-xconf/ Patch files for cocoon.xconf.
+ resourcetype-person.xconf The declaration of our resource type.
+ resources/
+ icons/
+ person.gif The icon for the sitetree.
+ samples/ Samples to create person documents.
+ foaf.xml The default sample document.
+ xslt/
+ foaf2xhtml.xml Transform FoaF documents to XHTML.
+ menus.xmap The sitemap generating the menu.</source>
+
+ <p>
+ Each module needs a module descriptor file <code>$MODULE_HOME/config/module.xml</code>.
+ In our case it looks like this (replace <code>org.yourproject</code> with your
+ own package name):
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<module xmlns="http://apache.org/lenya/module/1.0">
+ <id>org.yourproject.lenya.modules.person</id>
+ <package>org.yourproject.lenya.modules</package>
+ <version>0.1-dev</version>
+ <name>person</name>
+ <lenya-version>@lenya.version@</lenya-version>
+ <description>Resource type to store person details</description>
+</module>]]></source>
+ <p>
+ Now we have to let Lenya know that we've added a new module. Edit the
+ file <code>$LENYA_HOME/local.build.properties</code> and add the path
+ to your <code>modules</code> directory (the parent of <code>$MODULE_HOME</code>)
+ at the end of the <code>modules.root.dirs</code> declaration:
+ </p>
+ <source xml:space="preserve">modules.root.dirs=...:/home/john/src/lenya/modules</source>
+ <p>
+ Finally, we'll have to declare the module in the publications which use it
+ (in our case, the default publication). Edit <code>$PUB_HOME/config/publication.xml</code>
+ and add the entry
+ </p>
+ <source><![CDATA[<module name="person"/>]]></source>
+ <p>
+ to the <code><![CDATA[<modules/>]]></code> section.
+ </p>
+ </section>
+
+ <section>
+ <title>Declaring the Resource Type</title>
+ <p>
+ To let Lenya know that a new resource type exists, we'll add the
+ resource type declaration file <code>resourcetype-person.xconf</code>.
+ This is a patch for the <code>cocoon.xconf</code> file and therefore
+ located in <code>$MODULE_HOME/config/cocoon-xconf</code>.
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<xconf xpath="/cocoon/resource-types"
+ unless="/cocoon/resource-types/component-instance[@name = 'person']">
+
+ <component-instance name="person" logger="lenya.resourcetypes"
+ class="org.apache.lenya.cms.publication.ResourceTypeImpl">
+
+ <schema language="http://relaxng.org/ns/structure/0.9"
+ src="fallback://lenya/modules/person/resources/schemas/person.rng"/>
+
+ <!-- Default time in seconds until the resource-type has expired -->
+ <expires seconds="3600" />
+
+ <sample-name>fallback://lenya/modules/person/samples/foaf.xml</sample-name>
+
+ <format name="xhtml" uri="cocoon://modules/person/xhtml.xml"/>
+ <format name="xhtml-include" uri="cocoon://modules/person/xhtml-include.xml"/>
+ <format name="icon" uri="cocoon://modules/person/icon"/>
+
+ </component-instance>
+
+</xconf>]]></source>
+ <p>
+ According to this declaration, the Lenya web application creates a new
+ <code>ResourceTypeImpl</code> service on startup which makes the resource
+ type details available to other objects.
+ </p>
+ <p>
+ In the <a href="site:newResourceTypePart2">next section</a> we'll setup the creation of person documents.
+ </p>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part2.xml
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part2.xml?view=auto&rev=541690
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part2.xml (added)
+++ lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part2.xml Fri May 25 08:26:25 2007
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 1999-2006 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: metadata.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>Creating a Resource Type, Part 2: Creating Documents</title>
+ </header>
+
+ <body>
+
+ <section>
+ <title>Adding the Menu</title>
+ <p>
+ Now we'll add the menu for our module. The first item we need will trigger
+ the usecase to create new person documents. We have to add a sitemap which
+ serves as an entry point for the menu (<code>$MODULE_HOME/menus.xmap)</code>:
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="**">
+ <map:generate type="serverpages"
+ src="fallback://lenya/modules/person/config/menu.xsp"/>
+ <map:serialize type="xml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>]]></source>
+ <p>
+ According to this sitemap, the menu XSP is located at
+ <code>$MODULE_HOME/config/menu.xsp</code>:
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<xsp:page
+ language="java"
+ xmlns:xsp="http://apache.org/xsp"
+ xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+ xmlns:uc="http://apache.org/cocoon/lenya/usecase/1.0"
+ xmlns="http://apache.org/cocoon/lenya/menubar/1.0">
+ <menu>
+ <menus>
+ <menu i18n:attr="name" name="File">
+ <block areas="site authoring">
+ <item uc:usecase="sitemanagement.create" href="?doctype=person">
+ <i18n:translate>
+ <i18n:text>New ... Document</i18n:text>
+ <i18n:param>Person</i18n:param>
+ </i18n:translate>
+ </item>
+ </block>
+ </menu>
+ </menus>
+ </menu>
+</xsp:page>]]></source>
+ <p>
+ The menu contains an item which triggers the <code>sitemanagement.create</code>
+ usecase with the <code>doctype=person</code> parameter.
+ </p>
+ </section>
+ <section>
+ <title>Providing the Sample</title>
+ <p>
+ To create a document, the <code>sitemanagement.create</code> usecase needs a sample
+ XML. We've already specified the sample location in our resource type declaration
+ (see above). Now we have to add the corresponding FoaF person file
+ (<code>$MODULE_HOME/samples/foaf.xml</code>):
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<rdf:RDF
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:foaf="http://xmlns.com/foaf/0.1/">
+ <foaf:Person rdf:ID="me">
+ <foaf:name>Homer Simpson</foaf:name>
+ <foaf:title>Mr</foaf:title>
+ <foaf:givenname>Homer</foaf:givenname>
+ <foaf:family_name>Simpson</foaf:family_name>
+ <foaf:mbox rdf:resource="mailto:chunkylover53@aol.com"/>
+ <foaf:phone rdf:resource="tel:555-555-555"/>
+ <foaf:workplaceHomepage rdf:resource="http://powerplantspringfield.com"/>
+ </foaf:Person>
+</rdf:RDF>]]></source>
+
+ <p>
+ In the <a href="site:newResourceTypePart3">next section</a> we'll render our
+ newly created document as an XHTML web page.
+ </p>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part3.xml
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part3.xml?view=auto&rev=541690
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part3.xml (added)
+++ lenya/docu/src/documentation/content/xdocs/docs/1_4/tutorials/resourcetype/part3.xml Fri May 25 08:26:25 2007
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 1999-2006 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: metadata.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>Creating a Resource Type, Part 3: Presentation</title>
+ </header>
+ <body>
+
+ <section>
+ <title>A Basic Presentation Pipeline</title>
+ <p>
+ Now the Lenya web application can create new person documents, but
+ it won't be able to render them as HTML pages (or anything else) yet.
+ In our resource type declaration we specified the format <em>xhtml</em>.
+ According to this specification, we'll setup a basic presentation pipeline
+ which converts our FoaF XML document to XHTML.
+ </p>
+ <p>
+ First we'll add the sitemap (<code>$MODULE_HOME/sitemap.xmap</code>).
+ Note that some lines have been wrapped (marked with backslashes):
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+
+ <!-- {format}.xml -->
+ <map:match pattern="*.xml">
+ <map:generate src="cocoon:/{1}.xml/{page-envelope:publication-id}/ \
+ {page-envelope:area}/{page-envelope:document-uuid}/ \
+ {page-envelope:document-language}"/>
+ <map:serialize type="xml"/>
+ </map:match>
+
+ <!-- {format}.xml/{pubId}/{area}/{uuid}/{language} -->
+ <map:match pattern="*.xml/*/*/*/*">
+ <map:generate src="lenya-document:{4},lang={5}{link:rev}"/>
+ <map:transform src="fallback://lenya/modules/person/xslt/foaf2xhtml.xsl"/>
+ <map:serialize type="xml"/>
+ </map:match>
+
+ <!-- The icon for person nodes in the sitetree. -->
+ <map:match pattern="icon/*/*/*/*">
+ <map:read src="fallback://lenya/modules/person/resources/icons/person.gif"/>
+ </map:match>
+
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+ ]]></source>
+ <p>
+ The sitemap uses an XSLT stylesheet <code>$MODULE_HOME/xslt/foaf2xhtml.xsl</code>
+ to render the XHTML view of the FoaF file:
+ </p>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:foaf="http://xmlns.com/foaf/0.1/"
+ xmlns="http://www.w3.org/1999/xhtml">
+
+ <xsl:template match="rdf:RDF">
+ <html>
+ <head>
+ <style type="text/css">
+ table.person { font-size: small; }
+ table.person th {
+ font-weight: normal;
+ color: #999999;
+ text-align: left;
+ padding-right: 1em;
+ }
+ </style>
+ </head>
+ <body>
+ <div id="body">
+ <xsl:apply-templates select="foaf:Person"/>
+ </div>
+ </body>
+ </html>
+ </xsl:template>
+
+ <xsl:template match="foaf:Person">
+ <h2>Person Details</h2>
+ <table class="person">
+ <tr>
+ <th>Title:</th>
+ <td><xsl:value-of select="foaf:title"/></td>
+ </tr>
+ <tr>
+ <th>Given name:</th>
+ <td><xsl:value-of select="foaf:givenname"/></td>
+ </tr>
+ <tr>
+ <th>Family name:</th>
+ <td><xsl:value-of select="foaf:family_name"/></td>
+ </tr>
+ <tr>
+ <th>E-Mail:</th>
+ <td>
+ <xsl:variable name="mbox" select="foaf:mbox/@rdf:resource"/>
+ <a href="{$mbox}">
+ <xsl:value-of select="substring-after($mbox, 'mailto:')"/>
+ </a>
+ </td>
+ </tr>
+ <tr>
+ <th>Phone:</th>
+ <td>
+ <xsl:variable name="phone" select="foaf:phone/@rdf:resource"/>
+ <xsl:value-of select="substring-after($phone, 'tel:')"/>
+ </td>
+ </tr>
+ <tr>
+ <th>Homepage:</th>
+ <td>
+ <xsl:variable name="homepage" select="foaf:workplaceHomepage/@rdf:resource"/>
+ <a href="{$homepage}"><xsl:value-of select="$homepage"/></a>
+ </td>
+ </tr>
+ </table>
+ </xsl:template>
+
+</xsl:stylesheet>]]></source>
+ <p>
+ Note that we add some style information to the HTML header to display our table properly.
+ </p>
+ </section>
+
+ <section>
+ <title>Creating our First Person Document</title>
+ <p>
+ Now it's time to check out if everything works as expected. First, we build the
+ Lenya web application to deploy our new resource type. If Lenya is running, shut it down.
+ Go to <code>$LENYA_HOME</code> and execute
+ </p>
+ <source xml:space="preserve">./build.sh</source>
+ <p>
+ When the build has finished, start the Jetty server:
+ </p>
+ <source xml:space="preserve">./lenya.sh</source>
+ <p>
+ Now go to <a href="http://localhost:8888/default/authoring/index.html">http://localhost:8888/default/authoring/index.html</a>
+ and log in as user "lenya". The <em>File</em> menu should now contain an
+ item <em>New Person Document</em>. But before creating person documents,
+ we'll add a new top level XHTML document <em>People</em>:
+ </p>
+ <ul>
+ <li>File -> New XHTML Document</li>
+ <li>Node Name: people</li>
+ <li>Navigation Title: People</li>
+ </ul>
+ <p>
+ You end up on the <em>People</em> page. Now you can create a new person document
+ as a child of this document by selecting the <em>New Person Document</em> menu item:
+ </p>
+ <figure src="site:resourceTypeCreateScreen.img" alt="Create a person document"/>
+ <p>
+ After hitting OK, you're redirected to the newly created person document:
+ </p>
+ <figure src="site:resourceTypeNewDocument.img" alt="Person document"/>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/create-screen.png
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/create-screen.png?view=auto&rev=541690
==============================================================================
Binary file - no diff available.
Propchange: lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/create-screen.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/new-document.png
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/new-document.png?view=auto&rev=541690
==============================================================================
Binary file - no diff available.
Propchange: lenya/docu/src/documentation/content/xdocs/images/live/resourcetype/new-document.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: lenya/docu/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/lenya/docu/src/documentation/content/xdocs/site.xml?view=diff&rev=541690&r1=541689&r2=541690
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/site.xml (original)
+++ lenya/docu/src/documentation/content/xdocs/site.xml Fri May 25 08:26:25 2007
@@ -135,6 +135,11 @@
<tutorials href="tutorials/" label="Tutorials">
<newPublication14 href="newpublication/index.html" label="Create a Publication"/>
+ <newResourceType href="resourcetype/" label="Create a Resource Type">
+ <newResourceTypePart1 href="part1.html" label="Part 1"/>
+ <newResourceTypePart2 href="part2.html" label="Part 2"/>
+ <newResourceTypePart3 href="part3.html" label="Part 3"/>
+ </newResourceType>
<setupide href="setupide/index.html" label="Setting up Eclipse"/>
<tests href="tests.html" label="Writing Tests"/>
<bestpractises href="bestpractises.html" label="Best Practises"/>
@@ -556,6 +561,10 @@
<usecase-framework-architecture.img href="usecase-framework-architecture.png"/>
<repositoryWorkspaces.img href="repositoryWorkspaces.png"/>
<modules-svg-roundedcorners-screenshot.img href="svgmodule/roundedcorners.png"/>
+ <resourceTypeImages href="resourcetype/">
+ <resourceTypeCreateScreen.img href="create-screen.png"/>
+ <resourceTypeNewDocument.img href="new-document.png"/>
+ </resourceTypeImages>
</live>
</images>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@lenya.apache.org
For additional commands, e-mail: commits-help@lenya.apache.org