[WIKI-UPDATE] LenyaCreatePageWalkthrough Sat Jun 14 04:00:03 2003

[st...@outerthought.org]

Page: http://wiki.cocoondev.org/Wiki.jsp?page=LenyaCreatePageWalkthrough , version: 1 on Sat Jun 14 01:40:14 2003 by BillHumphries

New page created:
+ !!More sitemap spelunking: creating a new document
+ 
+ Continuing to learn by tailing logs, Day Two.
+ 
+ __NB__: The numbers after the colon in filenames refer to the line number.
+ 
+ Let's create a new page in the tutorial section of the default site.
+ 
+ {{http://localhost:8080/lenya/default/authoring/tutorial.html?lenya.usecase=create&lenya.step=showscreen&doctype=xhtml}}
+ 
+ {{"Matcher 'usecase' matched prepared pattern 'create' at webapps/lenya/sitemap.xmap:703:52"}}
+ 
+ So far, we've run across the {{wildcard}} matcher, we've not seen {{usecase}} before.
+ 
+ The documentation for the usecase matcher is in [http://localhost:8080/lenya/docs-new/docs/concepts/usecases.html].
+ 
+ Looking at {{webapps/lenya/sitemap.xmap:703:52}}:
+ 
+ {{{<map:match type="usecase" pattern="create">
+   <map:mount uri-prefix="" 
+     src="lenya/usecase.xmap" check-reload="true" 
+     reload-method="synchron"/>
+ </map:match>}}}
+ 
+ This directs Lenya to mount the usecase.xmap. 
+ 
+ But where's the usecase matcher defined? It's in {{webapps/lenya/sitemap.xmap:279}}.
+ 
+ {{{<map:matcher name="usecase" logger="sitemap.matcher.usecase" 
+   src="org.apache.cocoon.matching.WildcardRequestParameterMatcher">
+   <parameter-name>lenya.usecase</parameter-name>
+ </map:matcher>}}}
+ 
+ So all they've done here is define a [matcher|WildcardRequestParameterMatcher] that looks for the parameter {{lenya.usecase}} in the request, and flags a request as a match if the parameter is present.
+ 
+ So continue to {{webapps/lenya/usecase.xmap}} since {{"Matcher 'wildcard' matched prepared pattern '*/*/**' at webapps/lenya/lenya/usecase.xmap:119:33"}}
+ 
+ That's the start of a group of usecase matches, however none of them agree with the {{lenya.usecase}} parameter {{create}}.
+ 
+ ''It's worth pointing out that you can nest {{map:match}} elements inside {{map:match}} elements.''
+ 
+ So we go on to another URI pattern match.
+ 
+ {{"Matcher 'wildcard' matched prepared pattern '*/*/**' at webapps/lenya/lenya/usecase.xmap:210:33"}}
+ 
+ Again, there's no match inside the {{map:match}}, so we continue.
+ 
+ {{"Matcher 'wildcard' matched prepared pattern '*/*/**' at webapps/lenya/lenya/usecase.xmap:255:35"}}
+ 
+ Ah, now we see an immediate match inside this pipeline:
+ 
+ {{"Matcher 'usecase' matched prepared pattern 'create' at webapps/lenya/lenya/usecase.xmap:257:46"}}
+ 
+ {{{<!-- Create -->
+ <map:pipeline>
+   <!-- {publication-id}/{area}/{uri}-->
+   <map:match pattern="*/*/**">
+ 
+     <map:match type="usecase" pattern="create">
+ 
+       <map:match type="step" pattern="showscreen">
+         <map:call resource="usecase-create">
+           <map:parameter name="publication-id" value="{../../1}"/>
+         </map:call>
+       </map:match>
+ 
+       <map:match type="step" pattern="create">
+         <map:act type="default-create">
+           <!-- if the action suceeds it returns the referer and we -->
+           <!-- simply redirect to it. -->
+           <map:redirect-to uri="{request:requestURI}"/>
+         </map:act>
+         <!-- otherwise the action could not validate some of the -->
+         <!-- input and we present the upload form again -->
+         <map:call resource="usecase-create">
+           <map:parameter name="publication-id" value="{../../1}"/>
+         </map:call>
+      </map:match>
+ 
+    </map:match>
+   </map:match>
+ </map:pipeline>}}}
+ 
+ How did Lenya know to look for a match with {{create}}, because the WildCardParameterRequest matcher assigned the value of {{lenya.usecase}} into a parameter used by the mounted sitemap.
+ 
+ ''Thus, we learn that one can pass parameters to matchers that are mounted within a sitemap: a useful thing to know.''
+ 
+ Within {{<map:match type="usecase" pattern="create">}}, Lenya looks for a match with the request parameter {{lenya.step}}. The {{step}} matcher is another instance of the [WildCardRequestParameterMatcher].
+ 
+ The match is with {{showscreen}}:
+ 
+ {{{<map:match type="step" pattern="showscreen">
+   <map:call resource="usecase-create">
+     <map:parameter name="publication-id" value="{../../1}"/>
+   </map:call>
+ </map:match>}}}
+ 
+ A [Resource] is just a resuable pipeline. The {{usecase-create}} resource is defined at the top of {{usecase.xmap}}.
+ 
+ Note also that we define a parameter to pass along, {{publication-id}}. It's set to {{default}}.
+ 
+ A detour into sitemap parameters and nesting is worthwhile.
+ 
+ When we entered the sitemap, the first match was with the {{usecase}} matcher which set the {{usecase}} parameter to {{create}}.
+ 
+ Then we matched the wildcard pattern {{*/*/**}} which set parameters for the pieces of the URI.
+ 
+ * 0 -> {{default/authoring/tutorial.html}}
+ * 1 -> {{default}}
+ * 2 -> {{authoring}}
+ * 3 -> {{tutorial.html}}
+ 
+ Then we matched the {{step}} matcher with {{showscreen}}.
+ 
+ At that point, we had three levels of parameters. You'll find these defined in the log as:
+ 
+ {{{PARAM: '0' VALUE: 'showscreen'
+ LEVEL 2
+ PARAM: '../0' VALUE: 'create'
+ LEVEL 1
+ PARAM: '../../3' VALUE: 'tutorial.html'
+ PARAM: '../../2' VALUE: 'authoring'
+ PARAM: '../../0' VALUE: 'default/authoring/tutorial.html'
+ PARAM: '../../1' VALUE: 'default'}}}
+ 
+ Each new match pushes the stack of parameter groups down a level. So to recall parameters matched earlier, we use the {{../}} notation.
+ 
+ Okay, back to the {{usecase-create}} resource:
+ 
+ {{{<map:resource name="usecase-create">
+   <!-- use publication-specific schema if available -->
+   <map:act type="resource-exists" 
+     src="pubs/{publication-id}/content/authoring/create.xsp">
+     <map:generate type="serverpages" 
+       src="pubs/{../publication-id}/content/authoring/create.xsp"/>
+     <map:transform src="pubs/{../publication-id}/xslt/authoring/create.xsl"/>
+     <map:serialize />
+   </map:act>
+ 
+   <!-- otherwise use default schema -->
+   <map:generate type="serverpages" src="content/authoring/create.xsp"/>
+     <map:transform src="xslt/authoring/create.xsl"/>
+   <map:serialize />
+  </map:resource>}}}
+  
+  First we look to see if there's an XSP page associated with the publication. That's using the [ResourceExistsAction]. 
+ 
+ There is one, so it executes generating the XML for the page which asks for the page's id (for the URI) and the name (for the sitemap and navigation).
+ 
+ Then it's transformed with the appropriate XSLT and the form is delivered to the browser.
+ 
+ ''To be continued in [LenyaCreatePageWalkthrough2].''
+