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="[EMAIL PROTECTED]"/>
+ </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="[EMAIL PROTECTED]"/>
+ <person name="Randy Watler" email="[EMAIL PROTECTED]"/>
</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 <page> 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 <page> 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> <defaults> 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 <fragment> 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 <fragment> 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 <fragment> 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 <fragment> 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> <property> 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 <preference> 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 <preference> elements.
- <br/><br/>
- Preference precedence: User Defined > Fragment Defined > portlet.xml
Defined.
+The <a href="#Portlet_Fragments">portlet fragment</a> <preference>
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 <preference> 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><value></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 <preference> 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 <folder> 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 <folder> 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 <link> 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 <link> 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 <page-security> 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 <page-security> 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> <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.
+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 <security-constraints>, <security-constraints-def>, and
<global-security-constraints-ref> 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 <menu> 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="[EMAIL PROTECTED]"/>
+ <person name="Randy Watler" email="[EMAIL PROTECTED]"/>
</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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
