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 07:59:20 UTC

svn commit: r355015 - in /portals/jetspeed-2/trunk/xdocs/guides: guide-menus-declarative-psml.xml guide-psml.xml guide-security-declarative-psml.xml index.xml

Author: rwatler
Date: Wed Dec  7 22:59:10 2005
New Revision: 355015

URL: http://svn.apache.org/viewcvs?rev=355015&view=rev
Log:
major PSML guide update

Added:
    portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml   (with props)
Modified:
    portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml
    portals/jetspeed-2/trunk/xdocs/guides/guide-security-declarative-psml.xml
    portals/jetspeed-2/trunk/xdocs/guides/index.xml

Added: 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=355015&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml Wed Dec  7 22:59:10 2005
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2005 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+  <properties>
+    <title>Guide to Declarative Menus in PSML</title>
+    <subtitle>Guide to Declarative Menus in PSML</subtitle>
+    <authors>
+      <person name="Randy Watler" email="rwatler@apache.org"/>
+    </authors>
+  </properties>
+  <body>
+<section name="Declarative Menus">
+<p>
+<b>Document In Progress!</b>
+</p>
+</section>
+
+</body>
+</document>

Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-menus-declarative-psml.xml
------------------------------------------------------------------------------
    svn:eol-style = native

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=355015&r1=355014&r2=355015&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-psml.xml Wed Dec  7 22:59:10 2005
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!--
-Copyright 2004 The Apache Software Foundation
+Copyright 2004-2005 The Apache Software Foundation
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -20,18 +20,26 @@
     <subtitle>Documentation for Designers working with PSML</subtitle>
     <authors>
       <person name="David Sean Taylor" email="taylor@apache.org"/>
+      <person name="Randy Watler" email="rwatler@apache.org"/>
     </authors>
   </properties>
   <body>
 <section name="PSML">
 <ul>
-     <li><a href="#Page">Page</a></li>          
-     <li><a href="#Defaults">Defaults</a></li>     
-    <li><a href="#Title_and_Metadata">Title and Metadata</a></li>
-    <li><a href="#Layout_Fragments">Layout Fragments</a></li>    
-    <li><a href="#Portlet_Fragments">Portlet Fragments</a></li>    
-    <li><a href="#Preferences">Portlet Preferences</a></li>
+    <li><a href="#Page">Page</a></li>          
+    <ul>
+        <li><a href="#Defaults">Defaults</a></li>     
+        <li><a href="#Layout_Fragments">Layout Fragments</a></li>    
+        <li><a href="#Portlet_Fragments">Portlet Fragments</a></li>    
+        <li><a href="#Fragment_Properties">Fragment Properties</a></li>
+        <li><a href="#Preferences">Portlet Preferences</a></li>
+    </ul>
+    <li><a href="#Folder">Folder</a></li>          
+    <li><a href="#Link">Link</a></li>          
+    <li><a href="#Global_Page_Security">Global Page Security</a></li>          
+    <li><a href="#PSML_Titles_and_Metadata">Titles and Metadata</a></li>
     <li><a href="#PSML_Security_Constraints">Security Constraints</a></li>        
+    <li><a href="#PSML_Menus">Menus</a></li>        
 </ul>
     
 <p>
@@ -41,236 +49,677 @@
 Jetspeed-1. This document can be used as a reference guide to the elements of a PSML resource.
 </p>
 <p>
-Here is an example PSML file:    
+PSML files also capture other portal site information related to pages, folders, links, and global security constraints.
+Each of these primary PSML elements are captured in separate documents arranged in a hierarchy of directories in the file system.
+Typically, this directory is accessed as a resource at /WEB-INF/pages within the jetspeed web application.
+</p>
+<p>
+Here is an example PSML file for a portal site <a href="#Page">page</a>, (*.psml):
 </p>
 <source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
 <page>
-  <defaults
-     skin="orange"
-     layout-decorator="tigris"
-     portlet-decorator="tigris"
-  />
+  <!-- page info -->
   <title>Welcome to Jetspeed 2</title>
-  <metadata name="title" xml:lang="fr">
-        Ma Premiere Page de PSML
-  </metadata>
-  <metadata name="title" xml:lang="ja">
-        Jetspeed 2 へようこそ
-  </metadata>
-
-  <fragment id="dp-1" type="layout" name="jetspeed::VelocityTwoColumns">
-    <fragment id="dp-3" type="portlet" name="pam::LocaleSelector">
-      <property layout="TwoColumns" name="row" value="0" />
-      <property layout="TwoColumns" name="column" value="0" />
+  <metadata name="title" xml:lang="fr">Ma Premiere Page de PSML</metadata>
+  <metadata name="title" xml:lang="es">¡Bienvenido a Jetspeed 2!</metadata>
+  <metadata name="title" xml:lang="hu">Köszönti a Jetspeed 2!</metadata>
+
+  <!-- page decoration -->
+  <defaults skin="orange" layout-decorator="tigris" portlet-decorator="tigris"/>
+
+  <!-- page fragments -->
+  <fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
+    <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
+      <property layout="OneColumn" name="row" value="0"/>
     </fragment>                                
