ASF_20_SRC_AUTO/src/documentation/xdocs/faq/faq-sitemap.xml - cocoon - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">

 <faqs title="Sitemap FAQs">


 <faq>
   <question>
     What are the steps to pre-compile the sitemap and XSP's?
   </question>
   <answer>
     <ul>
       <li>Set the auto-reload to false in your sitemap.xmap as follows:</li>
     </ul>

     <source><![CDATA[
 <parameter name="auto-reload" value="false"/>
 ]]></source>

     <ul>
       <li>Use "-Dbuild.precompile=true" in your build command line when you are
         building your WAR file.
       </li>
     </ul>
   </answer>
 </faq>

 <faq>
  <question>I don't want to hand edit the sitemap.  Are there any
    tools?</question>
  <answer>
    <p>Try <fork href="http://pollo.sourceforge.net/">this</fork>
      by Bruno Dumon.</p>
  </answer>
 </faq>

 <faq>
  <question>How do I create some content which isn't directly visible to
    everyone?</question>
  <answer>
    <p>Put the content in an internal pipeline...</p>

    <source><![CDATA[
 <map:pipelines>
  <map:pipeline internal-only="true">
    <map:match pattern="int">
      <map:generate src="docs/description.xml"/>
      <map:serialize type="xml"/>
    </map:match>
  </map:pipeline>
  <map:pipeline>
    <map:match pattern="desc.html">
      <map:generate src="cocoon:/int"/>
      <map:transform src="stylesheets/description2html.xsl"/>
      <map:serialize type="html"/>
    </map:match>
  </map:pipeline>
 </map:pipelines>
 ]]></source>

  </answer>
 </faq>

 <faq>
  <question>How can I concatenate two xml files?</question>
  <answer>
    <source><![CDATA[
 <map:pipelines>
  <map:pipeline internal-only="true">
    <map:match pattern="one">
      <map:generate src="docs/one.xml"/>
      <map:serialize type="xml"/>
    </map:match>
    <map:match pattern="two">
      <map:generate src="docs/two.xml"/>
      <map:serialize type="xml"/>
    </map:match>
  </map:pipeline>
  <map:pipeline>
    <map:match pattern="desc.html">
      <map:aggregate element="newRootElement">
        <map:part src="cocoon:/one" element="firstXMLfile"/>
        <map:part src="cocoon:/two" element="secondXMLfile"/>
      </map:aggregate>
      <map:transform src="stylesheets/merge2html.xsl"/>
      <map:serialize type="html"/>
    </map:match>
  </map:pipeline>
 </map:pipelines>
 ]]></source>

    <p>Where the element attribute names are replaced with something more
      meaningful!  Note that the map:part element attributes can be left off,
      which results in the two parts being placed one immediately after the
      other.</p>
  </answer>
 </faq>

 <faq>
  <question>I want to use the XXX matcher/serializer/selecter/etc but there's no
    examples :(</question>
  <answer>
    <p>If you've checked the sample webapps which come with Cocoon, and you've
      looked in the documentation, then check both the user and
      dev archives.  If it hasn't been resolved before <strong>first</strong>
      email the user group and, after a <strong>reasonable</strong> (ie 1 or 2
      days) length of time (remember not everyone lives in your timezone) email
      the dev group.</p>
    <p>Please don't cross-post to both the user and dev groups - very few people
      like getting bombarded!</p>
    <p>Oh, and once you do get it working - how about documenting it and
      contributing it back to the group?</p>
  </answer>
 </faq>


 <faq>
   <question>
     I changed the sitemap, but my changes don't show in the browser.
     Do I need to restart the servlet container?
   </question>
   <answer>
     <p>Cocoon lets you decide whether it needs to poll for sitemap changes
     (with its associated performance penalty) or not. It also lets you decide whether the re-compilation resulting from polling shoud happen in the
     background or in the foreground.</p>

     <p>If you look at the cocoon.xconf file, you'll notice this element:</p>
     <source><![CDATA[
 <sitemap file="sitemap.xmap"
          reload-method="asynchron"
          check-reload="yes"/>]]></source>

     <p>Which means:</p>
       <ul>
         <li>The <code>check-reload</code> attribute determines if the sitemap
         is reloaded on change. Set to "no", the sitemap is generated once
         at startup. Set to "yes", the sitemap is regenerated if it changes.</li>
         <li>The <code>reload-method</code> specifies the method for the
           regeneration:
           <ol>
             <li><code>asynchron</code>: If the sitemap changes, the sitemap is
             regenerated at the next request in the background and the incoming
             request is served with the old sitemap. All subsequent requests
             are served with the old sitemap until the regeneration in the
             background has finished.</li>
             <li><code>synchron</code>: If the sitemap changes, the sitemap
             is regenerated at the next request. When the regeneration is
             finished, the request (and all subsequent ones) is served with
             the new sitemap.</li>
           </ol>
         </li>
       </ul>
     <p>
       For a development environment, set the reload-method to "synchron" and the
       check-reload to "yes." For a production environment,
       set the reload-method to "asynchron." For more safety, set the check-reload
       to "no."
     </p>

     <p>In a nutshell: By default, reload is "asynchron" which means:</p>
       <ol>
         <li>Change sitemap</li>
         <li>Hit reload</li>
         <li>Wait while CPU goes up to 100% and back down to 0%</li>
         <li>Hit reload</li>
         <li>Voila - new sitemap is used! :)</li>
       </ol>
     <p>Hence: you don't need to restart the servlet container.</p>

     <p>For sub-sitemaps, this issue is defined in the mounting element:</p>
     <source><![CDATA[
 <map:mount uri-prefix="foo" src="file:///c:/foo/"
            check-reload="yes"
            reload-method="synchron"/>]]></source>
     <p>With these settings Cocoon will react to any changes in the sub-sitemap,
       without even hitting the reload button twice. :)</p>
     <p>
       Moreover, it is a good idea to use sub-sitemaps because they reduce
       overall compilation time. For example, changes to a single sub-sitemap won't
       require recompilation for the the main sitemap or other sub-sitemaps. This
       practice leads to greater degree of modularity.
     </p>
   </answer>
 </faq>

 <faq>
   <question>When I add an action to a pipeline Cocoon returns an
   error.</question>
   <answer>
   <p>Before the action was added to the pipeline it worked fine. After
   the change Cocoon seems not to find the file specified in the
   variable that is returned by the matcher.</p>

 <source><![CDATA[
 <map:match pattern="*">
   <map:act type="validate-session">
     <map:generate type="serverpages" src="{../1}.xsp"/>
   </map:act>
   <map:serialize/>
 </map:match>
 ]]></source>

   <p>Please note in the above example the
   "<strong><code>../1</code></strong>".</p>
   <p>Map objects returned from matchers, actions etc. are organised
   <em>hierarchically</em>. Therefore they are not replaced by new ones
   but older ones are still accessible through a path expression. Here
   "<code>../1</code>" references key ("variable") "1" in the next to
   last Map. </p>
   </answer>
 </faq>

 <faq>
   <question>
     What is the syntax for absolute filesystem pathnames.
   </question>
   <answer>
    <p>
     In your sitemaps you may need to refer to some resource that is outside
     the webapp context (e.g. UNIX /foo/bar/this.xsl
     e.g. Windows C:\foo\bar\this.xsl). You need to use the file: convention.
    </p>
    <ul>
     <li>UNIX ... <code>file:///foo/bar/this.xsl</code></li>
     <li>Windows ... <code>file:///C:/foo/bar/this.xsl</code></li>
    </ul>
    <p>
     See further explanation of
     <link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
    </p>
   </answer>
 </faq>

 <faq>
   <question>
 What's the difference between having two pipelines with one matcher
 each, and one pipeline with two matchers?
   </question>
   <answer>
    <p>
 If there is no other difference in pipeline declarations, then none, really. Note that pipelines can differ by:
   </p>
 <ul>
 	<li>
 visibility: internal-only="true" (not accessible for external requests) or not.
    </li>
    <li>
 error handling: using different &lt;handle-errors&gt;s.
    </li>
    <li>
 cachability (since 2.1): some requests can use cached responses
 from caching pipeline. Others, which should not be cached, can be
 handled by the non-caching pipeline implementation.
   </li>
   <li>
 logical grouping: logically-related components can be grouped into
 separate pipelines to improve readability and ease administrative concerns.
   </li>
   <li>
 ids: used to identify pipeline and other elements. See the "sitebuilder" sitemap editor
 in scratchpad samples for an example.
   </li>
 </ul>
  </answer>
  </faq>

  <faq>
   <question>
 Where can I find more information about the sitemap?
   </question>
   <answer>
    <p>
 Learn more about advanced Sitemap features by downloading the free chapter, <link href="http://www.newriders.com/books/product.asp?product_id={C3C05052-BE3B-4E06-A60A-13FB40AF58F6}" >A User's Look at the Cocoon architecture,</link> from Langham and Ziegeler's <em>Cocoon: Building XML Applications</em> available at the New Riders web site.
   </p>
   <p>
 Check out a draft XML Schema <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/src/documentation/xdocs/drafts/sitemap-2.1-draft.xsd?rev=HEAD&amp;content-type=text/plain">grammar for the Cocoon sitemap</link>, and some <link href="http://outerthought.net/sitemap/">external documentation</link> generated from this Schema. A poster diagram of the sitemap structure is also available.
    </p>
   </answer>
   </faq>
 </faqs>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">

	<faqs title="Sitemap FAQs">


	<faq>
	<question>
	What are the steps to pre-compile the sitemap and XSP's?
	</question>
	<answer>
	<ul>
	<li>Set the auto-reload to false in your sitemap.xmap as follows:</li>
	</ul>

	<source><![CDATA[
	<parameter name="auto-reload" value="false"/>
	]]></source>

	<ul>
	<li>Use "-Dbuild.precompile=true" in your build command line when you are
	building your WAR file.
	</li>
	</ul>
	</answer>
	</faq>

	<faq>
	<question>I don't want to hand edit the sitemap. Are there any
	tools?</question>
	<answer>
	<p>Try <fork href="http://pollo.sourceforge.net/">this</fork>
	by Bruno Dumon.</p>
	</answer>
	</faq>

	<faq>
	<question>How do I create some content which isn't directly visible to
	everyone?</question>
	<answer>
	<p>Put the content in an internal pipeline...</p>

	<source><![CDATA[
	<map:pipelines>
	<map:pipeline internal-only="true">
	<map:match pattern="int">
	<map:generate src="docs/description.xml"/>
	<map:serialize type="xml"/>
	</map:match>
	</map:pipeline>
	<map:pipeline>
	<map:match pattern="desc.html">
	<map:generate src="cocoon:/int"/>
	<map:transform src="stylesheets/description2html.xsl"/>
	<map:serialize type="html"/>
	</map:match>
	</map:pipeline>
	</map:pipelines>
	]]></source>

	</answer>
	</faq>

	<faq>
	<question>How can I concatenate two xml files?</question>
	<answer>
	<source><![CDATA[
	<map:pipelines>
	<map:pipeline internal-only="true">
	<map:match pattern="one">
	<map:generate src="docs/one.xml"/>
	<map:serialize type="xml"/>
	</map:match>
	<map:match pattern="two">
	<map:generate src="docs/two.xml"/>
	<map:serialize type="xml"/>
	</map:match>
	</map:pipeline>
	<map:pipeline>
	<map:match pattern="desc.html">
	<map:aggregate element="newRootElement">
	<map:part src="cocoon:/one" element="firstXMLfile"/>
	<map:part src="cocoon:/two" element="secondXMLfile"/>
	</map:aggregate>
	<map:transform src="stylesheets/merge2html.xsl"/>
	<map:serialize type="html"/>
	</map:match>
	</map:pipeline>
	</map:pipelines>
	]]></source>

	<p>Where the element attribute names are replaced with something more
	meaningful! Note that the map:part element attributes can be left off,
	which results in the two parts being placed one immediately after the
	other.</p>
	</answer>
	</faq>

	<faq>
	<question>I want to use the XXX matcher/serializer/selecter/etc but there's no
	examples :(</question>
	<answer>
	<p>If you've checked the sample webapps which come with Cocoon, and you've
	looked in the documentation, then check both the user and
	dev archives. If it hasn't been resolved before <strong>first</strong>
	email the user group and, after a <strong>reasonable</strong> (ie 1 or 2
	days) length of time (remember not everyone lives in your timezone) email
	the dev group.</p>
	<p>Please don't cross-post to both the user and dev groups - very few people
	like getting bombarded!</p>
	<p>Oh, and once you do get it working - how about documenting it and
	contributing it back to the group?</p>
	</answer>
	</faq>



	<faq>
	<question>
	I changed the sitemap, but my changes don't show in the browser.
	Do I need to restart the servlet container?
	</question>
	<answer>
	<p>Cocoon lets you decide whether it needs to poll for sitemap changes
	(with its associated performance penalty) or not. It also lets you decide whether the re-compilation resulting from polling shoud happen in the
	background or in the foreground.</p>

	<p>If you look at the cocoon.xconf file, you'll notice this element:</p>
	<source><![CDATA[
	<sitemap file="sitemap.xmap"
	reload-method="asynchron"
	check-reload="yes"/>]]></source>

	<p>Which means:</p>
	<ul>
	<li>The <code>check-reload</code> attribute determines if the sitemap
	is reloaded on change. Set to "no", the sitemap is generated once
	at startup. Set to "yes", the sitemap is regenerated if it changes.</li>
	<li>The <code>reload-method</code> specifies the method for the
	regeneration:
	<ol>
	<li><code>asynchron</code>: If the sitemap changes, the sitemap is
	regenerated at the next request in the background and the incoming
	request is served with the old sitemap. All subsequent requests
	are served with the old sitemap until the regeneration in the
	background has finished.</li>
	<li><code>synchron</code>: If the sitemap changes, the sitemap
	is regenerated at the next request. When the regeneration is
	finished, the request (and all subsequent ones) is served with
	the new sitemap.</li>
	</ol>
	</li>
	</ul>
	<p>
	For a development environment, set the reload-method to "synchron" and the
	check-reload to "yes." For a production environment,
	set the reload-method to "asynchron." For more safety, set the check-reload
	to "no."
	</p>

	<p>In a nutshell: By default, reload is "asynchron" which means:</p>
	<ol>
	<li>Change sitemap</li>
	<li>Hit reload</li>
	<li>Wait while CPU goes up to 100% and back down to 0%</li>
	<li>Hit reload</li>
	<li>Voila - new sitemap is used! :)</li>
	</ol>
	<p>Hence: you don't need to restart the servlet container.</p>

	<p>For sub-sitemaps, this issue is defined in the mounting element:</p>
	<source><![CDATA[
	<map:mount uri-prefix="foo" src="file:///c:/foo/"
	check-reload="yes"
	reload-method="synchron"/>]]></source>
	<p>With these settings Cocoon will react to any changes in the sub-sitemap,
	without even hitting the reload button twice. :)</p>
	<p>
	Moreover, it is a good idea to use sub-sitemaps because they reduce
	overall compilation time. For example, changes to a single sub-sitemap won't
	require recompilation for the the main sitemap or other sub-sitemaps. This
	practice leads to greater degree of modularity.
	</p>
	</answer>
	</faq>

	<faq>
	<question>When I add an action to a pipeline Cocoon returns an
	error.</question>
	<answer>
	<p>Before the action was added to the pipeline it worked fine. After
	the change Cocoon seems not to find the file specified in the
	variable that is returned by the matcher.</p>

	<source><![CDATA[
	<map:match pattern="*">
	<map:act type="validate-session">
	<map:generate type="serverpages" src="{../1}.xsp"/>
	</map:act>
	<map:serialize/>
	</map:match>
	]]></source>

	<p>Please note in the above example the
	"<strong><code>../1</code></strong>".</p>
	<p>Map objects returned from matchers, actions etc. are organised
	<em>hierarchically</em>. Therefore they are not replaced by new ones
	but older ones are still accessible through a path expression. Here
	"<code>../1</code>" references key ("variable") "1" in the next to
	last Map. </p>
	</answer>
	</faq>

	<faq>
	<question>
	What is the syntax for absolute filesystem pathnames.
	</question>
	<answer>
	<p>
	In your sitemaps you may need to refer to some resource that is outside
	the webapp context (e.g. UNIX /foo/bar/this.xsl
	e.g. Windows C:\foo\bar\this.xsl). You need to use the file: convention.
	</p>
	<ul>
	<li>UNIX ... <code>file:///foo/bar/this.xsl</code></li>
	<li>Windows ... <code>file:///C:/foo/bar/this.xsl</code></li>
	</ul>
	<p>
	See further explanation of
	<link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
	</p>
	</answer>
	</faq>

	<faq>
	<question>
	What's the difference between having two pipelines with one matcher
	each, and one pipeline with two matchers?
	</question>
	<answer>
	<p>
	If there is no other difference in pipeline declarations, then none, really. Note that pipelines can differ by:
	</p>
	<ul>
	<li>
	visibility: internal-only="true" (not accessible for external requests) or not.
	</li>
	<li>
	error handling: using different <handle-errors>s.
	</li>
	<li>
	cachability (since 2.1): some requests can use cached responses
	from caching pipeline. Others, which should not be cached, can be
	handled by the non-caching pipeline implementation.
	</li>
	<li>
	logical grouping: logically-related components can be grouped into
	separate pipelines to improve readability and ease administrative concerns.
	</li>
	<li>
	ids: used to identify pipeline and other elements. See the "sitebuilder" sitemap editor
	in scratchpad samples for an example.
	</li>
	</ul>
	</answer>
	</faq>

	<faq>
	<question>
	Where can I find more information about the sitemap?
	</question>
	<answer>
	<p>
	Learn more about advanced Sitemap features by downloading the free chapter, <link href="http://www.newriders.com/books/product.asp?product_id={C3C05052-BE3B-4E06-A60A-13FB40AF58F6}" >A User's Look at the Cocoon architecture,</link> from Langham and Ziegeler's <em>Cocoon: Building XML Applications</em> available at the New Riders web site.
	</p>
	<p>
	Check out a draft XML Schema <link href="http://cvs.apache.org/viewcvs.cgi/checkout/cocoon-2.1/src/documentation/xdocs/drafts/sitemap-2.1-draft.xsd?rev=HEAD&content-type=text/plain">grammar for the Cocoon sitemap</link>, and some <link href="http://outerthought.net/sitemap/">external documentation</link> generated from this Schema. A poster diagram of the sitemap structure is also available.
	</p>
	</answer>
	</faq>
	</faqs>