ate 2005/01/14 05:04:07
Modified: xdocs navigation.xml
Added: xdocs/images definingUserAttributes.jpg
usingUserAttributes.jpg
xdocs user-attributes.xml
Log:
User Attributes Usage documentation added
Revision Changes Path
1.1
jakarta-jetspeed-2/xdocs/images/definingUserAttributes.jpg
<<Binary file>>
1.1 jakarta-jetspeed-2/xdocs/images/usingUserAttributes.jpg
<<Binary file>>
1.5 +1 -0 jakarta-jetspeed-2/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-jetspeed-2/xdocs/navigation.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- navigation.xml 16 Nov 2004 22:50:54 -0000 1.4
+++ navigation.xml 14 Jan 2005 13:04:07 -0000 1.5
@@ -28,6 +28,7 @@
<item name="Getting Started" href="getting-started.html"/>
<item name="Database" href="database.html"/>
<item name="Localization" href="l10n-guide.html"/>
+ <item name="User Attributes" href="user-attributes.html"/>
<item name="Goals" href="js2-goals.html"/>
<item name="Tasks" href="tasks.html"/>
<item name="Sub Projects" href="projects-overview.html"/>
1.1 jakarta-jetspeed-2/xdocs/user-attributes.xml
Index: user-attributes.xml
===================================================================
<?xml version="1.0"?>
<!--
Copyright 2004 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>Defining User Attributes</title>
<subtitle>PLT.17 User Information Configuration</subtitle>
<authors>
<person name="Ate Douma" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
<body>
<section name="Defining User Attributes">
<p>
The Portlet Specification defines how Portlet Applications can use
User Attributes.<br/>
The attributes must be defined in the portlet.xml like (see
PLT.17.1):</p>
<source><![CDATA[
<portlet-app version="1.0"
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd";>
<user-attribute>
<description>User Given Name</description>
<name>user.name.given</name>
</user-attribute>
<user-attribute>
<description>User Last Name</description>
<name>user.name.family</name>
</user-attribute>
<user-attribute>
<description>User eMail</description>
<name>user.home-info.online.email</name>
</user-attribute>
...
</portlet-app>]]></source>
<p>
Once attributes are defined like this, a portlet can access the
current values for the logged on
user as an unmodifiable Map from the PortletRequest using the
USER_INFO constant defined in the
PortletRequest interface (see PLT.17.2):</p>
<source>
Map userInfo = (Map)request.getAttribute(PortletRequest.USER_INFO);
String givenName = (userInfo!=null) ?
(String)userInfo.get("user.name.given") : "";
String lastName = (userInfo!=null) ?
(String)userInfo.get("user.name.family") : "";
String email = (userInfo!=null) ?
(String)userInfo.get("user.home-info.online.email") : "";</source>
<p>
What is not defined by the Portlet Specification is <em>how</em> the
Portal
must map the defined User Attributes to concrete attributes of a
user.</p>
</section>
<section name="Mapping User Attributes">
<p>
Jetspeed-2 provides a very flexible way to define concrete User
attributes and defining access to them.</p>
<p>
Concrete User attributes are stored using User Preferences for which
Jetspeed-2 provides its own database
back end for storage (which is customizable by the way like almost
any component of Jetspeed-2)<br/>
The concrete User attributes are stored under a specific node in the
User preferences and can contain
any named attribute at will.<br/>
These concrete User attributes can be mapped to the defined User
Attributes in the portlet.xml in two ways:
<ol>
<li>
Using an exact match of attribute names
</li>
<li>
Using a custom mapping definition in a jetspeed-portlet.xml
</li>
</ol>
</p>
<subsection name="Custom User Attribute Mapping">
<p>
If you write new Portlet Applications with Jetspeed-2 as target
Portal, defining User Attributes which
match the concrete User attributes in the Portal usually will be
quite straightforward<br/>
But, if you have an existing Portlet Application which you want to
deploy on Jetspeed-2, there might
be a mismatch between the attribute names needed by the Portlet
Application and the
concrete attribute names as stored in the Jetspeed-2 User
Preferences.</p>
<p>
<em>
Note: The Portlet Specification defines a set of attribute names
which are recommended to be used
in Appendix PLT.D.<br/>
Portlet Applications using these attribute names and Portals
storing the concrete User attributes
also using these names won't need any custom attribute mapping as
will be described below.<br/>
Although Jetspeed-2 allows a fully free definition of the
concrete User attributes,
it is recommended to use these predefined attributes names as
much as possible.</em></p>
<p>
The jetspeed-portlet.xml allows jetspeed specific configurations
and customizations to be specified.<br/>
This deployment document isn't required, but will be processed if
found within the WEB-INF folder of a
Portlet Application war.<br/>
Jetspeed specific configurations must be defined using the
"http://portals.apache.org/jetspeed"; namespace.</p>
<p>
User attribute mapping is defined using an "user-attribute-ref"
element containing a "name" element defining
the custom user attribute name and a "name-link" element defining
the concrete attribute name to which it
is mapped:</p>
<source><![CDATA[
<portlet-app version="1.0"
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd";
xmlns:js="http://portals.apache.org/jetspeed";>
<js:user-attribute-ref>
<js:name>user-name-given</js:name>
<js:name-link>user.name.given</js:name-link>
</js:user-attribute>
<js:user-attribute-ref>
<js:name>user-name-family</js:name>
<js:name-link>user.name.family</js:name-link>
</js:user-attribute>
...
</portlet-app>]]></source>
<p>
Using the above custom mapping as an example, the Portlet can now
access the user attributes as follows:</p>
<source>
Map userInfo = (Map)request.getAttribute(PortletRequest.USER_INFO);
String givenName = (userInfo!=null) ?
(String)userInfo.get("user-name-given") : "";
String lastName = (userInfo!=null) ?
(String)userInfo.get("user-name-family") : "";
String email = (userInfo!=null) ?
(String)userInfo.get("user.home-info.online.email") : "";</source>
<p>
Note that the email attribute for which no custom mapping was
defined still can be access using
exact name matching (provided the concrete attribute is defined for
the logged on user).</p>
</subsection>
</section>
<section name="Defining User Attributes in Jetspeed-2">
<p>
Jetspeed-2 is provided with several Administrative Portlets,
including for User Management.<br/>
Using the User Management Portlets, it is very easy to define or
modify concrete attributes for a user:</p>
<img src="images/definingUserAttributes.jpg"/>
<p>
The User Info Test demo Portlet, default deployed in Jetspeed-2 and
displayed on the start page, uses
the above example User Attribute definitions and displays the values
for the logged on user (also showing that
these can be accessed from both the PortletRequest as well as the
HttpServletRequest from within a servlet):</p>
<img src="images/usingUserAttributes.jpg"/>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