-    <fragment id="dp-12" type="portlet" name="security::LoginPortlet">
-      <property layout="TwoColumns" name="row" value="0" />
-      <property layout="TwoColumns" name="column" value="1" />
-    </fragment>                                
-    <fragment id="dp-7" type="portlet" name="demo::PickANumberPortlet" >
-      <property layout="TwoColumns" name="row" value="1" />
-      <property layout="TwoColumns" name="column" value="0" />
-    </fragment>        
-    <fragment id="dp-16" type="portlet" name="demo::RoleSecurityTest">
-      <property layout="TwoColumns" name="row" value="1" />
-      <property layout="TwoColumns" name="column" value="1" />
-    </fragment>
-    <fragment id="dp-9" type="portlet" name="demo::IFramePortlet">
-      <property layout="TwoColumns" name="row" value="2" />
-      <property layout="TwoColumns" name="column" value="0" />
-    </fragment>
-    <fragment id="dp-17" type="portlet" name="demo::UserInfoTest">
-      <property layout="TwoColumns" name="row" value="2" />
-      <property layout="TwoColumns" name="column" value="1" />
-    </fragment>
-    <fragment id="dp-18" type="portlet" name="demo::BookmarkPortlet">
-      <property layout="TwoColumns" name="row" value="3" />
-      <property layout="TwoColumns" name="column" value="1" />
+    <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
+      <property layout="OneColumn" name="row" value="1"/>
+      <property layout="TwoColumns" name="sizes" value="33%,66%"/>
+      <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
+        <property layout="TwoColumns" name="row" value="0"/>
+        <property layout="TwoColumns" name="column" value="0"/>
+      </fragment>                                
+      <fragment id="100171" type="portlet" name="demo::UserInfoTest">
+        <property layout="TwoColumns" name="row" value="0"/>
+        <property layout="TwoColumns" name="column" value="1"/>
+      </fragment>    
     </fragment>
   </fragment>
 
+  <!-- security constraints -->
   <security-constraints>
     <security-constraints-ref>public-view</security-constraints-ref>
   </security-constraints>
 </page>
 ]]></source>
+<p>
+Here is an example PSML file that defines portal site <a href="#Folder">folder</a>, (folder.metadata):
+</p>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<folder>
+  <!-- folder description -->
+  <title>Root Folder</title>  
+  <metadata name="title" xml:lang="fr">Répertoire racine</metadata>
+  <metadata name="title" xml:lang="es">Carpeta raiz</metadata>
+
+  <!-- order of documents in folder -->
+  <document-order>Jetspeed2.link</document-order>
+  <document-order>Jetspeed2Wiki.link</document-order>
+  <document-order>apache_portals.link</document-order>
+  <document-order>apache.link</document-order>
+
+  <!-- portal site menus -->
+  <menu name="page-navigations">
+    <separator>
+      <text>Top Pages</text>
+      <metadata name="text" xml:lang="fr">Page haut</metadata>
+      <metadata name="text" xml:lang="es">Páginas más populares</metadata>
+    </separator>
+    <options>/Administrative</options>
+    <separator>
+      <text>Profiled Pages</text>
+      <metadata name="text" xml:lang="es">Páginas del Perfil</metadata>
+    </separator>
+    <options regexp="true">/p[0-9][0-9][0-9].psml</options>
+    <separator>
+      <text>Non Java Pages</text>
+      <metadata name="text" xml:lang="es">Ejemplos sin java</metadata>
+    </separator>
+    <options>/non-java</options>
+  </menu>
+
+  <!-- security constraints -->
+  <security-constraints>
+    <security-constraints-ref>public-view</security-constraints-ref>
+  </security-constraints>
+</folder>
+]]></source>
+<p>
+Here is an example PSML file for a portal site <a href="#Link">link</a>, (*.link):
+</p>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<link target="top">
+  <!-- link description -->
+  <title>Jetspeed 2 Home Page</title>
+  <url>http://portals.apache.org/jetspeed-2/</url>
+  <metadata name="title" xml:lang="es">Jetspeed 2</metadata>
+</link>
+]]></source>
+<p>
+Here is an example PSML file for the portal site <a href="#Global_Page_Security">page security</a>, (page.security):
+</p>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<page-security>
+  <!-- global admin constraints -->
+  <security-constraints-def name="admin">
+    <security-constraint>
+      <roles>admin</roles>
+      <permissions>view, edit</permissions>
+    </security-constraint>
+  </security-constraints-def>
+  <global-security-constraints-ref>admin</global-security-constraints-ref>
+
+  <!-- public constraints -->
+  <security-constraints-def name="public-view">
+    <security-constraint>
+      <users>*</users>
+      <permissions>view</permissions>
+    </security-constraint>
+  </security-constraints-def>
+  <security-constraints-def name="public-edit">
+    <security-constraint>
+      <users>*</users>
+      <permissions>view, edit</permissions>
+    </security-constraint>
+  </security-constraints-def>
+</page-security>
+]]></source>
 </section>
 <section name='Page'>
 <p>
