upayavira 2003/07/01 22:03:52
Modified: src/documentation/xdocs/userdocs/concepts book.xml
modules.xml
Added: src/documentation/xdocs/userdocs/concepts redirection.xml
Log:
Added docs on redirection
Fixed typo in modules doc
Please review this doc - it's my first, and I'd
like to know I'm doing it right.
Upayavira
Revision Changes Path
1.4 +1 -0 cocoon-2.1/src/documentation/xdocs/userdocs/concepts/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/concepts/book.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- book.xml 29 Apr 2003 10:45:20 -0000 1.3
+++ book.xml 2 Jul 2003 05:03:52 -0000 1.4
@@ -26,6 +26,7 @@
<menu-item label="XML Validation" href="validation.html"/>
<menu-item label="Databases" href="databases.html"/>
<menu-item label="Modules" href="modules.html"/>
+ <menu-item label="Redirects" href="redirects.html"/>
<menu-item label="Profiler" href="profiler.html"/>
<menu-item label="Error Handling" href="errorhandling.html"/>
</menu>
1.3 +1 -1 cocoon-2.1/src/documentation/xdocs/userdocs/concepts/modules.xml
Index: modules.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/concepts/modules.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- modules.xml 19 Mar 2003 08:19:12 -0000 1.2
+++ modules.xml 2 Jul 2003 05:03:52 -0000 1.3
@@ -73,7 +73,7 @@
Cocoon. Exception to this rule are the auto increment modules: only the
HSQL module is already setup.
</p>
- <s2 title="Step 1: Making a new module know to Apache Cocoon">
+ <s2 title="Step 1: Making a new module known to Apache Cocoon">
<p>
Like other core components of Apache Cocoon, modules are declared in
<code>cocoon.xconf</code>. There are already too many to list here.
1.1
cocoon-2.1/src/documentation/xdocs/userdocs/concepts/redirection.xml
Index: redirection.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
<header>
<title>Redirection</title>
<authors>
<person name="Upayavira" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
A Redirector allows the sitemap to pass a request for one URI on to another,
whether that other URI is handled by Cocoon or not.
</p>
<p>
To redirect from <code>page1.html</code> to <code>page2.html</code>, you can
use
the following:
</p>
<source>
<![CDATA[
<map:match pattern="page1.html">
<map:redirect-to uri="page2.html"/>
</map:match>
]]>
</source>
</s1>
<s1 title="HTTP redirects and how they work">
<p>If the URI specified does not use the Cocoon: protocol, then an HTTP
redirect
will occur. The new URI is sent back to the client, which will then request
the page from this new location.
</p>
<p>Therefore, directory handling in redirect URIs works differently from other
sitemap components.
</p>
<p>If the new URI is relative, then it will be relative to the directory of
the
page that called it, not relative to the URI of the sitemap containing it.
Thus, the following is incorrect:
</p>
<source>
<![CDATA[
<map:match pattern="folder/page1.html">
<map:redirect-to uri="folder/page2.html"/>
</map:match>
]]>
</source>
<p>
This will in fact redirect the user to folder/folder/page2.html, which is
probably not intended. The correct version is:
</p>
<source>
<![CDATA[
<map:match pattern="folder/page1.html">
<map:redirect-to uri="page2.html"/>
</map:match>
]]>
</source>
</s1>
<s1 title="Internal Redirects Using the Cocoon Protocol">
<p>
A redirection URI can make use of the <code>cocoon:</code> protocol to return
content from another Cocoon pipeline. In this case, the redirection happens
internally. The content from the redirected URI is returned to the client as
if it came from the original URI.
</p>
<p>
Directory handling is the same here as for other sitemap components. So that:
</p>
<source>
<![CDATA[
<map:match pattern="folder/page1.html">
<map:redirect-to uri="cocoon:/folder/page2.html"/>
</map:match>
]]>
</source>
<p>
will return the content of <code>page2.html</code> to the client in response
to the request for <code>page1.html</code>.
</p>
<p>
Note: when the <code>cocoon:</code> protocol is used, an HTTP redirect is not
used.
</p>
</s1>
<s1 title="Session Management with Redirects">
By setting the <code>session</code> attribute to <code>yes</code>, the current
session will be maintained during the redirect.
</s1>
<s1 title="Temporary and Permanent Redirects">
<p>
By default, an HTTP redirect sends a code of
<code>SC_MOVED_TEMPORARILY</code>,
(<code>302</code>). This instructs the user agent to use the new URI, but not
to
cache the resulting page, as it may well soon revert back to the old URI.
</p>
<p>
This can be a problem for pages that have been moved permanently, as the new
page will never be cached, placing additional load on both the browser and on
the server.
</p>
<p>
This can be avoided using a permanent redirect, using a code of
<code>SC_MOVED_PERMANENTLY</code> (<code>301</code>). A permanent redirect
can be specified as:
</p>
<source>
<![CDATA[
<map:match pattern="page1.html">
<map:redirect-to uri="page2.html" permanent="yes"/>
</map:match>
]]>
</source>
<p>
This results in the user agent caching the redirected page, and thus saves
resources both on the server and for the client's browser.
</p>
</s1>
<s1 title="Redirects in Pipelines">
<p>
A redirect must stand alone in a pipeline - it cannot occur after a
generator.
If a redirect needs to be generated conditionally by a pipeline, then a
<code><meta></code> tag redirect should be added into the
<code><head></code> of the HTML page. The syntax for this is:
</p>
<source>
<![CDATA[
<html>
<head>
<meta http-equiv="refresh" content="0;URL=page2.html"/>
...
</head>
...
</html>
]]>
</source>
</s1>
<s1 title="Global Redirects">
<p>
When an aggregator accesses a source that includes a redirection, it will
aggregate the document specified by the redirection URI.
</p>
<p>
Alternatively, if a redirection that has the <code>global</code> attribute
is set
(to <code>yes</code> or <code>true</code>) occurs within an aggregation, the
aggregation is cancelled and the redirect is sent back to the client.
</p>
</s1>
<s1 title="Redirecting to Resources">
<p>Specifiying a <code>resource</code> attribute allows the redirection to a
sitemap
resource. This usage has been deprecated. <code>map:call</code> should be used
instead.
</p>
</s1>
</body>
</document>
