You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2007/06/07 18:18:56 UTC
[DAISY] Created: Redirects
A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/1378.html
Document ID: 1378
Branch: main
Language: default
Name: Redirects
Document Type: Cocoon Document
Created: 6/7/07 4:18:48 PM
Creator (owner): Reinhard Pötz
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 4267 bytes
Content:
<html>
<body>
<h1>Introduction</h1>
<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 <tt>page1.html</tt> to <tt>page2.html</tt>, you can use the
following:</p>
<pre>
<map:match pattern="page1.html">
<map:redirect-to uri="page2.html"/>
</map:match>
</pre>
<h1>HTTP redirects and how they work</h1>
<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>
<pre>
<map:match pattern="folder/page1.html">
<map:redirect-to uri="folder/page2.html"/>
</map:match>
</pre>
<p>This will in fact redirect the user to folder/folder/page2.html, which is
probably not intended. The correct version is:</p>
<pre>
<map:match pattern="folder/page1.html">
<map:redirect-to uri="page2.html"/>
</map:match>
</pre>
<h1>Internal Redirects Using the Cocoon Protocol</h1>
<p>A redirection URI can make use of the <tt>cocoon:</tt> 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>
<pre>
<map:match pattern="folder/page1.html">
<map:redirect-to uri="cocoon:/folder/page2.html"/>
</map:match>
</pre>
<p>will return the content of <tt>page2.html</tt> to the client in response to
the request for <tt>page1.html</tt>.</p>
<p>Note: when the <tt>cocoon:</tt> protocol is used, an HTTP redirect is not
used.</p>
<h1>Session Management with Redirects</h1>
<p>By setting the <tt>session</tt> attribute to <tt>yes</tt>, the current
session will be maintained during the redirect.</p>
<h1>Temporary and Permanent Redirects</h1>
<p>By default, an HTTP redirect sends a code of <tt>SC_MOVED_TEMPORARILY</tt>,
(<tt>302</tt>). 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
<tt>SC_MOVED_PERMANENTLY</tt> (<tt>301</tt>). A permanent redirect can be
specified as:</p>
<pre>
<map:match pattern="page1.html">
<map:redirect-to uri="page2.html" permanent="yes"/>
</map:match>
</pre>
<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>
<h1>Redirects in Pipelines</h1>
<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 <tt><meta></tt> tag redirect should be added into the
<tt><head></tt> of the HTML page. The syntax for this is:</p>
<pre>
<html>
<head>
<meta http-equiv="refresh" content="0;URL=page2.html"/>
...
</head>
...
</html>
</pre>
<h1>Global Redirects</h1>
<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 <tt>global</tt> attribute is set
(to <tt>yes</tt> or <tt>true</tt>) occurs within an aggregation, the aggregation
is cancelled and the redirect is sent back to the client.</p>
<h1>Redirecting to Resources</h1>
<p>Specifiying a <tt>resource</tt> attribute allows the redirection to a sitemap
resource. This usage has been deprecated. <tt>map:call</tt> should be used
instead.</p>
</body>
</html>
Collections
===========
The document belongs to the following collections: cdocs-core