-The Page element is a simple container to hold all other PSML elements.
-There are two valid attributes for the Page element:
+The &lt;page&gt; element is a simple container to hold other PSML elements associated with a portal site page.
+This element is persisted as a file with a '.psml' extension in the appropriate file system directory associated with the parent <a href="#Folder">folder</a>.
+There are two valid attributes for the page element:
 </p>
 <table>
     <tr>
-    <th>id</th>
-    <th>hidden</th>
+    <th>Attribute</th>
+    <th>Description</th>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
+    <td>hidden</td>
+    <td>A boolean attribute used to indicate that a page should not appear in portal site menus or other navigational elements.</td>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
+    <td>version</td>
+    <td>A general purpose version tracking attribute. Not currently used by Jetspeed2.</td>
     </tr>
 </table>
-<p>Example:</p>  
-<source><![CDATA[
-<page id='mypage' hidden='false'>
-...
-</page>  
-]]></source>
+<p>
+The &lt;page&gt; element contains a number of other PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </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>
+    </tr>
+    <tr>
+    <td>short-title?</td>
+    <td>Optional simple element containing text of the default short title for the page. 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="#Defaults">defaults</a></td>
+    <td>Specifies the decorations for the page and its fragments. Defaults are required for each page.</td>
+    </tr>
+    <tr>
+    <td><a href="#Layout_Fragments">fragment</a></td>
+    <td>The root of the fragment hierarchy. All pages require a root Fragment.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Titles_and_Metadata">metadata</a>*</td>
+    <td>Optionally specifies locale specific titles and short titles for the page.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menus">menu</a>*</td>
+    <td>Optionally specifies additional or overrides inherited menu definitions for the page.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints</a>?</td>
+    <td>Optionally defines inline security constraints for the page. If not specified, the page inherits the security constraints effective in the parent <a href="#Folder">folder</a>.</td>
+    </tr>
+</table>
+<p>Example: <a href="#PSML">see intoductory examples above.</a></p>  
 </section>
+
 <section name='Defaults'>
 <p>
-The Defaults element defines the default layout decorator and default portlet decorator.
+The <a href="#Page">page</a> &lt;defaults&gt; element defines the default layout decorator and default portlet decorator.
 The default layout decorator is applied to all layout fragments which do NOT have a decorator attribute.
 The default portlet decorator is applied to all portlet fragments which do NOT have a decorator attribute.
 There are three valid attributes on the defaults element:
 </p>
 <table>
     <tr>
-    <th>skin</th>
-    <th>layout-decorator</th>
-    <th>portlet-decorator</th>    
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>layout-decorator</td>
+    <td>The name of the layout decorator used to render the page. This attribute is required.</td>    
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>portlet-decorator</td>
+    <td>The name of the default portlet decorator used to render the page fragments. This attribute is optional, but is almost always set.</td>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>skin</td>
+    <td>A general purpose decorator attribute that can be referenced in the decorators to control page and fragment presentation. Not currently used by Jetspeed2.</td>    
     </tr>
 </table>
 <p>Example:</p>  
 <source><![CDATA[
+<page>
+  ...
+  <defaults skin="orange" layout-decorator="tigris" portlet-decorator="tigris"/>
+  ...
+</page>
 ]]></source>
 </section>
 
-<section name='Title and Metadata'>
+<section name='Layout Fragments'>
 <p>
+The <a href="#Page">page</a> layout &lt;fragment&gt; element is a hierarchical container used to hold <a href="#Portlet_Fragments">portlet fragments</a> and nested layout fragments.
+The root fragment of a <a href="#Page">page</a> must be a layout fragment, even when only one portlet fragment is part of the page.
+Layout fragments are subject to layout of the parent layout fragment and thus support the 'row' and 'column' <a href="#Fragment_Properties">layout properties</a>.
+In addition, they also support the 'sizes' layout property used to control multicolumn layout proportions.
+There are 3 required attributes for this element:
 </p>
 <table>
     <tr>
