Esup Lecture Portlet - Configuration Guide


Auteur : Bourges Raymond - Bouteille Gwénaëlle - Repain Vincent (University of Rennes 1)

Configuration

Technical configuration


Adapt to your environment these configuration files:

Content configuration


To adapt to your environment, edit these configuration files:

esup-lecture.xml

These file contains some technical parameters (guestUser, ttl) and describe the contents displayed (contexts, category profiles). Here is the structure of this file (for more information, look at dtd esup-lecture.dtd):

Element channelConfig

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" >
<channelConfig>

  <!-- guestUser definition -->
  <guestUser> ... </guestUser>

  <!-- ttl definition -->
  <ttl> ... </ttl>

  <!-- contexts definition -->
  <context> ... </context>
  <context> ... </context>
  ...

  <!-- category profile definition -->
  <categoryProfile> ... </categoryProfile>
  <categoryProfile> ... </categoryProfile>
  ...

</channelConfig>

channelConfig is the root element, it is of course mandatory and all others elements must be described under it.

Element guestUser

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" >
<channelConfig>
  <guestUser>guest</guestUser>

guestUser is an optional property. Default value is "guest".
If the current connected user name equals guestUser property, then all controls used for personalisation (change tree size buttons, mark an item as read button, edit button, etc.) are hidden.
This is used in Portlet mode when esup-lecture is used in a portal unauthenticated view.

Element ttl

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" >
<channelConfig>
  <ttl>0</ttl>

ttl is an optional property. Default value is 0 (zero). If not used, the configTtl property of bean channel (see properties/domain/domain.xml) is used instead.

It tunes the time in seconds the two configuration files (esup-lecture.xml and mappings.xml) will stay in cache, that is, the time between two reloadings of theses files. This allow to change the configuration files without reloading the portlet. A value of zero means no reloading.

Element context

<context
   name = "Démonstration Esup-Lecture"
   id = "default">
   <description>Context de démo</description>
   <refCategoryProfile refId="demo1"/>
   <refCategoryProfile refId="demo2"/>
   ...
</context>

You can use a specific context by configuring your portlet with a portlet preference. This portlet preference must have a name "context" and a value equals to the id you want for this portlet. If you don't define any context preference for your portlet then context with id "default" is used. With this mechanism you can define many channels with many contexts definitions in your portal environment with just one instance of the portlet.

Before uPortal 2.5.4, because of a bug (http://www.ja-sig.org/issues/browse/UP-1040) you can't use this feature.

A context has the following attributes :

A context may have also the following elements :

Element categoryProfile

<categoryProfile   name="Categorie de démo"
   id="demo1"
   urlCategory="http://partages.univ-rennes1.fr/files/partages/Services/CRI/SI/conf_lecture_gwe_ray/demo1.xml"
   trustCategory="no"
   access="public"
   ttl = "3600"
   timeout = "3000">
   <visibility> ... </visibility>
</categoryProfile>

A category profile have the following attributes :

Element visibility

<visibility>
   <allowed/>
   <autoSubscribed/>
   <obliged>
      <group name="local.0"/>
      <group .../>
      ...
      <regular attribute="sn" value="user" />
      <regular .../>
      ...
      <regex attribute="isMemberOf" pattern="[ a-zA-Z0-9:]*:Eleves" />

      <regex .../>
      ...
 </obliged>
</visibility>

In this element, you define 3 groups of visibility;

A user is in a visibility group by two ways :

<category>.xml

described by dtd category.dtd, provided by remote server, requested by urlCategory of esup-lecture.xml

element category

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE category SYSTEM "category.dtd">
<category name="Différents RSS">
  <description>Très belle description !</description>
  <sourceProfiles>
    <sourceProfile> ... </sourceProfiles>
    <sourceProfile> ... </sourceProfiles>
    ...
  </sourceProfiles>
  <visibility> ... </visibility>
</category>

A category has a name and a description (displayed on interface), and

element sourceProfile

<sourceProfile
  id="un" access="public" name="Incidents techniques Rennes 1"
  specificUserContent="no" url="http://info.cri.univ-rennes1.fr/rss/rss.php">
  <visibility> ... </visibility>

</sourceProfile>

A source profile has an id, a name (displayed on interface) and :

mappings.xml

mappings.xml: it describes a list of mappings used to parse xml stream of a source in a html content (see mappings.dtd) :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mappings SYSTEM "mappings.dtd" >
<mappings>
  <mapping> ... </mapping>
  <mapping> ... </mapping>
  ...
</mappings>

A source is composed of a list of items that will be parsed to be displayed in web page. A mapping is used to define a xsltFile to apply on items selected by itemXPath. Sometimes, to define itemXPath, namespaces definition are required.

Here is an example of mapping:

<mapping
  sourceURL="http://info.cri.univ-rennes1.fr/rss/rss.php"
  xsltFile="http://partages.univ-rennes1.fr/files/partages/Services/CRI/SI/conf_lecture_gwe_ray/stylesheet01.xsl"
  itemXPath="/rdf:RDF/default:item">
  <XPathNameSpace prefix="rdf" uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/>
  <XPathNameSpace prefix="default" uri="http://purl.org/rss/1.0/" />
</mapping>

Explanations:

Priority to find xslt informations on key entry of a mapping are : sourceURL, DTD, xmlType, xmlns and finally rootElement.

portlet.xml

All portal user attributes used by portlet must be declared in the webapp/WEB-INF/portlet.xml, here is an example:

<user-attribute>
  <description>the username of the portal user</description>
  <name>username</name>
</user-attribute>
<user-attribute>
  <description>the displayName of the portal user</description>
  <name>displayName</name>
</user-attribute>
<user-attribute>
  <description>the sn of the portal user</description>
  <name>sn</name>
</user-attribute>

auth.xlm

This file (properties/auth.xml) is used to define auth mecanism. For example when using CAS in servlet mode or a portal in portlet mode:

<bean id="authenticationService"
  class="org.esupportail.commons.services.authentication.PortalOrCasFilterAuthenticator">
  <description>The name of the Portal attribute that holds the uid of users, as set in portlet.xml.</description>
  <property name="uidPortalAttribute" value="uid" />
</bean>