cvs commit: jakarta-jetspeed-2/xdocs user-attributes.xml navigation.xml

[at...@apache.org]

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="ate@douma.nu"/>
      </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: jetspeed-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: jetspeed-dev-help@jakarta.apache.org