-    <th></th>
-    <th></th>
-    <th></th>    
+    <th>Attribute</th>
+    <th>Description</th>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>id</td>
+    <td>The required id is used to identify a fragment and <b>must</b> be unique across all fragments defined within the site. The value is opaque to Jetspeed2 and can follow any convention to guarantee uniqueness. Since fragments may be cached internally by Jetspeed2, any edits to exiting pages may require new ids to ensure the modifications are taken by Jetspeed2.</td>    
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>type</td>
+    <td>This required attribute must be set to 'layout' for all layout fragments.</td>    
+    </tr>
+    <tr>
+    <td>name</td>
+    <td>The required name of the portlet used to implement the fragment layout. The portlet name generally takes the form of 'portlet-app-id:portlet-id' as specified in the portlet.xml files. Here are the supported Jetspeed2 layout portlet names:
+        <ul>
+            <li>jetspeed-layouts::FrameLayoutPortlet</li>
+            <li>jetspeed-layouts::VelocityOneColumn</li>
+            <li>jetspeed-layouts::VelocityOneColumnNoActions</li>
+            <li>jetspeed-layouts::VelocityThreeColumns</li>
+            <li>jetspeed-layouts::VelocityThreeColumnsNoActions</li>
+            <li>jetspeed-layouts::VelocityThreeColumnsTable</li>
+            <li>jetspeed-layouts::VelocityTwoColumns</li>
+            <li>jetspeed-layouts::VelocityTwoColumns2575</li>
+            <li>jetspeed-layouts::VelocityTwoColumns2575NoActions</li>
+            <li>jetspeed-layouts::VelocityTwoColumnsNoActions</li>
+            <li>jetspeed-layouts::VelocityTwoColumnsSmallLeft</li>
+            <li>jetspeed-layouts::VelocityTwoColumnsSmallLeftNoActions</li>
+            <li>jetspeed-layouts::VelocityTwoColumnsTable</li>
+        </ul>
+    </td>
+    </tr>
+</table>
+<p>
+The layout &lt;fragment&gt; element contains a number of other PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td><a href="#Portlet_Fragments">fragment*</a></td>
+    <td>Specified fragment elements can be either portlet fragments to be laid out by this layout fragment or nested layout fragments. All child fragments will have required <a href="#Fragment_Properties">property</a> elements to specify their positions in this layout. Specifying no fragments within a layout fragment will result in no content being generated.</td>
+    </tr>
+    <tr>
+    <td><a href="#Fragment_Properties">property*</a></td>
+    <td>Layout fragments can have an optional 'sizes' property that can be used to specify multicolumn layout proportions. Nested layout fragments may also have 'row' and/or 'column' properties to identify its positional location in the parent layout.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints</a>?</td>
+    <td>Optionally defines inline security constraints for the fragment and its child fragments. Unlike, page, folder, and link constraints, only 'view' permissions can be constrained. If not specified, the fragment inherits the security constraints effective in the <a href="#Page">page</a>.</td>
     </tr>
 </table>
 <p>Example:</p>  
 <source><![CDATA[
+<page>
+  ...
+  <fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
+    <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
+      <property layout="OneColumn" name="row" value="0"/>
+    </fragment>                                
+    <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
+      <property layout="OneColumn" name="row" value="1"/>
+      <property layout="TwoColumns" name="sizes" value="33%,66%"/>
+      <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
+        <property layout="TwoColumns" name="row" value="0"/>
+        <property layout="TwoColumns" name="column" value="0"/>
+      </fragment>                                
+      <fragment id="100171" type="portlet" name="demo::UserInfoTest">
+        <property layout="TwoColumns" name="row" value="0"/>
+        <property layout="TwoColumns" name="column" value="1"/>
+      </fragment>    
+    </fragment>
+  </fragment>
+  ...
+</page>
 ]]></source>
 </section>
 
-<section name='Layout Fragments'>
+<section name='Portlet Fragments'>
 <p>
+The portlet &lt;fragment&gt; element is used to identify portlets on the page. Portlet fragments are subject to layout of the parent layout fragment and thus support the 'row' and 'column' <a href="#Fragment_Properties">layout properties</a> as required by the layout.
+There are many valid attributes for this element:
 </p>
 <table>
     <tr>
