You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by rw...@apache.org on 2005/12/08 23:33:41 UTC
svn commit: r355250 - in /portals/jetspeed-2/trunk/xdocs/guides:
guide-menus-declarative-psml.xml guide-psml.xml
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 <menu> 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 < 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 <menu> 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 <options> 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 < 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 <separator> 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 <separator> 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 <include> 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 <exclude> 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> <metadata> 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