Esup Lecture Portlet - Installation Guide

Dates de modification
Revision 1.0	2006-11-29	First version of the installation Guide
Revision 1.1	2007-01-12	installation Guide form Esup Lecture Portlet V0.6

Download esup-lecture-<version>.zip from the project site
Unzip the file somewhere on a working directory

Note

To configure this application you have to adapt some configuration files. Every time you will find a <fileName>-example.<extension> example file that you can copy to <fileName>.<extension> before adapting.
Adapt build.properties
Adapt properties/exceptionHandling/exceptionHandling.xml for exception handling configuration.

Note

By default, exception reports are also sent to an archived bugs mailing list, accessible to the developers of the project only. This feature is used to be warned of all the possible exceptions occuring on the applciation anywhere; this way, most bugs can be corrected as soon as they happen. If you do not want the exceptions to be sent to this list, you can manually set property doNotSendExceptionReportsToDevelopers to true.
Adapt properties/smtp/smtp.xml for SMTP configuration.
Adapt properties/dao/hibernate/hibernate.cfg.xml for database confuguration.
Test your configuration:
- ant test-config
- ant test-smtp
- ant test-database
Initialize your database if necessary:
- ant init
  
  Note
  
  This Command will erase all existing data in your database !!!!
  
  Your database (configured in hibernate.cfg.xml) must exists.
Deploy the application:
- ant deploy
Configure a new context in your application server. For example with Tomcat create a LecturePortlet.xml file in the Toncat conf/Catalina/localhost subfolder with content like this:
```
<Context path="/LecturePortlet"
        docBase="D:/esupdev/esupdev-2.5-esup-2/uPortal-quick-start/webapps/LecturePortlet">
        </Context>
```
Configure your portal to reference this portlet. For example with uPortal you can use cannel manager as shown here:

Note

Portlet definition ID is very important. Here it is LecturePortlet.esup-lecture. LecturePortlet must be equal to the appliation server context name and esup-lecture must be equal to the portlet-name of the WEB-INF/portlet.xml file.

If you don't use this default value you have to adap the "portlet-guid" parameter of "The esup-lecture portlet servlet" servlet in the WEB-INF/web.xml too.

2. Configuration

You can configure your application. For this: adapt file(s) in properties directory and use ant deploy to deploy again your application.

2.1. Technical configuration

2.2. Content configuration

2.2.1. esup-lecture.xml and <category>.xml

it describes contexts, category profiles and userId definition. Here is the structure of this file (for more information, look at dtd lecture-config.dtd) :

element channelConfig in esup-lecture.xml :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" >
<channelConfig>
  
  <!-- user attribute to define a user Id -->
  <userId>displayName</userId>
  
  <!-- contexts definition -->
  <context> ... </context>
  <context> ... </context>
  ...

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

</channelConfig>

element userId : it indicates which portal user attribute is used to define userId in the channel. Portal user attributes used must be defined in the portlet.xml - see "portlet.xml" section.
element context :
```
<context 
   name = "Démonstration Esup-Lecture"
   id = "default">
   <description>Context de démo</description> 
   <refCategoryProfile refId="demo1"/>
   <refCategoryProfile refId="demo2"/>
   ...
</context>
```
Here are defined context with:
- id (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. But in uPortal because of a bug (http://www.ja-sig.org/issues/browse/UP-1040) you can't use this feature.)
- name (displayed on interface)
- description (displayed on interface)
- eferences on category profile declared in this context (using category profile id)
You can declare as many category profiles as you want in a context. Each category profile must be defined in an element categoryProfile. A same categoryProfile can be declared in many contexts.
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" > 
   <visibility> ... </visibility>
</categoryProfile>
```
Here are defined category profile id, name, and
- urlCategory : url to get back a xml category file on a remote server -see after for its description-
- trustCategory ( yes | no ) : If it is "yes", visibility rights used are those of remote category and sources. If it is "no", visibility rights on category and sources used are those of this category profile, defined in visibility element.
- access ( public | cas ) : access of the category is public or cas because it needs CAS proxy ticket for authentication -not yet supported -
- ttl (second) : time to live of the remote category and its sources
- visibility : define group visibility for category referenced by this category profile. It is used only if trustCategory is set to "no"
element visibility :
```
<visibility>
   
   <allowed/>
   <autoSubscribed/>
   <obliged>	
      <group name="local.0"/>
      <group .../> 
      ...
      <regular attribute="sn" value="user" />
      <regular .../>
      ...
   </obliged>
</visibility>
```
In this element, you define 3 groups of visibility
- allowed : user inside are "allowed" to subscribe to a category - not yet supported -
- autoSubscribed : user inside are auto subscribed to this category and is allowed to unsubscribe - not yet supported -
- obliged : user inside are automatically subscribe to this category and can't unsubscribe - for the moment, it is the only way for users to see category -
A user is in a visibility group by two ways :
- group : user is in the portal group referenced by attribute name, in the example : user in in group "local.0" - see "portlet.xml" section.
- regular : user check regular, in the example : user value of portal attribute "sn" is "user" - see "portlet.xml" section.
element category in xml category file (describe by dtd category.dtd), provided by remote server, requested by urlCategory of esup-lecture.xml :
```
<?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
- a list of source profiles
- visibility : define group visibility for this category. It is used only if trustCategory attribute of referencing categoryProfile is set to "yes" else visibility of category profile is used - optional -
element sourceProfile in xml category file :
```
<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
- access ( public | cas ) : access of the source is public or cas because it needs CAS proxy ticket for authentication -not yet supported -
- specificUserContent ( yes | no) : if it is "yes", source content is specific to user. If it is "no", source content is the same for every users (If your configure with “yes” then application assumes that content can be deferent for each user (may be because of specific content due to profiling according to authentication). In this case application doesn't use any cache for the source. So be careful before use “yes” for this property.)
- url : url to get xml stream of the source
- visibility : define group visibility for source refered by this source profile. It is used only if trustCategory attribute of referencing categoryProfile is set to "yes" else visibility category profile is used - optional -
Note

Be carefull to manage unique id for every sources profiles defined in categories : application does not yet manage it.

2.2.2. mappings.xml

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

A source is composed of a list of items that will be parsed to be all displayed on interface . A mapping is used to define xsltFile and itemXPath to apply on a source. Sometimes, to define itemXPath, namespaces definition are required. Here is a mapping :

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

2.2.3. portlet.xml