-    <th></th>
-    <th></th>
-    <th></th>    
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>id</td>
+    <td>The required id is used to identify a fragment and <b>must</b> be unique across all fragments defined within the site. The value is opaque to Jetspeed2 and can follow any convention to guarantee uniqueness. Since fragments may be cached internally by Jetspeed2, any edits to exiting pages may require new ids to ensure the modifications are taken by Jetspeed2.</td>    
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>type</td>
+    <td>This required attribute must be set to 'portlet' for all portlet fragments.</td>    
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>name</td>
+    <td>The required name of the portlet used to populate the fragment content. The portlet name generally takes the form of 'portlet-app-id:portlet-id' as specified in the portlet.xml files.</td>
+    </tr>
+    <tr>
+    <td>skin</td>
+    <td>A general purpose decorator attribute that can be referenced in the portlet decorators to control fragment presentation. Not currently used by Jetspeed2.</td>    
+    </tr>
+    <tr>
+    <td>decorator</td>
+    <td>The name of the default portlet decorator used to render the fragments. This attribute is optional, but if it is not specified, the <a href="#Defaults">defaults</a> for the page must specify a default portlet decorator.</td>
+    </tr>
+    <tr>
+    <td>state</td>
+    <td>The initial state of the fragment portlet; 'hidden' is currently the only valid value for this attribute.</td>
+    </tr>
+</table>
+<p>
+The portlet &lt;fragment&gt; element contains other PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td><a href="#Fragment_Properties">property*</a></td>
+    <td>Parent fragments may have 'row' and/or 'column' properties to identify positional location in the parent layout.</td>
+    </tr>
+    <tr>
+    <td>title?</td>
+    <td>Optional simple text element containing title for fragment portlet, overridding titles set in portlet.xml.</td>
+    </tr>
+    <tr>
+    <td><a href="#Preferences">preference*</a></td>
+    <td>Specifies initial user preference settings for fragment portlet, overridding any portlet preferences set in portlet.xml. User preferences, in turn, override these values.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints</a>?</td>
+    <td>Optionally defines inline security constraints for the fragment. Unlike, page, folder, and link constraints, only 'view' permissions can be constrained. If not specified, the fragment inherits the security constraints effective in the <a href="#Page">page</a>.</td>
     </tr>
 </table>
 <p>Example:</p>  
 <source><![CDATA[
+<fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
+  ...
+  <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
+    <property layout="OneColumn" name="row" value="0"/>
+  </fragment>                                
+  ...
+</fragment>
 ]]></source>
 </section>
 
-<section name='Portlet Fragments'>
+<section name='Fragment Properties'>
 <p>
+The <a href="#Portlet_Fragments">fragment</a> &lt;property&gt; element is use to specify named properties for fragments. These properties are used commonly to specify layout portlet parameters and portlet positional location within the page. The property element has 3 supported attributes:
 </p>
 <table>
     <tr>
-    <th></th>
-    <th></th>
-    <th></th>    
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>layout <i>(deprecated)</i> </td>
+    <td>The symbolic name of the layout fragment portlet the property is associated with. This attribute is supported for compatibility reasons. The strictly hierarchical structure of layout and portlet fragments implies that any single fragment and its properties can be subject to one layout fragment portlet.</td>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>name</td>
+    <td>The fragment property name. Jetspeed2 layout portlets support the 'row', 'column' and 'sizes' properties.</td>
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>value</td>
+    <td>The fragment property value. The 'row' and 'column' properties accept 0-based indicies values. The 'sizes' property accepts HTML frameset tag 'rows' and 'cols' attributes sytax, (i.e. '25%,75%').</td>    
     </tr>
 </table>
-<p>Example:</p>  
+<p>Examples:</p>  
 <source><![CDATA[
-
+<fragment id="100876" type="portlet" name="j2-admin::LoginPortlet">
+  ...
+  <property layout="TwoColumns" name="row" value="2"/>
+  <property layout="TwoColumns" name="column" value="1"/>
+  ...
+</fragment>
+]]></source>
+<source><![CDATA[
+<fragment id="103456" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
+  ...
+  <property layout="TwoColumns" name="sizes" value="33%,66%"/>
+  ...
+</fragment>
 ]]></source>
 </section>
 
 <section name='Preferences'>
 <p>
-    The &lt;preference&gt; elements allows for the defining of portlet preferences.  
-	This provides an eaiser avenue for the setting of default portlet prefences for a portlet
-    instance on a page without having to duplicate a portlet definition within
-    the portlet application's portlet.xml.
-	<br/><br/>
-	A fragment can contain 0..n &lt;preference&gt; elements.
-	<br/><br/>
-	Preference precedence: User Defined > Fragment Defined > portlet.xml Defined.
+The <a href="#Portlet_Fragments">portlet fragment</a> &lt;preference&gt; elements allows for the defining of portlet preferences.  
+This provides an eaiser avenue for the setting of default portlet prefences for a portlet
+instance on a page without having to duplicate a portlet definition within
+the portlet application's portlet.xml.
+</p>
+<p>
+Preference precedence: User Defined > Fragment Defined > portlet.xml Defined.
 </p>
+<p>The &lt;preference&gt; element attributes:</p>  
 <table>
     <tr>
-    <th>Attribute: name</th>
-    <th>Attribute: readOnly</th>
-    <th>Element: value</th>    
+    <th>Attribute</th>
+    <th>Description</th>
     </tr>
     <tr>
+    <td>name</td>
     <td>The name of the preference.</td>
-    <td>Whether or not the user can change the value of this preference.</td>
-    <td>There can be 1..n <i>&lt;value&gt;</i> elements assigned to a single preference.</td>    
     </tr>
     <tr>
-    <td></td>
-    <td></td>
-    <td></td>    
+    <td>readOnly</td>
+    <td>Boolean indicating whether or not the user can change the value of this preference.</td>
+    </tr>
+</table>
+<p>The &lt;preference&gt; element contains these elements:</p>  
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>value+</td>
+    <td>Simple text element containing a value associated with the named preference.</td>    
     </tr>
 </table>
 <p>Example:</p>  
 <source><![CDATA[
+<fragment id="uhtemp-1012" type="portlet" name="demo::BookmarkPortlet">
+  ...
+  <preference name="Google" readOnly="false">
+    <value>http://www.google.com</value>
+  </preference>
+  ...
+</fragment>
+]]></source>
+</section>
 
