portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rwat...@apache.org
Subject svn commit: r355250 - in /portals/jetspeed-2/trunk/xdocs/guides: guide-menus-declarative-psml.xml guide-psml.xml
Date Thu, 08 Dec 2005 22:33:41 GMT
Author: rwatler
Date: Thu Dec  8 14:33:40 2005
New Revision: 355250

URL: http://svn.apache.org/viewcvs?rev=355250&view=rev
Log:
declarative menus guide checkpoint

Modified:
    portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml
    portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml

Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml?rev=355250&r1=355249&r2=355250&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml Thu Dec  8 14:33:40
2005
@@ -25,7 +25,333 @@
   <body>
 <section name="Declarative Menus">
 <p>
-<b>Document In Progress!</b>
+Declarative menus are used to add new or customize default navigation elements in displayed
portal pages.
+These PSML declarations are part of the <a href="guide-psml.html#Page">page</a>
and <a href="guide-psml.html#Folder">folder</a> elements.
+As with other PSML elements, effective menu declarations available for a given page are those
that are explicity
+defined in the page along with all defined in parent folders. For this reason, global site
menus are defined in
+the PSML associated with the site root folder. Menu definitions in a specific page or folder
override
+menus with the same name found in parent folders.
+</p>
+<p>
+Portal layout decorators access page menu declarations by name while rendering portal content.
Menus are
+used to create dynamic navigation panes, portal page tabs, bread crumb links, and pull downs.
+The Portal Site Component is responsible for fleshing out the dynamic menu definition options
with page specific PSML
+elements from the site. For instance, a global menu declaration would typically be involved
in the following
+sequence of events while a portal page is being composed:
+<ol>
+	<li>The portal layout decorator would request a menu definition by name,</li>
+	<li>the definition would be inherited by the current page and located in the root
folder PSML,</li>
+	<li>the Portal Site Component would interpret the menu definition in the context of
the current page and populate <a href="guide-psml.html#Page">page</a>, <a href="guide-psml.html#Folder">folder</a>,
and <a href="guide-psml.html#Link">link</a> menu options,</li>
+	<li>the decorator would display the menu rendering titles and text from the menu definition
itself and the computed menu options into portal navigation content.</li>
+</ol>
+</p>
+<p>
+There are default global menu declarations supported internally by the Portal Site Component
that do not need to
+be explicitly defined in any page or folder PSML elements of the site: 
+<ul>
+	<li><b>pages</b>: relative pages menu used to define the page tabs above
the portal.</li>
+	<li><b>breadcrumbs</b>: paths to page used to provide history links below
the page tabs.</li>
+	<li><b>navigations</b>: relative subfolders and root level links menu
used to define the navigation pane beside the portal.</li>
+	<li><b>back</b>: parent folder menu used to define the single "back" link
above the portal page tabs.</li>
+</ul>
+As one would expect, these built in menu definitions can be overridden by declaring menus
in the site PSML with the same name. 
+</p>
+<p>
+<ul>
+	<li><a href="#Menu_Definition">Menu Definition</a></li>
+    <ul>
+	    <li><a href="#Menu_Options_Definition">Options</a></li>
+	    <li><a href="#Menu_Separator_Definition">Separator</a></li>
+	    <li><a href="#Menu_Include_Definition">Include</a></li>
+	    <li><a href="#Menu_Exclude_Definition">Exclude</a></li>
+    </ul>
+	<li><a href="#Page_Layout_Decorators">Page Layout Decorators</a></li>
+	<li><a href="#Portal_Site_Component">Portal Site Component</a></li>
+</ul>
+</p>
+</section>
+
+<section name='Menu Definition'>
+<p>
+The &lt;menu&gt; element defines a menu to be used by the layout decorators or a
nested menu within another menu.
+There are many valid attributes for the menu element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>name</td>
+    <td>Identifies menu name for retrieval from template code and/or menu reference.
This attribute is required for top level nodes and ignored for nested menus.</td>
+    </tr>
+    <tr>
+    <td>options</td>
+    <td>Specifies root document path for this menu if deep inclusion of documents and
folders is specified by this menu. This attribute may also define document paths that specify
page, folder, or link menu options. Multiple option paths can be specified as a comma separated
list of paths and/or regular expression patterns. Relative paths are interpreted as relative
to the current page. Special patterns, '~' or '@', can be used to reference the current page.</td>
+    </tr>
+    <tr>
+    <td>depth</td>
+    <td>Specifies deep inclusion of documents from option folders, (depth &lt;
0 specifies infinite depth). Menu options are created to represent each visible page or link
in the site; folders are converted into nested menus constrained by this setting.</td>
+    </tr>
+    <tr>
+    <td>paths</td>
+    <td>Boolean attribute to control the inclusion of ordered path options from root
folder to the specified options. This setting is used to generate "history" or "bread crumb"
menus.</td>
+    </tr>
+    <tr>
+    <td>regexp</td>
+    <td>A boolean attribute the specifies whether wild card/regular expression processing
be performed on options values. File system command line regular expression syntax is supported.</td>
+    </tr>
+    <tr>
+    <td>profile</td>
+    <td>Specified name of Profile Locator to be used when evaluating option values.
This attribute also sets the default profile value for options and nested menus. Specifying
'*' forces the acceptance of all Profile Locator names; this can be used to override parent
menu selects a profile name.</td>
+    </tr>
+    <tr>
+    <td>order</td>
+    <td>Comma separated list of regexp patterns matched against list or regular expression
document path values to determine order of matched options. This attribute will be applied
as a default options value for any options elements, but is not used to reorder multiple options
children matches. If not specified, multiple options are included in the order returned by
the underlying folder document orderings. Option paths not matched by this attribute are appended
after ordered matches.</td>
+    </tr>
+    <tr>
+    <td>skin</td>
+    <td>Optional decorator defined layout hint for the menu. This attribute is also
used as the default skin value for options and nested menus. This hint is not currently used
by Jetspeed2 decorators.</td>
+    </tr>
+</table>
+<p>
+The &lt;menu&gt; element contains a number of other menu definition PSML elements.
With the exception of the title and metadata elements, the relative order of these elements
determines the order that the layout decorators present them:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>title?</td>
+    <td>Simple element text specifies default locale-independent title for the menu.
The title of the menu is considered its long description and is used as rollover text in some
decorators if the short title is available for the menu text. If not specified, the name of
the menu will be used.</td>
+    </tr>
+    <tr>
+    <td>short-title?</td>
+    <td>Simple element text specifies default locale-independent short title for the
menu. The short title, if available, is used as menu text in some decorators. If not specified,
the title text is used.</td>
+    </tr>
+    <tr>
+    <td><a href="guide-psml.html#PSML_Titles_and_Metadata">metadata</a>*</td>
+    <td>Optionally specifies additional locale-specific titles and short titles.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menu_Options_Definition">options</a>*</td>
+    <td>This ordered menu element specifies content elements for this menu definition.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menu_Separator_Definition">separator</a>*</td>
+    <td>An ordered menu element used to specify text lines to be included inline in
this menu definition.</td>
+    </tr>
+    <tr>
+    <td>menu*</td>
+    <td>Another ordered menu element used to define a nested menu contained in this
menu definition.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menu_Include_Definition">include</a>*</td>
+    <td>Specifies a menu to nest within or options from a another menu to be included
in this menu definition. The name of the menu to include is the text of this ordered menu
element.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menu_Exclude_Definition">exclude</a>*</td>
+    <td>Specifies options and nested menus from another menu to be excluded from this
menu definition. The name of the menu with elements to exclude is the text of this ordered
menu element.</td>
+    </tr>
+</table>
+<p>Examples:</p>  
+<source><![CDATA[
+<menu name="simple">
+    <options>/some-top-page.psml,/custom/some-other-page.psml</options>
+</menu>
+]]></source>
+<source><![CDATA[
+<menu name="top-2-levels" options="/" depth="2" skin="dhtml-pull-down"/>
+]]></source>
+<source><![CDATA[
+<menu name="top-role-pages" regexp="true" options="/*" profile="roles"/>
+]]></source>
+<source><![CDATA[
+<menu name="top-custom">
+    <title>Top Menu</title>
+    <metadata name="title" xml:lang="fr">Haut</metadata>
+    <options regexp="true" profile="groups">/group-pages/*</options>
+    <menu options="/" profile="page">
+        <separator>
+            <text>-- Top Pages --</text>
+            <title>Top Pages</title>
+        </separator>
+        <options regexp="true">/*</options>
+        <separator>
+            <title>Custom Pages</title>
+        </separator>
+        <options depth="2">/custom-folder/</options>
+    </menu>
+    <exclude>top-role-pages</exclude>
+    <separator>More Top Pages</separator>
+    <include nest="true">top-role-pages</include>
+</menu>
+]]></source>
+<p>The definitions for the default global menu declarations supported internally by
the Portal Site Component:</p>  
+<source><![CDATA[
+<menu name="pages" regexp="true" options="*.psml"/>
+]]></source>
+<source><![CDATA[
+<menu name="breadcrumbs" options="~" paths="true"/>
+]]></source>
+<source><![CDATA[
+<menu name="navigations">
+  <separator>Folders</separator>
+  <options regexp="true">./*/</options>
+  <include>page-navigations</include>
+  <separator>Additional Links</separator>
+  <options regexp="true">/*.link</options>
+</menu>
+]]></source>
+<source><![CDATA[
+<menu name="back" options="../"/>
+]]></source>
+<p>Note that the separator text of these definitions is localized internally.</p>
 
+</section>
+
+<section name='Menu Options Definition'>
+<p>
+The &lt;options&gt; element defines a single or multiple options within a <a href="#Menu_Definition">menu</a>.
The text of this simple element specifies document paths that yield page, folder, or link
menu options. Multiple option paths can be specified as a comma separated list of paths and/or
regular expression patterns. Relative paths are interpreted as relative to the current page.
Special patterns, '~' or '@', can be used to reference the current page. This element shares
many attributes in common with the menu element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>depth</td>
+    <td>Specifies deep inclusion of documents from option folders, (depth &lt;
0 specifies infinite depth). Menu options are created to represent each visible page or link
in the site; folders are converted into nested menus constrained by this setting.</td>
+    </tr>
+    <tr>
+    <td>paths</td>
+    <td>Boolean attribute to control the inclusion of ordered path options from root
folder to the specified options. This setting is used to generate "history" or "bread crumb"
menus.</td>
+    </tr>
+    <tr>
+    <td>regexp</td>
+    <td>A boolean attribute the specifies whether wild card/regular expression processing
be performed on options values. File system command line regular expression syntax is supported.</td>
+    </tr>
+    <tr>
+    <td>profile</td>
+    <td>Specified name of Profile Locator to be used when evaluating option values.
This attribute also sets the default profile value for options and nested menus. Specifying
'*' forces the acceptance of all Profile Locator names; this can be used to override parent
menu selects a profile name.</td>
+    </tr>
+    <tr>
+    <td>order</td>
+    <td>Comma separated list of regexp patterns matched against list or regular expression
document path values to determine order of matched options. This attribute will be applied
as a default options value for any options elements, but is not used to reorder multiple options
children matches. If not specified, multiple options are included in the order returned by
the underlying folder document orderings. Option paths not matched by this attribute are appended
after ordered matches.</td>
+    </tr>
+    <tr>
+    <td>skin</td>
+    <td>Optional decorator defined layout hint for the menu options. This hint is not
currently used by Jetspeed2 decorators.</td>
+    </tr>
+</table>
+<p>Example:</p>
+<source><![CDATA[
+<menu>
+    ...
+    <options regexp="true" order="*.psml,*.link">/some-top-page.psml,/custom/some-other-page.psml,/*.link</options>
+    ...
+</menu>
+]]></source>
+</section>
+
+<section name='Menu Separator Definition'>
+<p>
+The &lt;separator&gt; element defines a separator to be included in a <a href="#Menu_Definition">menu</a>.
The separator will be included only if <a href="#Menu_Options_Definition">options</a>
or nested menus appear below this element within a menu definition. The text of the separator
can be specified in the contained text of this element or in the text menu definition element.
+There is only one attribute accepted by the separator element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>skin</td>
+    <td>Optional decorator defined layout hint for the menu separator. This hint is
not currently used by Jetspeed2 decorators.</td>
+    </tr>
+</table>
+<p>
+The &lt;separator&gt; element contains a number of other menu definition PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>title?</td>
+    <td>Simple element text specifies default locale-independent title for the separator.
The title of the separator is considered its long description and is used as rollover text
in some decorators if the separator text is available.</td>
+    </tr>
+    <tr>
+    <td>text?</td>
+    <td>Simple element text specifies default locale-independent text for the separator.
The required separator text, whether specified by this attribute or as the contained text
of the separator element, is the text to be inserted in the menu by the layout decorator.</td>
+    </tr>
+    <tr>
+    <td><a href="guide-psml.html#PSML_Titles_and_Metadata">metadata</a>*</td>
+    <td>Optionally specifies additional locale-specific titles and separator text.</td>
+    </tr>
+</table>
+<p>Examples:</p>  
+<source><![CDATA[
+<menu>
+    ...
+    <separator>-------------</separator>
+    ...
+    <separator>
+        <text>-- Top 10 Pages --</text>
+        <metadata name="text" xml:lang="fr">Haut Pages</metadata>
+        <title>Top 10 pages as voted by the Jetspeed2 users!</title>
+    </separator>
+    ...
+</menu>
+]]></source>
+</section>
+
+<section name='Menu Include Definition'>
+<p>
+The &lt;include&gt; element includes <a href="#Menu_Options_Definition">options</a>
or nested <a href="#Menu_Definition">menus</a> from another menu. The name of
the menu to include is specified as the text value of this element.
+There is only one valid attribute for the include element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>nest</td>
+    <td>Boolean flag that controls whether the specified menu is to be nested. If this
attribute is set to 'true', the included menu will be nested as a submenu; otherewise, all
options and nested menus from the specified menu will be inserted inline into this menu.</td>
+    </tr>
+</table>
+<p>Examples:</p>  
+<source><![CDATA[
+<menu>
+    ...
+    <include nest="true">navigations</include>
+    ...
+</menu>
+]]></source>
+</section>
+
+<section name='Menu Exclude Definition'>
+<p>
+The &lt;exclude&gt; element excludes <a href="#Menu_Options_Definition">options</a>
or nested <a href="#Menu_Definition">menus</a> from another menu. This option
is used primarily to remove menu options that already appear on the portal page in another
menu from this menu. Matching options or menus will be excluded only if they appear above
this element within a menu definition. The name of the menu to include is specified as the
text value of this simple element.
+</p>
+<p>Examples:</p>  
+<source><![CDATA[
+<menu>
+    ...
+    <exclude>pages</exclude>
+    ...
+</menu>
+]]></source>
+</section>
+
+<section name='Page Layout Decorators'>
+<p>
+</p>
+</section>
+
+<section name='Portal Site Component'>
+<p>
 </p>
 </section>
 

Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml?rev=355250&r1=355249&r2=355250&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml Thu Dec  8 14:33:40 2005
@@ -209,7 +209,7 @@
     </tr>
     <tr>
     <td>title?</td>
-    <td>Simple element containing text for the default page title. The title of the
page is considered its 'long' description and is used as rollover text in some decorators
if the short title is available for the menu text. If not specified, Jetspeed2 will attempt
to define a title from the name of the file that contains the page element.</td>
+    <td>Simple element containing text for the default page title. The title of the
page is considered its long description and is used as rollover text in some decorators if
the short title is available for the menu text. If not specified, Jetspeed2 will attempt to
define a title from the name of the file that contains the page element.</td>
     </tr>
     <tr>
     <td>short-title?</td>
@@ -553,7 +553,7 @@
     </tr>
     <tr>
     <td>title?</td>
-    <td>Simple element containing text for the default folder title. The title of the
folder is considered its 'long' description and is used as rollover text in some decorators
if the short title is available for the menu text. If not specified, Jetspeed2 will attempt
to define a title from the name of the file that contains the folder element.</td>
+    <td>Simple element containing text for the default folder title. The title of the
folder is considered its long description and is used as rollover text in some decorators
if the short title is available for the menu text. If not specified, Jetspeed2 will attempt
to define a title from the name of the file that contains the folder element.</td>
     </tr>
     <tr>
     <td>short-title?</td>
@@ -615,7 +615,7 @@
     </tr>
     <tr>
     <td>title?</td>
-    <td>Simple element containing text for the default link title. The title of the
link is considered its 'long' description and is used as rollover text in some decorators
if the short title is available for the menu text. If not specified, Jetspeed2 will attempt
to define a title from the name of the file that contains the link element.</td>
+    <td>Simple element containing text for the default link title. The title of the
link is considered its long description and is used as rollover text in some decorators if
the short title is available for the menu text. If not specified, Jetspeed2 will attempt to
define a title from the name of the file that contains the link element.</td>
     </tr>
     <tr>
     <td>short-title?</td>
@@ -673,7 +673,7 @@
 <p>Example: <a href="#PSML">see intoductory examples above.</a></p>
 
 </section>
 
-<section name='Titles and Metadata'>
+<section name='PSML Titles and Metadata'>
 <p>
 The <a href="#Page">page</a>, <a href="#Folder">folder</a>, and <a
href="#Link">link</a> &lt;metadata&gt; element is used to define locale specific
title and short title text.
 Any number of these elements may appear within a containing PSML element, but multiple named
values should not be specified for a single locale.



---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message