You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lenya.apache.org by gr...@apache.org on 2005/05/14 22:33:01 UTC
svn commit: r170166 - in /lenya/docu/src/documentation/content/xdocs:
1_2_x/how-to/custom_resourcetype.xml site.xml
Author: gregor
Date: Sat May 14 13:33:00 2005
New Revision: 170166
URL: http://svn.apache.org/viewcvs?rev=170166&view=rev
Log:
Added custom resource type how-to
Added:
lenya/docu/src/documentation/content/xdocs/1_2_x/how-to/custom_resourcetype.xml
Modified:
lenya/docu/src/documentation/content/xdocs/site.xml
Added: lenya/docu/src/documentation/content/xdocs/1_2_x/how-to/custom_resourcetype.xml
URL: http://svn.apache.org/viewcvs/lenya/docu/src/documentation/content/xdocs/1_2_x/how-to/custom_resourcetype.xml?rev=170166&view=auto
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/1_2_x/how-to/custom_resourcetype.xml (added)
+++ lenya/docu/src/documentation/content/xdocs/1_2_x/how-to/custom_resourcetype.xml Sat May 14 13:33:00 2005
@@ -0,0 +1,340 @@
+<?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>Custom Resource Type How-To</title>
+ </header>
+ <body>
+<p>This tutorial explains how to add a custom resource type to the Default publication in order to mix free page editing (as in XHTML) and constrained editing
+(as you get with a custom resource type). </p>
+
+<section><title id="head-de4048d1d2761efba50bdc305d7f2afdf7a546e2">Decide if you really need a new resource type</title>
+
+<p>Introducing a new resource type where you don't need one is a time consuming and often unnecessary excercise. Therefore you should ask yourself first if you really need a new
+resource type for what you are trying to achieve or if you should be looking for other means of solving your problem. </p>
+<p>As a rule of thumb, you should use a new resource type if you are going to render documents which are fundamentally different from XHTML.
+ A resource type is all about Lenya turning an arbitraty XML document into XHTML which then will be put into the content page of your publication's page. </p>
+<p>It might make sense for example to introduce resource types for well known XML schemas such as: </p>
+<ul>
+<li> RSS</li>
+<li><a href="http://docbook.sourceforge.net/">DocBook</a></li>
+<li><p> NewsML, SportsML, <a href="http://nitf.org/">NITF</a> or <a href="http://www.iptc.org">IPTC</a> </p>
+</li>
+<li><a href="http://xmlns.com/foaf/0.1/">FOAF</a></li>
+</ul>
+<p>It may also make sense to introduce resource types for custom XML schemas such as </p>
+<ul>
+<li><p> the XML format you use for a catalog item in your company </p>
+</li>
+</ul>
+<p>In contrast, it is not a good idea to introduce a custom resource type if you want to render documents that are basically XHTML but just contain some non-XHTML tags such as </p>
+<ul>
+<li><p> <xi:include ...> </p>
+</li>
+<li><p> <ft:...> (Cocoon Form tags) </p>
+</li>
+</ul>
+<p>In this case you should rather add some extra transformers to the pipeline that renders these tags into XHTML. </p>
+
+<p>Also resource types are not XHTML templates. </p>
+
+</section><section><title id="head-2ee188822e061359b50250dfaaf79edb933981bc">Choose a name</title>
+
+<p>Choose a name for the resource type ID: <em>myresourcetype</em> </p>
+
+</section><section><title id="head-d05f4f01dd36c53247e296e75bc2f09a5d801429">Define the resource type ID</title>
+
+<p>Define the resource type ID in <tt>mypub/config/doctypes/doctypes.xconf</tt> Note that resource types were historically called doctypes, thus the names of the config files. </p>
+
+<pre>
+<doctypes>
+ <!-- Here is the document ID -->
+ <doc type="myresourcetype">
+ <!-- if the document is allowed to have children, define what resource types they can be -->
+ <children>
+ <!-- this resource type is allowed to have xhtml and/or myresourcetype documents as children -->
+
+ <doc type="xhtml"/>
+ <doc type="myresourcetype"/>
+ </children>
+ <!-- This is the class that creates a new instance of this resource type -->
+ <creator src="org.apache.lenya.cms.authoring.DefaultBranchCreator">
+ <!-- this is the sample file that is used when creating a new instance of this resource type. Can be found in config/doctypes/samples -->
+
+ <sample-name>myresourcetype.xml</sample-name>
+ </creator>
+ <!-- These tasks here refer to ant tasks that should be called for this resource type. For instance, you can have a special publish task. -->
+ <!-- tasks are defined in mypub/config/tasks/tasks.xconf -->
+ <tasks>
+
+ <task id="publish"/>
+ </tasks>
+ <!-- Specify the workflow definition for this resource type. You can define a seperate workflow for each resource type, for instance with one or two levels of approval. -->
+ <!-- workflow process is defined in mypub/config/workflow/workflow.xml (see below) -->
+ <workflow src="workflow.xml"/>
+ </doc>
+
+</doctypes></pre>
+
+</section><section><title id="head-cea12489d4b764632fd61dd792a9e5f90626e11e">Create the schema</title>
+
+<p>Create relax NG schema: <tt>mypub/config/doctypes/schemas/myresourcetype.rng</tt> </p>
+<p>Note: This is optional, but important if you want to use the form editors. If you get your XML files that you try to render as a custom resource type from
+somewhere else you can omit this step. You can also omit it if you want to create a sample document manually first to see all the rest working and come back to this point later. </p>
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<!--+
+ | myresourcetype resource type
+ +-->
+
+<grammar ns="http://www.w3.org/1999/xhtml"
+ xmlns="http://relaxng.org/ns/structure/1.0"
+ xmlns:lenya="http://apache.org/cocoon/lenya/page-envelope/1.0"
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml"
+ >
+
+<!-- include the general lenya schema -->
+<!-- you should include the lenya schema if you want to use meta data or assets -->
+<include href="lenya.rng"/>
+
+<!-- include original XHTML transitional schema -->
+<include href="xhtml/xhtml-basic.rng">
+
+ <define name="html">
+
+ <element name="html">
+ <ref name="html.attlist"/>
+ <ref name="lenya.meta"/> <!-- this is the Lenya meta data wrapper -->
+ <ref name="head"/>
+ <ref name="body"/>
+
+ </element>
+ </define>
+
+ <define name="html.attlist">
+ <ref name="XHTML.version.attrib"/>
+ <ref name="I18n.attrib"/>
+ <ref name="dummy.attlist"/> <!-- this is deprecated -->
+
+ </define>
+
+</include>
+
+
+<!-- additional block elements -->
+<define name="Block.class" combine="choice">
+ <choice>
+ <ref name="lenya.asset"/>
+
+ </choice>
+</define>
+
+
+</grammar></pre>
+<p>Note that you can generate Relax NG schemas from sample files by using <a href="http://www.thaiopensource.com/relaxng/trang.html">
+ Trang</a> or <a href="http://wwws.sun.com/software/xml/developers/relaxngconverter/"> Sun RELAX NG Converter</a> </p>
+
+</section><section><title id="head-ff4bce85b820a235e0f917955b004b766b9a6d41">Resource type matcher</title>
+
+<p>Add a sourcetype matcher in <tt>mypub/parameter-doctype.xmap</tt>
+</p>
+<pre>
+<!-- This file is map:mounted from mypub/publication-sitemap.xmap -->
+
+<map:action name="sourcetype" src="org.apache.cocoon.acting.sourcetype.SourceTypeAction">
+ <sourcetype name="myresourcetype">
+
+ <document-element local-name="myroottag"/>
+ <!-- this matches the root tag -->
+ </sourcetype>
+</map:action>
+
+</pre>
+<p>The parameter-doctype.xmap allows Lenya to determine the resource type of any URI. the mapping provided in here allows to mix and match resource types freely.
+ It makes use of the <a href="http://forrest.apache.org/docs/cap.html"> Source Type action</a>. There are several ways to identify a resource type,
+ such as by its root tag, the namespace of its root element or its schema. Please note that the name of the resource type you specify here is used throughout
+ Lenya as a naming convention, for instance for the resourcetype2xhtml.xsl. </p>
+
+<p>The root-tag is just the doctype within your publication (i.e., 'homepage', if you have a homepage.rng doctype definition). For more background, see:
+<a href="http://forrest.apache.org/docs/cap.html"> http://forrest.apache.org/docs/cap.html</a> </p>
+<p>For great examples of complex custom types, please also go to <a href="http://www.wyona.org"> http://www.wyona.org</a> and do a Subversion
+update to download the example publication (University of Zurich and others). </p>
+<p>Many problems with resource types not rendering correctly result from this matcher not recognizing the resource type and therefore using the default.
+So pay special attention to this. Check the overview page in the site area where it will tell you what resource type the document has. </p>
+
+</section><section><title id="head-efab8428b801182274861ad033341c99f13bb014">Sample File</title>
+
+<p>Add a sample file: <tt>mypub/config/doctypes/samples/myresourcetype.xml</tt> </p>
+<p>The sample file will be used as a template. If you create a new document with this resource type a copy of the sample file will be placed as a starting point.
+Therefore it makes sense to set some good defaults here. </p>
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml"
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:lenya="http://apache.org/cocoon/lenya/page-envelope/1.0"
+ xhtml:dummy="FIXME:keepNamespace" dc:dummy="FIXME:keepNamespace"
+ lenya:dummy="FIXME:keepNamespace" dcterms:dummy="FIXME:keepNamespace">
+ <lenya:meta>
+ <dc:title>dctitle</dc:title>
+
+ <dc:creator>dccreator</dc:creator>
+ <dc:subject>dcsubject</dc:subject>
+ <dc:description>An empty page for a new resource type</dc:description>
+ <dc:publisher/>
+
+ <dc:contributor/>
+ <dc:date>2004-4-6</dc:date>
+ <dc:type/>
+ <dc:format/>
+ <dc:identifier/>
+
+ <dc:source/>
+ <dc:language>en</dc:language>
+ <dc:relation/>
+ <dc:coverage/>
+ <dc:rights>dcrights</dc:rights>
+
+ </lenya:meta>
+ <head>
+ <title>Sample new resource type</title>
+ </head>
+ <body>
+
+ <h1>New resource type sample</h1>
+ <p>This sample page is the basis for pages based on this resource type</p>
+ </body>
+</html></pre>
+
+</section><section><title id="head-e41c27c12a329ba8438e3a4b228ac2f4e0e3ccd5">Presentation</title>
+
+<ul>
+<li><p> Create presentation XSLT and CSS. If the XSLT and CSS are specific to the publication, you may want to store them in <tt>mypub/xslt/myresourcetype2xhtml.xsl</tt>
+ and <tt>mypub/resources/shared/css/myresourcetype.css</tt>, respectively. Take care of the naming conventions for the XSLT files. </p>
+</li>
+<li class="gap"><p> Copy <tt>mypub/xslt/page2xhtml-xhtml.xsl</tt> to <tt>mypub/xslt/page2xhtml-myresourcetype.xsl</tt>. This will style your new document type
+ like your old documents. If you wish to change how the new documents look, create your own stylesheet at <tt>mypub/xslt/page2xhtml-myresourcetype.xsl</tt> </p>
+
+</li>
+<li class="gap"><p> If you wish to edit your new documents using BXE (Kupu works only with XHTML), you should place a CSS file for styling your documents in
+ <tt>mypub/resources/misc/myresourcetype-bxeng.css</tt> </p>
+</li>
+<li class="gap"><p> Add presentation pipelines in <tt>mypub/sitemap.xmap</tt> if you need special pipelines for your resource type </p>
+</li>
+</ul>
+<p>Make sure you understand that for your new resource type you don't need a replacement for page2xhtml.xsl but for xhtml2xhtml. The reason is this: </p>
+
+<p>Transforming a document to a page in the browser is always a two-step process, </p>
+<ol type="1">
+<li><p>Using {resourcetype}2xhtml.xsl the document (which might be any arbritary XML such as the link list, Docbook, a RSS feed, etc.) is turned into an XHTML presentation. </p>
+</li>
+<li><p>This XHTML is then processed to contain nagivation, menus and the like using page2xhtml. </p>
+</li>
+<li><p>The stylesheet {resourcetype}2xhtml.xsl must return a document of the form
+<tt><div id="body" xmlns="http://www.w3.org/1999/xhtml"> ... </div></tt>. </p>
+
+</li>
+</ol>
+<p>If you have 5 resource types in your publication, for example: </p>
+<ul>
+<li>rss</li>
+<li><p> linklist </p>
+</li>
+<li><p> gallery </p>
+</li>
+
+<li><p> docbook </p>
+</li>
+<li><p> xhtml </p>
+</li>
+</ul>
+<p>the concept would be </p>
+
+<pre>
+document -> rss2xhtml.xsl --+
+document -> linklist2xhtml.xsl --+
+document -> gallery2xhtml.xsl --+---> page2xhtml.xsl -> Browser
+document -> docbook2xhtml.xsl --+
+document -> xhtml2xhtml.xsl --+
+
+</pre>
+
+</section><section><title id="head-cb2652bbd893f7f0e164215f740a06953ffb30a1">Menus</title>
+
+<p>Configure the menus (either 1. or 2.) </p>
+
+<h4 id="head-a546c21eb7f721406e7b0fb338f2241933bb5397">Using an existing menu</h4>
+
+<p>Use an existing menu and add necessary menu items </p>
+<ul>
+<li><p> Edit <tt>mypub/config/menus/generic.xsp</tt> and add an entry for the new resource type </p>
+
+</li>
+<li><p> </p>
+<pre>
+...
+ <menus>
+ <menu i18n:attr="name" name="File" label="File">
+ <block>
+ <xsp:logic>
+ {
+ if (Publication.ARCHIVE_AREA.equals(area) || Publication.TRASH_AREA.equals(area)) {
+ <item><i18n:text>New Document</i18n:text></item>
+
+ }
+ else {
+ <item uc:usecase="create" uc:step="showscreen" href="?doctype=xhtml"><i18n:text>New Document</i18n:text></item>
+ <item uc:usecase="create" uc:step="showscreen" href="?doctype=myresourcetype">New "Doc type" Document</item>
+ }
+ }
+ </xsp:logic>
+
+ </block>
+...</pre>
+</li>
+</ul>
+
+<h4 id="head-46fd0096d6ae1a5ed8d88f18cc135cf069164b2f">using a custom menu</h4>
+
+<p>or Create a custom menu for this resource type </p>
+<ul>
+<li><p> edit <tt>mypub/menus.xmap</tt> </p>
+
+</li>
+<li><p> create a menu file <tt>mypub/config/menus/myresourcetype.xsp</tt> </p>
+</li>
+</ul>
+
+</section><section><title id="head-05d787d62a93318a4edadf14e42a300b4e41f3f3">Workflow</title>
+
+<p>(optional) define a specific workflow </p>
+<ul>
+<li><p> add the workflow schema to <tt>mypub/config/workflow/</tt> </p>
+
+</li>
+<li><p> assign the workflow schema to the resource type in <tt>mypub/config/doctypes/doctypes.xconf</tt> </p>
+</li>
+</ul></section> </body>
+</document>
\ No newline at end of file
Modified: lenya/docu/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/lenya/docu/src/documentation/content/xdocs/site.xml?rev=170166&r1=170165&r2=170166&view=diff
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/site.xml (original)
+++ lenya/docu/src/documentation/content/xdocs/site.xml Sat May 14 13:33:00 2005
@@ -104,6 +104,7 @@
<newpub href="new_publication.html" label="New Publication"/>
<deploypub href="deploy_publication.html" label="Deploy Publication"/>
<lookandfeel href="look_and_feel.html" label="Look and Feel"/>
+ <customresourcetype href="custom_resourcetype.html" label="Custom Resource Type"/>
</howtos>
<components href="components/" label="Components">
<accesscontrol href="accesscontrol/" label="Access Control">
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@lenya.apache.org
For additional commands, e-mail: commits-help@lenya.apache.org