Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-portlet-bridges.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-portlet-bridges.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-portlet-bridges.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-portlet-bridges.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,78 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You 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>Jetspeed Portlet Bridges</title> + <subtitle>Documentation for Apache Portals Portlet Bridges</subtitle> + <authors> + <person name="David Le Strat" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Struts Portlet Bridge"> +<p> +The Portals Bridges project provides a Portlet bridge for Struts which can be used with Jetspeed 2. +Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-struts/index.html";>Apache Portals Struts Portlet Bridge</a> +sub project documentation. +</p> +<p> +The Bridges project also provides a great Struts Portlet demo application: +<ul> + <li>The <a href="http://portals.apache.org/bridges/multiproject/jpetstore/index.html";>iBATIS JPetstore Demo Portlet</a> application</li> +</ul> +</p> +</section> +<section name="JSF Portlet Bridge"> +<p> +The Portals Bridges project provides a Portlet bridge for JSF which can be used with Jetspeed 2. +Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-jsf/index.html";>Apache Portals JSF Portlet Bridge</a> +sub project documentation. +</p> +<p> +Portals Bridges also provides a JSF portlet demo application based on MyFaces JSF implementation: +<ul> + <li>The <a href="http://portals.apache.org/bridges/multiproject/jsf-demo/index.html";>JSF Portlet Demo</a> application using Apache Portals JSF Portlet Bridge</li> +</ul> +</p> +</section> + +<section name="Velocity Portlet Bridge"> +<p> +The Portals Bridges project provides a Portlet bridge for Velocity which is used extensively within Jetspeed 2 itself. +Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-velocity/index.html";>Apache Portals Velocity Portlet Bridge</a> +sub project documentation. +</p> +</section> + +<section name="Perl Portlet Bridge"> +<p> +The Portals Bridges project provides a Portlet bridge for Perl applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-perl/index.html";>Apache Portals Perl Portlet Bridge</a> +sub project documentation. +</p> +</section> + +<section name="PHP Portlet Bridge"> +<p> +The Portals Bridges project provides a Portlet bridge for PHP applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-php/index.html";>Apache Portals PHP Portlet Bridge</a> +sub project documentation. +</p> +</section> + +</body> +</document> +
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiler.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiler.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiler.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiler.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,586 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You 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>Profiler</title> + <subtitle>Documentation for Jetspeed-2 Profiler</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Profiler Overview"> +<p> +The Jetspeed Profiler is a portal resource location rule-based engine. +The profiler locates the following kinds of portal resources: +<ul> + <li>PSML pages</li> + <li>Folders</li> + <li>Menus</li> + <li>Links</li> +</ul> +When a request is received by the portal, the profiler will compute a normalized instruction set, known +as a profile locator. The locator is then added to the request context, from which subsequent components on the +Jetspeed pipeline, most notably the Page Manager and Portal Site components, can take the profile locator +and use it to find a requested resource. For example, the Page Manager uses the locator to find a page or folder. +The Portal Site component uses the locator build the options on a menu. +</p> +<p> +The profile locator is the output from the profiler. The input is a normalized set of runtime parameters and state. +The profiler input is defined in profiling rules, and can be made of any Java class available on the pipeline. +Jetspeed comes with quite a few predefined rules for taking criteria from request parameters, HTTP headers, +security information, language and session attributes. The profiler is invoked during the Jetspeed request +processing pipeline in the profiler valve. +</p> +<p> +<img src="images/profiler-pipeline.jpg" border="1"/> +</p> +<p> +All of these runtime parameters are called the <i>profile criterion</i>, which the profiler uses to locate +portal resources. +</p> +</section> +<section name="Located Portal Resources: Pages"> +<p> +The Profiler searches over a directory tree of PSML pages trying to locate a +PSML page to be displayed. By default, this directory structure is found under WEB-INF/pages. +The pages directory can also be stored in the database. This directory structure, comprised of +portal resources (pages, folders, menus, links), is a <i>physical</i> representation of the portal site. +The Jetspeed team plans to also support <i>logical</i> views of the portal site in future releases. +</p> +<p> +Analogous to a file system, there is one physical root to the portal site. However, using the concept of <i>subsites</i>, +the Jetspeed site can support entire subsites that are not visible to other subsites, or the main site. +There are several reserved (system) directories standardized by the profiler: +<table> + <tr> + <th>Reserved Folder</th> + <th>Description</th> + </tr> + <tr> + <td>_user</td> + <td>holds all user-specific folders and pages</td> + </tr> + <tr> + <td>_role</td> + <td>holds all role-organized folders and pages</td> + </tr> + <tr> + <td>_group</td> + <td>holds all group-organized folders and pages</td> + </tr> + <tr> + <td>_subsite-root</td> + <td>contains complete subsite trees, exactly like root tree</td> + </tr> +</table> +<img src="images/pages.jpg" border="1"/> +</p> +<p>By applying profiling rules, the profiler locates pages in the portal site directory.</p> +</section> +<section name="Profiling Rules"> +<p> + +A ProfilingRule defines a list of criteria used when evaluating a request +to determine the location of a specific resource. Profiling rules are +used by the profiler to locate portal resources +based on the decoupled criteria for known portlet request data. +A rule consists of an ordered list of criteria which should be applied +in a given order. Following this rule's order, the profiling engine applies +each criteria of the rule using a less-specific algorithm until the least +specific resource criterion is considered. When all criteria are exhausted, +the rule will fail and a fallback resource will be required. +</p> +<subsection name='Rule Criteria'> +<p> +A Rule Criterion specifies one criterion in a list of profiling rule criteria. +The rule is used to build a normalized profiling locator and then +locate a portal resource based on the current user request. +Rule Criteria are templates for locating profile properties. +Criteria consist of: +<table> + <tr><td>Type</td> + <td>The type of criterion. Types are configured in the profiler spring configuraiton. + Each type maps to a <i>rule criterion resolver</i>. A resolver is a Java class which maps request input + to a normalized location instruction. Valid resolvers are provided in the table below. + </td> + </tr> + <tr> + <td>Fallback Order</td> + <td>The sequential in which to apply this criterion within the profiling rule.</td> + </tr> + <tr> + <td>Fallback Type</td> + <td>After evaluation this criterion, the rule can either continue processing the remaining + criteria, or stop processing. The fallback type determines how to continue processing. + Valid values are: + <table> + <tr> + <td>FALLBACK_CONTINUE</td> + <td>evaluate this criterion and if it fails continue to the next criterion</td> + </tr> + <tr> + <td>FALLBACK_STOP</td> + <td>evaluate this criterion and if it fails stop evaluation criteria for this rule</td> + </tr> + <tr> + <td>FALLBACK_LOOP</td> + <td>evaluate this criterion and if it fails continue evaluating</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>Name</td> + <td>The unique name (per rule) of this criterion. Upon matches, the name is mapped to the profile locator property name.</td> + </tr> + <tr> + <td>Value</td> + <td>The default value (not required) to use for this criterion when resolution fails.</td> + </tr> +</table> +More complex implementations will need to use other inputs in mapping to resources such as Cookies, IP Address Ranges, Statistical Resource Usage Analysis, or Business Rules. +</p> +</subsection> +<subsection name='Rule Criterion Resolvers'> +<p> +The table below displays all default rule criterion resolvers available with Jetspeed out of the box. +Resolvers are Java classes, implementing the interface from the Jetspeed API <i>org.apache.jetspeed.profiler.rules.RuleCriterionResolver</i>. +You may use this default set of resolvers to build your own profiling rules. Rules are currently stored in the +Jetspeed database. Portal administrators may edit the rules using an administrative portlet. In the demo system, +login as the user "admin" to see an example of the Jetspeed Profiler Administration portlet. +</p> +<p>Additionally, you may add your own resolvers to Jetspeed. You will need to create a jar file + holding your custom resolvers, and then drop them into the Jetspeed webapp's class path. Resolvers + will need to be given a unique name. This is done by modifying the profiler.xml in the Spring assembly. + See the section below on configuration to see where to add a resolver to the Spring configuration. +<table> + <tr> + <th>Resolver</th> + <th>Description</th> + </tr> + <tr> + <td>request</td> + <td>resolve by matching a request parameter by name, returning the request parameter value for a locator property taking the name of the criterion</td> + </tr> + <tr> + <td>session</td> + <td>resolve by matching a session attribute by name, returning the session attribute value for a locator property taking the name of the criterion</td> + </tr> + <tr> + <td>request.session</td> + <td>resolve by first matching a request parameter by name. If not matched, try matching a session attribute name, returning the request parameter or session attribute value for a locator property taking the name of the criterion</td> + </tr> + <tr> + <td>path</td> + <td>resolve by matching the PSML page <i>path</i> value of the current request. The path is typically the path and name of a page, such as <i>default-page</i> for a locator property named <quote>path</quote></td> + </tr> + <tr> + <td>path.session</td> + <td>resolve by matching the PSML page <i>path</i> value of the current request. The path is typically the path and name of a page, such as <i>default-page</i>. If fails to find a valid path in the request, will then look in the session for the page value. The locator property will be named <quote>path</quote></td> + </tr> + <tr> + <td>hard.coded</td> + <td>resolve to a hard.coded default value, for example, set a locator property named page to <quote>/my-account.psml</quote></td> + </tr> + <tr> + <td>user</td> + <td>resolve by matching the name of the current authenticated user. The username is mapped to a locator property named <quote>user</quote></td> + </tr> + <tr> + <td>role</td> + <td>resolve by matching all of the security roles of the current authenticated user (in the JAAS Subject of the request context) and putting them in a comma-separated list. The locator property should be named <quote>role</quote>. The role criterion is often used in combination with path criteria, to create a role-fallback rule that searches over all security roles for a given user.</td> + </tr> + <tr> + <td>group</td> + <td>resolve by matching all of the groups of the current authenticated user (in the JAAS Subject of the request context) and putting them in a comma-separated list. The locator property should be named <quote>group</quote>. The group criteion is often used in combination with path criteria, to create a group-fallback rule that searches over all security groups for a given user.</td> + </tr> + <tr> + <td>rolecombo</td> + <td>resolve by matching all of the security roles of the current authenticated user (in the JAAS Subject of the request context) and putting them in a dash-separated string, for example: (role1-role2-role3). The locator property should be named <quote>role</quote>. The role criterion is often used in combination with path criteria, to create a role-fallback rule that searches over all security roles for a given user.</td> + </tr> + <tr> + <td>mediatype</td> + <td>resolve by matching the media type (HTML,XHTML,WML...) from the request context. Sets a locator property named <quote>mediatype</quote></td> + </tr> + <tr> + <td>language</td> + <td>resolve by matching the browser's language from the request context locale (originating from the HTML headers). Sets a locator property named <quote>language</quote></td> + </tr> + <tr> + <td>country</td> + <td>resolve by matching the browser's country code from the request context locale (originating from the HTML headers). Sets a locator property named <quote>country</quote></td> + </tr> + <tr> + <td>group.role.user</td> + <td>resolve by first matching on a request parameter named <quote>group</quote>. If that fails, resolve on a request parameter named <quote>role</quote>. If that fails, resolve by matching the name of the current authenticated user. The username is mapped to a locator property named <quote>user</quote></td> + </tr> + <tr> + <td>user.attribute</td> + <td>resolve by matching a Portlet API User Attribute by name, returning the user attribute value for a locator property taking the name of the criterion</td> + </tr> + <tr> + <td>user.agent</td> + <td>resolve by matching the browser's (client) user agent from the request context device capabilities (originating from the HTML headers)</td> + </tr> + <tr> + <td>hostname</td> + <td>resolve by matching the host name from the server name in the request, returning the host name</td> + </tr> + <tr> + <td>domain</td> + <td>resolve by matching the domain from the server name in the request, returning the domain</td> + </tr> + <tr> + <td>navigation</td> + <td>A directive to changes the current navigation path during a profile location resolution performed by the page manager. The value can be the location of a folder, for example <quote>/pages/freecontent</quote></td> + </tr> +</table> +<i>Note that all criteria will fall back to the default value when no match is made. Locator property expects a criterion named <quote>navigation</quote></i> +</p> +</subsection> +<subsection name='Default Rules'> +<p> +Several rules are provided by default with the Jetspeed system. +The rules in the table below display the criterion in a most-specific to least-specific ordering. +</p> +<table> + <tr> + <th>Rule</th> + <th>Description</th> + </tr> + <tr> + <td>j1</td> + <td> + <p>Implements the Jetspeed-1 hard-coded profiler fallback algorithm, resolving in a most-specific to least-specific algorithm:</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>country</td> + <td>country</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>language</td> + <td>language</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>mediatype</td> + <td>mediatype</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>group.role.user</td> + <td>user|group|role</td> + <td></td> + <td>stop</td> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>role-fallback</td> + <td> + <p>A role based fallback algorithm, trying to find the most-specific resource by searching over all security roles for the current authenticated user.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>group-fallback</td> + <td> + <p>A group based fallback algorithm, trying to find the most-specific resource by searching over all security groups for the current authenticated user.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + <tr> + <td>group</td> + <td>group</td> + <td></td> + <td>continue</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>j2</td> + <td> + <p>The default profiling rule for users and mediatype minus language and country.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>mediatype</td> + <td>mediatype</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>group.role.user</td> + <td>user|group|role</td> + <td></td> + <td>stop</td> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>security</td> + <td> + <p>The security profiling rule needed to force credential change requirements.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>hard.coded</td> + <td>page</td> + <td>/my-account.psml</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>path</td> + <td> + <p>Only criterion applied is the path portion of the portal URL.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path</td> + <td>page</td> + <td>/</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>user-role-fallback</td> + <td> + <p>Rule will first look for the resource in the user's home folder. If not found there, a role based fallback algorithm is applied, trying to find the most-specific resource by searching over all security roles for the current authenticated user.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>continue</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>/</td> + <td>loop</td> + </tr> + <tr> + <td>user</td> + <td>user</td> + <td></td> + <td>continue</td> + </tr> + + </table> + </td> + </tr> + <tr> + <td>user-rolecombo-fallback</td> + <td> + <p>Rule will first look for the resource in the user's home folder. If not found there, a role based fallback algorithm is applied, trying to find the most-specific resource by searching over all security roles for the current authenticated user. Creates a locater property named <quote>role</quote> that is the concatenation of all roles into one string, such as <i>role1-role2-role3</i>. This combined string is used as the role name in the locator.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>continue</td> + </tr> + <tr> + <td>rolecombo</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>/</td> + <td>loop</td> + </tr> + <tr> + <td>user</td> + <td>user</td> + <td></td> + <td>continue</td> + </tr> + + </table> + </td> + </tr> + <tr> + <td>subsite-role-fallback-home</td> + <td> + <p>A rule based on role fallback algorithm with specified subsite and home page</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path</td> + <td>path</td> + <td>subsite-default-page</td> + <td>stop</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>subsite-root</td> + <td>loop</td> + </tr> + </table> + </td> + </tr> + + </table> +</subsection> +</section> +<section name="Profile Locators"> +<p> +Profile Locators are used to locate profiled portal resources such as +pages, folders, menus and links. A locator contains a collection of properties +(name value pairs) describing the actual resource to be located. +</p> +<img src="images/parameter-resolution.jpg" border="1"/> +<p> +The profiler takes runtime information as input, generalized into +generalized profile locators that are passed on to the page manager to locate a page or menu. +The profile locators are normalized and not coupled to the profiler or page manager implementation. +</p> +<img src="images/parameter-resolution-2.jpg" border="1"/> +</section> +<section name='Principal Rules'> +<p>Each user principal can be mapped to specific profiling rule. This association is stored in the Jetspeed database. +The association is three-way, combining the PRINCIPAL + PROFILING RULE + LOCATOR, where the locator values +currently supported are <quote>menu</quote> or <quote>page</quote>. Thus we can have two different profiling rules +applied for locating resources per user: locate pages and locate menus. When the profiler attempts to locate a page +for the current user, it will apply the profiling rule for the given user. The Jetspeed User Administration portlet +has a tab for editing user profile information: +</p> +<p> +<!-- +<img src="images/user-profile-locator.jpg" border="1"/> + --> +</p> +<p> +Often, profiling rules are determined and then associated by portal-specific logic during user registration (or self-registration). +A Jetspeed-specific self-registration portlet could handle the registration process of adding a user to the system, granting roles, +setting user attributes, and assigning the profiling rule for the user. +</p> +</section> + + +</body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiling-ip.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiling-ip.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiling-ip.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-profiling-ip.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,79 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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 Profiling IP Addresses</title> + <subtitle>Documentation for Using the ip-address Profiler rule</subtitle> + <authors> + <person name="Philip Mark Donaghy" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Guide to Profiling IP Addresses"> + <p> + Jetspeed has a built in mechanism to serve custom content + to a specific IP address. This feature uses the Profiler + to negociate pages based on the requesting clients IP address. + </p> + <subsection name="1. The Rule"> + <p> + The rule is identified by the key <b>ip-address</b>. There is one criterion + called <b>ip</b> resolved using the IP Criterion Resolver. This class implements + the resolve method of the Rule Criterion Resolver in order to obtain the IP address + from the request. + </p> + <source> + public String resolve(RequestContext context, RuleCriterion criterion) + { + // look for override + String value = super.resolve(context, criterion); + if (value != null) { return value.toLowerCase(); } + + // Note IP addresses can vary depending on the client + // Konqueror 3.4.2 returns IPv6 e.g. 0:0:0:0:0:0:0:1 + // Firefox 1.0.7 returns IPv4 e.g. 127.0.0.1 + // This is the value used to resolve pages in the _ip directory + // TODO create an option to convert all IPv4 addresses to IPv6 + return context.getRequest().getRemoteAddr(); + } + </source> + </subsection> + <subsection name="2. The Page Locator"> + <p> + Users with this profile rule set to the <b>page</b> locator are served pages from the _ip + directory of the psml site tree. Example, if a request is made for + http://www.apache.org/jetspeed/portal/default-page.psml from 81.29.65.234 + then the rule will match /WEB-INF/pages/_ip/81.29.65.234/default-page.psml before + falling back to /WEB-INF/pages/default-page.psml + </p> + </subsection> + <subsection name="3. Example Use Cases"> + <p> + You have a location in Tokyo serving content specific to that + location. Your kiosk is configured with a fixed IP address. The annonymous + user (guest by default) uses this profile rule. Anyone using + the portal from that kiosk would be served content from the _ip directory. + </p> + <p> + It could also be used to profile robots. Or keep out unwanted visitors. And can be the basis for + profiling IP ranges or IP prefixes, networks and subnetworks, and geographic locations. + </p> + </subsection> + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml-xsd.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml-xsd.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml-xsd.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml-xsd.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,56 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You 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 PSML XML Schema</title> + <subtitle>Guide to PSML XML Schema</subtitle> + <authors> + <person name="Randy Watler" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="PSML XML Schema"> +<p> +The following PSML XML Schema further define the XML documents defined in these guides: +<ul> + <li><a href="guide-psml.html">Guide to PSML</a></li> + <li><a href="../deployguide/guide-security-declarative-psml.html">Guide to declarative security through PSML</a></li> + <li><a href="../deployguide/guide-menus-declarative-psml.html">Guide to declarative menus in PSML</a></li> +</ul> +</p> +<p> +PSML XML Schema definitions by document type: +<ul> + <li><a href="../2.2/schemas/psml.xsd">Page, (*.psml)</a></li> + <li><a href="../2.2/schemas/folder-metadata.xsd">Folder Metadata, (folder.metadata)</a></li> + <li><a href="../2.2/schemas/link.xsd">Link, (*.link)</a></li> + <li><a href="../2.2/schemas/page-security.xsd">Page Security, (page.security)</a></li> + <li><a href="../2.2/schemas/dpsml.xsd">Dynamic Page, (*.dpsml)</a></li> + <li><a href="../2.2/schemas/tpsml.xsd">Template Page, (*.tpsml)</a></li> + <li><a href="../2.2/schemas/fpsml.xsd">Fragment Definition, (*.fpsml)</a></li> +</ul> +</p> +<p> +Additional PSML XML Schema definitions: +<ul> + <li><a href="../2.2/schemas/psml-core.xsd">Common Core PSML Schema Definitions</a></li> +</ul> +</p> +</section> +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/guide-psml.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,983 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You 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>PSML</title> + <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> + <ul> + <li><a href="#Layout_Fragments">Layout Fragments</a></li> + <li><a href="#Portlet_Fragments">Portlet Fragments</a></li> + <li><a href="#Fragment_References">Fragment References</a></li> + <li><a href="#Fragment_Properties">Fragment Properties</a></li> + <li><a href="#Preferences">Portlet Preferences</a></li> + </ul> + <li><a href="#Dynamic_Page">Dynamic Page</a></li> + <li><a href="#Page_Template">Page Template</a></li> + <ul> + <li><a href="#Page_Fragment">Page Fragment</a></li> + </ul> + <li><a href="#Fragment_Definition">Fragment Definition</a></li> + <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_Defaults">Defaults</a></li> + <li><a href="#PSML_Security_Constraints">Security Constraints</a></li> + <li><a href="#PSML_Menus">Menus</a></li> + <li><a href="guide-psml-xsd.html">PSML Document XML Schemas</a></li> +</ul> + +<p> +PSML is an acronym for Portal Structure Markup Language. It was created to allow content structure and abstraction within Jetspeed. +PSML defines how portlets are aggregated, laid out, and decorated on a portal page. Note that page layout is not a part of the Java +Portlet Standard API. Thus PSML is a Jetspeed-specific implementation. Also note that PSML in Jetspeed-2 is different from PSML in +Jetspeed-1. This document can be used as a reference guide to the elements of a PSML resource. +</p> +<p> +PSML files capture portal site information related to pages, folders, links, and global security constraints for the portal. PSML +elements can be defined in separate documents arranged in a hierarchy of directories in the file system. The folder structure of the +PSML documents mirrors the portal URL space. Typically, the PSML root directory is accessed as a resource at /WEB-INF/pages within +the jetspeed web application. It is also possible to store PSML definitions in the database; the folder and document arrangement +of the PSML hierarchy is maintained there as well. +</p> +<p> +The following PSML documents/elements are defined below: +</p> +<table> + <tr> + <th>PSML Element</th> + <th>Document</th> + <th>Description</th> + </tr> + <tr> + <td><a href="#Page">Page</a></td> + <td>*.psml</td> + <td> + Defines a single portal page within the portal at a specific portal URL. Page definitions + will be augmented by a page template, if found, in current or parent folders. Pages are + primarily composed of fragments which are mapped to individual portlets. Pages can also + include fragment references to separately defined fragment references. + </td> + </tr> + <tr> + <td><a href="#Dynamic_Page">Dynamic Page</a></td> + <td>*.dpsml</td> + <td> + Defines a reusable portal page used with matching content URLs within the portal. Like page + definitions, dynamic pages will be augmented by page templates and are made up of fragments + and fragment references. Dynamic pages are matched to portal content page requests by URL + and content type mappings: matching pages are selected from current or parent folders. Only + one dynamic page per content type should be defined per folder. + </td> + </tr> + <tr> + <td><a href="#Page_Template">Page Template</a></td> + <td>*.tpsml</td> + <td> + Defines fragment and fragment references that are to be included in all concrete and dynamic + pages. An individual page template is selected from within the current page or parent + folders. A special page fragment is used to define where in the page template current page + fragments are inserted. Only one page template can be defined per folder. + </td> + </tr> + <tr> + <td><a href="#Fragment_Definition">Fragment Definition</a></td> + <td>*.fpsml</td> + <td> + </td> + Externally defines fragments to be referenced from multiple pages or page templates. + Fragment references are used to refer to fragment definitions. Fragment definitions cannot + contain references to other fragment definitions. Only one fragment definition per fragment + id can be defined per folder. + </tr> + <tr> + <td><a href="#Folder">Folder</a></td> + <td>folder.metadata</td> + <td> + Defines metadata associated with the file system folder or URL path. As one would expect, + only one set of metadata information can be associated with a folder. With the exception of + content URLs, the hierarchical structure defined by folders and pages defines the portal + URL space. + </td> + </tr> + <tr> + <td><a href="#Link">Link</a></td> + <td>*.link</td> + <td> + Defines URL links to external or local resources used in portal menus. + </td> + </tr> + <tr> + <td><a href="#Global_Page_Security">Global Page Security</a></td> + <td>page.security</td> + <td> + Defines global securuty constraint definitions and defaults for all portal pages and folders. + </td> + </tr> +</table> +<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> + <!-- 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="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 name="row" value="0"/> + </fragment> + <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> + <property name="row" value="1"/> + <property name="sizes" value="33%,66%"/> + <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet"> + <property name="row" value="0"/> + <property name="column" value="0"/> + </fragment> + <fragment id="100171" type="portlet" name="demo::UserInfoTest"> + <property name="row" value="0"/> + <property 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 for portal site <a href="#Dynamic_Page">dynamic page</a>, (*.dpsml): +</p> +<source><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<dynamic-page content-type="*" inheritable="true"> + <title>Jetspeed 2 Portals Content</title> + <fragment id="default-content-layout" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> + <property name="sizes" value="80%,20%" /> + <fragment id="default-content-dynamic-content" type="portlet" name="j2-admin::DynamicWebContentPortlet" decorator="gray-gradient-noborder"> + <property name="row" value="0" /> + <property name="column" value="0" /> + <preference name="SRC"> + <value>http://portals.apache.org/</value> + </preference> + <preference name="PORTALPATH"> + <value>/content/</value> + </preference> + </fragment> + <fragment-reference id="default-content-wp-reference" refid="wp-definition"> + <property name="row" value="0"/> + <property name="column" value="1"/> + </fragment-reference> + </fragment> +</dynamic-page> +]]></source> +<p> +Here is an example PSML file for portal site <a href="#Page_Template">page template</a>, (*.tpsml): +</p> +<source><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<page-template> + <title>Portal Template</title> + <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + <page-fragment id="template-top-page-template"> + <property name="row" value="0"/> + </page-fragment> + <fragment id="template-top-login" type="portlet" name="j2-admin::LoginPortlet"> + <property name="row" value="1"/> + </fragment> + <fragment-reference id="template-top-wp-reference" refid="wp-definition"> + <property name="row" value="2"/> + </fragment-reference> + </fragment> +</page-template> +]]></source> +<p> +Here is an example PSML file for portal site <a href="#Fragment_Definition">fragment definition</a>, (*.fpsml): +</p> +<source><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<fragment-definition> + <title>Current Weather</title> + <fragment id="wp-definition" type="portlet" name="demo::WeatherPortlet"/> +</fragment-definition> +]]></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> + + <!-- default page decorations --> + <defaults layout-decorator="tigris" portlet-decorator="tigris"/> + + <!-- 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 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>Attribute</th> + <th>Description</th> + </tr> + <tr> + <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>version</td> + <td>A general purpose version tracking attribute. Not currently used by Jetspeed2.</td> + </tr> +</table> +<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="#PSML_Defaults">defaults?</a></td> + <td>Specifies the decorations for the page and its fragments. Optional defaults can be inherited from parent folders, but layout decorations are required for each page either specified explicitly or in a parent folder.</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='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>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>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-name:portlet-name' where portlet-app-name is the web context name, 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 name="row" value="0"/> + </fragment> + <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> + <property name="row" value="1"/> + <property name="sizes" value="33%,66%"/> + <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet"> + <property name="row" value="0"/> + <property name="column" value="0"/> + </fragment> + <fragment id="100171" type="portlet" name="demo::UserInfoTest"> + <property name="row" value="0"/> + <property name="column" value="1"/> + </fragment> + </fragment> + </fragment> + ... +</page> +]]></source> +</section> + +<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>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>type</td> + <td>This required attribute must be set to 'portlet' for all portlet fragments.</td> + </tr> + <tr> + <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="#PSML_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 name="row" value="0"/> + </fragment> + ... +</fragment> +]]></source> +</section> +<section name='Fragment References'> +<p> +The <fragment-reference> element is used to insert an external <a href="#Fragment_Definition">fragment definition</a> fragment hierarchy into the containing <a href="#Page">page</a>, <a href="#Dynamic_Page">dynamic page</a> or <a href="#Page_Template">page template</a>. Fragment references cannot appear in <a href="#Fragment_Definition">fragment definitions</a>. The referenced fragment may be either a <a href="#Layout_Fragments">layout fragment</a> or <a href="#Portlet_Fragments">portlet fragment</a>. Attributes and child elements of the fragment reference element override the settings in the referenced fragment. The fragment reference element supports one additional attribute not supported by <a href="#Layout_Fragments">layout fragments</a> or <a href="#Portlet_Fragments">portlet fragments</a>: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>refid</td> + <td>Unique identifier of the root fragment in the <a href="#Fragment_Definition">fragment definition</a> to insert.</td> + </tr> +</table> +<p> +The following <a href="#Layout_Fragments">layout fragment</a> and <a href="#Portlet_Fragments">portlet fragment</a> attributes and child elements are not supported by the fragment reference element: name, type, fragment, fragment-reference, and page-fragment. +</p> +<p>Example:</p> +<source><![CDATA[ +<fragment-reference id="template-top-wp-reference" refid="wp-definition"> + <property name="row" value="2"/> +</fragment-reference> +]]></source> +</section> +<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>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>name</td> + <td>The fragment property name. Jetspeed2 layout portlets support the 'row', 'column' and 'sizes' properties.</td> + </tr> + <tr> + <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>Examples:</p> +<source><![CDATA[ +<fragment id="100876" type="portlet" name="j2-admin::LoginPortlet"> + ... + <property name="row" value="2"/> + <property name="column" value="1"/> + ... +</fragment> +]]></source> +<source><![CDATA[ +<fragment id="103456" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> + ... + <property name="sizes" value="33%,66%"/> + ... +</fragment> +]]></source> +</section> +<section name='Preferences'> +<p> +The <a href="#Portlet_Fragments">portlet fragment</a> <preference> elements allow for the defining of default +portlet preference values. +This provides an easier avenue for the setting of default portlet preferences for a portlet +instance on a page without having to duplicate portlet definitions 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</th> + <th>Description</th> + </tr> + <tr> + <td>name</td> + <td>The name of the preference.</td> + </tr> + <tr> + <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> +<section name='Dynamic Page'> +<p> +The <dynamic-page> element defines a reusable page that is used to display any matching portal content request URLs in the portal site. Individual dynamic pages are selected by the portal site mappings of the portal URL paths and content type. Apart from this matching process, content pages are identical to concrete <a href="#Page">page</a> definitions. There are two attributes supported by the dynamic page element in addition to the page element attributes and child elements: +</p> +<table> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + <tr> + <td>content-type</td> + <td>The content type string that identifies the content this reusable page is to be used to display. The wildcard type, '*', can be used to identify a dynamic page that should be used by all content types or as a fallback for unmatched content request URLs.</td> + </tr> + <tr> + <td>inheritable</td> + <td>Boolean indicating whether or not other more specific portal content URLs can utilize this page definition.</td> + </tr> +</table> +<p>Example:</p> +<source><![CDATA[ +<dynamic-page content-type="doc" inheritable="false"> + ... + <fragment id="default-content-layout" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> + ... + </fragment> + ... +</dynamic-page> +]]></source> +</section> +<section name='Page Template'> +<p> +The <page-template> element specifies a template page that defines top level fragment and fragment references to be included in all <a href="#Page">concrete pages</a> and <a href="#Dynamic_Page">dynamic pages</a> in the portal site. A required single <a href="#Page_Fragment">page fragment</a> must be part of the page template fragment hierarchy. When pages are merged into the template, this fragment is replaced with the root fragment of the displayed <a href="#Page">concrete page</a> and <a href="#Dynamic_Page">dynamic page</a>. With the exception of the <a href="#Page_Fragment">page fragment</a>, the page template element supports all <a href="#Page">page</a> attributes and child elements identically. +</p> +<p>Example:</p> +<source><![CDATA[ +<page-template> + ... + <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + ... + <page-fragment id="template-top-page-template"> + <property name="row" value="1"/> + </page-fragment> + ... + </fragment> + ... +</page-template> +]]></source> +</section> +<section name='Page Fragment'> +<p> +The <page-fragment> element appears exactly once in each <a href="#Page_Template">page template</a> definition. When the page template is merged with the displayed <a href="#Page">concrete page</a> or <a href="#Dynamic_Page">dynamic page</a>, all attributes and child elements override the same settings in the root fragment of the referenced page. No additional <a href="#Layout_Fragments">layout fragment</a> attributes are supported by the page fragment element. The following <a href="#Layout_Fragments">layout fragment</a> attributes and child elements are not supported by the page fragment element: name, type, fragment, fragment-reference, and page-fragment. +</p> +<p>Example:</p> +<source><![CDATA[ +<page-template> + ... + <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn"> + ... + <page-fragment id="template-top-page-template"> + <property name="row" value="1"/> + </page-fragment> + ... + </fragment> + ... +</page-template> +]]></source> +</section> +<section name='Fragment Definition'> +<p> +The <fragment-definition> element defines a hierarchy of fragments that can be referenced from and merged into in multiple <a href="#Page">pages</a>, <a href="#Dynamic_Page">dynamic pages</a>, or <a href="#Page_Template">page templates</a>. The fragment definition is referenced by the id of the contained root fragment and the fragment hierarchy is merged into the displayed page where referenced. All attributes and child elements of the fragment definition, (with the exception of the root fragment), are not used within the displayed pages. Consequently, only <a href="#Page">page</a> elements and attributes used to identify, describe, or secure the fragment definition itself are supported: id, security-constraints, version, title, short-title and metadata. Only <a href="#Layout_Fragments">layout fragments</a> and <a href="#Layout_Fragments">portlet fragments</a> can appear in the fragment hierarchy, but unlike pages, the root fragment need not be a layout. +</p> +<p>Example:</p> +<source><![CDATA[ +<fragment-definition> + <title>Current Weather</title> + <fragment id="wp-definition" type="portlet" name="demo::WeatherPortlet"/> +</fragment-definition> +]]></source> +</section> +<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><a href="#PSML_Defaults">defaults?</a></td> + <td>Optionally specifies the decorations for the folder or subfolder pages and their fragments. Layout decorations are required for each page either specified explicitly in the individual pages or in a parent folder.</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 three 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> + <tr> + <td>skin</td> + <td>A general purpose decorator attribute that can be referenced in the portlet decorators to control link presentation. <a href="#Menus">Menu</a> option elements for the link will adopt this skin value if not otherwise specified. 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='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. +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 Defaults'> +<p> +The <a href="#Page">page</a> and <a href="#Folder">folder</a> <defaults> element defines the default layout +decorator and default portlet decorator. The default layout decorator is applied to all top level 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. Defaults may be inherited from parent folder default elements. There are three valid +attributes on the defaults element: +</p> +<table> + <tr> + <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, but may be inherited from a parent folder..</td> + </tr> + <tr> + <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. This attribute too may be inherited from parent folders.</td> + </tr> + <tr> + <td>skin</td> + <td>A general purpose decorator attribute that can be referenced in the decorators to control page and folder presentation. <a href="#Menus">Menu</a> option elements for the page and folder will adopt this skin value if not otherwise specified. 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="PSML Security Constraints"> +<p> +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='../deployguide/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='../deployguide/guide-menus-declarative-psml.html'>Declarative Menus Guide</a> +</p> +</section> + +</body> +</document> +