-    <fragment id="uhtemp-1012" type="portlet" name="demo::BookmarkPortlet">
-      <property layout="TwoColumns" name="row" value="2" />
-      <property layout="TwoColumns" name="column" value="1" />
-      <preference name="Google" readOnly="false">
-        <value>http://www.google.com</value>
-      </preference>
-    </fragment>
+<section name='Folder'>
+<p>
+The &lt;folder&gt; element is a simple container to hold other PSML elements associated with a portal site folder.
+This element is persisted as a folder.metadata file in the associated file system directory.
+There are two valid attributes for the folder element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>hidden</td>
+    <td>A boolean attribute used to indicate that a folder should not appear in portal site menus or other navigational elements.</td>
+    </tr>
+    <tr>
+    <td>version</td>
+    <td>A general purpose version tracking attribute. Not currently used by Jetspeed2.</td>
+    </tr>
+</table>
+<p>
+The &lt;folder&gt; element contains a number of other PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </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>
+    </tr>
+    <tr>
+    <td>short-title?</td>
+    <td>Optional simple element containing text of the default short title for the folder. 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>default-page?</td>
+    <td>Optional simple element containing text with the default page or subfolder name for the folder. The default page is used when the folder is directly referenced in the portal. The name of any <a href="#Page">page</a> or folder in this folder, (including '..' for the parent folder), can be specified. If no default page is set, the page named 'default-page.psml' will be used; if 'default-page.psml' does not exist, the first page in the folder will become the default.</td>
+    </tr>
+
+    <tr>
+    <td>document-order*</td>
+    <td>An optional collection of simple elements containing text names used to define a sort order for <a href="#Page">page</a>, subfolder, and <a href="#Link">link</a> members. Members with matching names will be arranged in the order these elements are defined. Other members will be sorted by their names and will appear in menus and other lists after the matching members. Regular expressions for name matching are not supported.</td>
+    </tr>
+
+    <tr>
+    <td><a href="#PSML_Titles_and_Metadata">metadata</a>*</td>
+    <td>Optionally specifies locale specific titles and short titles for the folder.</td>
+    </tr>
+    <tr>
+    <td><a href="#Menus">menu</a>*</td>
+    <td>Optionally specifies additional or overrides inherited menu definitions for the folder.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints</a>?</td>
+    <td>Optionally defines inline security constraints for the folder. If not specified, the folder inherits the security constraints effective in the parent folder.</td>
+    </tr>
+</table>
+<p>Example: <a href="#PSML">see intoductory examples above.</a></p>  
+</section>
+
+<section name='Link'>
+<p>
+The &lt;link&gt; element is a simple container to hold other PSML elements associated with a portal link used to reference content external to the portal site.
+This element is persisted as a file with a '.link' extension in the appropriate file system directory associated with the parent <a href="#Folder">folder</a>.
+There are two valid attributes for the link element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>target</td>
+    <td>An optional target frame name in which to open the external content. If not specified, the linked content will replace the portal in the browser.</td>
+    </tr>
+    <tr>
+    <td>version</td>
+    <td>A general purpose version tracking attribute. Not currently used by Jetspeed2.</td>
+    </tr>
+</table>
+<p>
+The &lt;link&gt; element contains a number of other PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </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>
+    </tr>
+    <tr>
+    <td>short-title?</td>
+    <td>Optional simple element containing text of the default short title for the link. 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>url</td>
+    <td>The required content url element. The text of this element will be used to navigate the specified target frame in the browser.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Titles_and_Metadata">metadata</a>*</td>
+    <td>Optionally specifies locale specific titles and short titles for the link.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints</a>?</td>
+    <td>Optionally defines inline security constraints for the link. If not specified, the link inherits the security constraints effective in the parent <a href="#Folder">folder</a>.</td>
+    </tr>
+</table>
+<p>Example: <a href="#PSML">see intoductory examples above.</a></p>  
+</section>
 
