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>