+<section name='Global Page Security'>
+<p>
+The &lt;page-security&gt; element is a simple container to hold other PSML elements used to declare global security constraints and their definitions..
+This element is persisted as the page.security file and is always located in the root directory of the PSML file system directories.
+There is only one valid attribute for the page security element:
+</p>
+<table>
+    <tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td>version</td>
+    <td>A general purpose version tracking attribute. Not currently used by Jetspeed2.</td>
+    </tr>
+</table>
+<p>
+The &lt;page-security&gt; element contains two security constraints related PSML elements:
+</p>
+<table>
+    <tr>
+    <th>Element</th>
+    <th>Description</th>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">security-constraints-def</a>*</td>
+    <td>Optionally defines a collection of security constraints defined by name. These security constraints are referenced in <a href="#Page">pages</a>, <a href="#Layout_Fragments">fragments</a>, <a href="#Folder">folders</a>, and <a href="#Link">links</a> and in this element to facilitate reuse and security maintenance.</td>
+    </tr>
+    <tr>
+    <td><a href="#PSML_Security_Constraints">global-security-constraints-ref</a>*</td>
+    <td>Optionally defines security constraints references to be applied to all security constraints in the site. The text of each simple element references a named security constraints definition specified here in this element.</td>
+    </tr>
+</table>
+<p>Example: <a href="#PSML">see intoductory examples above.</a></p>  
+</section>
+
+<section name='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.
+The PSML xml documents are normally declared with the UTF-8 encoding to support a wide variety of character sets.
+</p>
+<table>
+    <tr>
+    </tr>
+    <th>Attribute</th>
+    <th>Description</th>
+    <tr>
+    <td>name</td>
+    <td>Name of the metadata text. This name should be either 'title' or 'short-title' to specify locale specific title text.</td>
+    </tr>
+    <tr>
+    <td>xml:lang</td>
+    <td>The locale language or language/country selector for the metadata text. The conventional Java Locale names are expected, (ISO-639 and ISO-3166). Valid values would include 'en' and 'en_US'.</td>
+    </tr>
+</table>
+<p>Example:</p>  
+<source><![CDATA[
+<page>
+  ...
+  <metadata name="title" xml:lang="fr">Ma Premiere Page de PSML</metadata>
+  <metadata name="title" xml:lang="es">¡Bienvenido a Jetspeed 2!</metadata>
+  <metadata name="title" xml:lang="hu">Köszönti a Jetspeed 2!</metadata>
+  ...
+</page>
 ]]></source>
 </section>
 
 <section name="PSML Security Constraints">
 <p>
-<a href='bronco.html'>Link to Security Constraints Docs</a>
+The &lt;security-constraints&gt;, &lt;security-constraints-def&gt;, and &lt;global-security-constraints-ref&gt; elements that appear in <a href="#Page">pages</a>, <a href="#Layout_Fragments">fragments</a>, <a href="#Folder">folders</a>, <a href="#Link">links</a>, and the <a href="#Global_Page_Security">page security</a> elements above are documented separately in the the Declarative Security Constraints Guide.
+</p>
+<p>
+<a href='guide-security-declarative-psml.html'>Declarative Security Constraints Guide</a>
+</p>
+</section>
+
+<section name="PSML Menus">
+<p>
+The &lt;menu&gt; element that appears in <a href="#Page">page</a> and <a href="#Folder">folder</a> elements above are documented separately in the the Declarative Menus Guide.
+</p>
+<p>
+<a href='guide-menus-declarative-psml.html'>Declarative Menus Guide</a>
 </p>
 </section>
 

Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-security-declarative-psml.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-security-declarative-psml.xml?rev=355015&r1=355014&r2=355015&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-security-declarative-psml.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-security-declarative-psml.xml Wed Dec  7 22:59:10 2005
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!--
-Copyright 2004 The Apache Software Foundation
+Copyright 2004-2005 The Apache Software Foundation
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -20,6 +20,7 @@
     <subtitle>Guide to Declarative Security through PSML</subtitle>
     <authors>
       <person name="David Sean Taylor" email="taylor@apache.org"/>
+      <person name="Randy Watler" email="rwatler@apache.org"/>
     </authors>
   </properties>
   <body>
@@ -30,17 +31,18 @@
 	<li><a href="#Declarative and Global Constraints">Declarative and Global Constraints</a></li>	 
     <li><a href="#Folder Constraints">Folder Constraints</a></li>
     <li><a href="#Page Constraints">Page Constraints</a></li>    
+    <li><a href="#Fragment Constraints">Fragment Constraints</a></li>    
     <li><a href="#Spring Configuration">Spring Configuration</a></li>    
-    <li><a href="#Subsite Security">Subsite Security</a></li>        
 </ul>
 </p>
 <p>
 Security Constraints are applied to pages and folders.  Security Constraints either grant or deny 
-access to pages and folders.  Constraints can be defined in one of three places:
+access to pages and folders.  Constraints can be defined in one or all of these four places:
 <ul>
     <li>1. <b>Global:</b> As declarations in the <b><i>page.security</i></b> file found in the root of the PSML tree.</li>
-    <li>2. <b>Folder:</b> In the <b><i>folder.metadata</i></b> file optionally located in every directory</li>    
-    <li>3. <b>Page:</b> In PSML files to constraint access to specific pages</li>
+    <li>2. <b>Folder:</b> In the <b><i>folder.metadata</i></b> file optionally located in every directory.</li>    
+    <li>3. <b>Page:</b> In PSML files to constrain access to specific pages.</li>
+    <li>4. <b>Fragment:</b> In page PSML files to constrain access to a specific fragment within a page.</li>
 </ul>
 </p>
 <subsection name='Grants'>
@@ -200,11 +202,11 @@
 </section>
 <section name='Declarative and Global Constraints'>
 <p>
-Declarative constraints are declared in the <b><i>page.security</i></b> file of the root of a site or subsite.
+Declarative constraints are declared in the <b><i>page.security</i></b> file of the root of a site.
 Declarative constraints are referenced in pages and folders with the <b><i>security-constraints-ref</i></b> tag.
 Global constraints are also declarative constraints. They are also defined and found in the <b><i>page.security</i></b> file in the root PSML repository.
 The difference with global constraints is that they implicitly apply to all folders and pages within the scope of the page.security file, (i.e. the site).
-Note that there can be more than one <b><i>page.security</i></b> files in a subsite Jetspeed installation.
+Note that there can be only one <b><i>page.security</i></b> file in a Jetspeed installation.
 </p>
 <source><![CDATA[
   <security-constraints-def name="admin">
@@ -302,16 +304,42 @@
 Note that all security constraints must be placed within a <b><i>security-constraints</i></b> collection.
 </p>
 </section>
-<section name="Spring Configuration">
+<section name='Fragment Constraints'>
 <p>
-TODO: page-manager.xml enabling
+As with Page Security constraints, Fragment Security constraints are placed within
+<b><il>security-constraints list</il></b> in <b><i>PSML</i></b> page files and are
+again optional. As expected, the absence of a security constraints list implies the
+fragment will inherit the constraints of the page of which it is a part. Note that
+only the view permission is checked against these constraints. Other permissions
+are tested only against the containing page.
 </p>
 </section>
-<section name="Subsite Security">
+<section name="Spring Configuration">
 <p>
-subsite security
+Declarative Security Constraints are enabled by default in the Spring configuration of the
+Page Manager component. Here is the default Page Manager bean configuration from the
+<b><i>page-manager.xml</i></b> spring assembly configuration file:
+</p>
+<source><![CDATA[
+  <bean id="org.apache.jetspeed.page.PageManager" 
+       name="pageManager"
+       class="org.apache.jetspeed.page.psml.CastorXmlPageManager">         
+       <constructor-arg index="0"><ref bean="IdGenerator"/></constructor-arg>
+       <constructor-arg index="1"><ref bean="DocumentHandlerFactory"/></constructor-arg>
+       <constructor-arg index="2"><ref bean="FolderHandler"/></constructor-arg>
+       <constructor-arg index="3"><ref bean="PageFileCache"/></constructor-arg>        
+       <!-- permissions security enabled flag, default=false -->
+       <constructor-arg index="4"><value>false</value></constructor-arg>
+       <!-- constraints security enabled flag, default=true -->
+       <constructor-arg index="5"><value>true</value></constructor-arg>
+  </bean>
+]]></source>
+<p>
+Here the 6th, (index="5"), boolean constructor argument specifies whether or
+not the "constraints security" model is enabled. If the Declarative Security Constraints
+are not enabled, all inline, referenced, and global security constraints will be ignored. 
 </p>
 </section>
+
 </body>
 </document>
-

Modified: portals/jetspeed-2/trunk/xdocs/guides/index.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/index.xml?rev=355015&r1=355014&r2=355015&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/index.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/index.xml Wed Dec  7 22:59:10 2005
@@ -44,7 +44,6 @@
 			<li><a href="guide-database.html">Guide to database configuration</a></li>
 			<li><a href="guide-app-servers.html">Guide to application servers configuration</a></li>
 			<li><a href="guide-security.html">Guide to configuring Jetspeed-2 security</a></li>
-			<li><a href="guide-security-declarative-psml.html">Guide to portal entities declarative security through PSML</a></li>
 			<li><a href="guide-sso.html">Guide to using Jetspeed-2 single sign-on</a></li>
 			<li><a href="guide-user-attributes.html">Guide to defining user attributes (PLT.17 user information configuration)</a></li>
 			<li><a href="guide-profilers.html">Guide to using profilers</a></li>
@@ -55,6 +54,8 @@
 		<ul>
 			<li><a href="guide-portal-design.html">Guide to portal design</a></li>
 			<li><a href="guide-psml.html">Guide to PSML</a></li>
+			<li><a href="guide-security-declarative-psml.html">Guide to declarative security through PSML</a></li>
+			<li><a href="guide-menus-declarative-psml.html">Guide to declarative menus in PSML</a></li>
 			<li><a href="guide-site.html">Guide to working with a Jetspeed-2 site</a></li>
 			<li><a href="guide-l10n.html">Guide to localization with Jetspeed-2</a></li>
 			<li><a href="guide-simple-portlet.html">Guide to a very simple portlet with Jetspeed-2</a></li>
@@ -82,4 +83,4 @@
 		</subsection>		
 		</section>
 	</body>
-</document>
\ No newline at end of file
+</document>



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