Important note

Because of uPortal limitation before 2.6.1 release (OK since uPortal 2.6.1 DLM version) in session objects management esup-lecture may produce null pointer exceptions randomly. For this esup-lecture, since 0.9.0 release has a full support of servlet mode. Please see "Servlet mode" section for more information.

Installation

Installing the portlet

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

  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/config.properties for exception handling configuration, SMTP configuration and database confuguration.

  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.

• Test your configuration:
  • ant test-config
  • ant test-smtp
  • ant test-database

• Initialize your database if necessary (first installation):
  • ant init-data

    This Command will erase all existing data in your database !!!!
    Your database (configured in config.properties) 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="/esup-lecture" docBase="D:/esupdev/esupdev-2.5-esup-2/uPortal-quick-start/webapps/esup-lecture" />
  

  ATTENTION : Cf FAQ : http://www.esup-portail.org/display/PROJESUPLECTURE/FAQ+(French)?showComments=true#comments

Configuring the portlet in the portal

• Configure your portal to reference this portlet. For example with uPortal you can use channel manager as shown here:
  

  Portlet definition ID is very important. Here it is esup-lecture.esup-lecture. Fisrt esup-lecture must be equal to the appliation server context name and second 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.

  
  

  You can specify a preference with name "context" here too. See chapter 2.2.1 about context id for more information about this.

  If you don't use channel manager you can use a xml Portlet definition file. You can use this file with an uPortal ant target like ant uportal.pubchan -Dchannel=lecture-portlet.xml. For this, you have to save a lecture-portlet.xml file in the folder properties/chanpub of your uPortal distribution. This is an example of lecture-portlet.xml file :
  
  
  

  <?xml version="1.0" encoding="UTF-8"?>
  
  <!DOCTYPE channel-definition SYSTEM "channelDefinition.dtd">
  
  <channel-definition>
  
      <title>lecture-portlet</title>
      <name>lecture-portlet</name>
      <fname>lecture</fname>
      <desc>Esup-Portail lecture portlet</desc>
      <type>Portlet</type>
      <class>org.jasig.portal.channels.portlet.CPortletAdapter</class>
      <timeout>15000</timeout>
  
      <hasedit>N</hasedit>
      <hashelp>N</hashelp>
      <hasabout>N</hasabout>
  
      <secure>N</secure>
      <locale>en_US</locale>
  
      <categories>
          <category>Applications</category>
      </categories>
  
      <groups>
          <group>Everyone</group>
      </groups>
  
      <parameters>
  
          <!-- The syntax of the portletDefinitionId is [portlet-context-name].[portlet-name] -->
          <parameter>
              <name>portletDefinitionId</name>
              <value>esup-lecture.esup-lecture</value>
              <description>The syntax of the portletDefinitionId is [portlet-context-name].[portlet-name]</description>
              <ovrd>N</ovrd>
          </parameter>
  
          <parameter>
              <name>PORTLET.context</name>
              <value>default</value>
              <description>The "context" Portlet preference in relationship with context@id of the esup-lecture.xml file</description>
              <ovrd>N</ovrd>
          </parameter>
  
      </parameters>
  
  </channel-definition>
  

Adding esup-lecture styles in the portal

• Import lecture.css and thickbox.css (if you are using thickbox for news focusing) in main portal css page :
  For example with esup skin in a esup-portail package:
  • copy esup.css from update/uPortal/webpages/media/org/jasig/portal/layout/tab-column/xhtml-theme/esup to custom/uPortal/webpages/media/org/jasig/portal/layout/tab-column/xhtml-theme/esup/skin
  • adapt esup.css by adding :

    @import url("lecture.css");
    @import url("thickbox.css");
    

  •  copy lecture.css and thickbox.css in custom/uPortal/webpages/media/org/jasig/portal/layout/tab-column/xhtml-theme/esup/skin
  • use ant init deploy

Servlet mode

Introduction

You can use esup-lecture in servlet mode. In this mode you don't have the notion of Portlet preference and you can't define more than one context in your esup-lecture.xml file. In servlet mode this context must have an id with value "default" ("context" before 1.1.0 version). Example:

<context name="Simple context" id="default">
  <description>Simple context</description>
  <refCategoryProfile refId="rss" />
</context>

To used serlvet mode you just have to adapt buil.properties with deploy.type=servlet before using ant deploy.

Authentication

In servlet mode you can't used your portal for authentication. If you use CAS you don't have to modify the auth.xml file but you have to adapt CAS parameters ti suit your own CAS server. For this, you will find properties :

• tomcat.host, tomcat.port in build.properties file.
• casService.bean (it MUST be valued at servletCasService), ccasService.url, casService.proxyCallbackUrl in properties/config.properties file.

  With these properties ant deploy will automatically make appropriate changes in your web.xml file.

Authorization

Authorizations defined in your esup-lecture.xml file or provided by news portlet are based in attributes or groups issued form uPortal. Of course, in servlet mode you don't have access to these informations naturally. So, you have to install (if not yet present in your uPortal distribution) esup-portal-ws (see http://sourcesup.cru.fr/projects/esup-portal-ws/).

After, you have to configure esup-lecture to used this Web Service. For this, you have portalService.url, portalService.testUserId, portalService.testGroupId, portalService.testGroupName properties in the config.properties file. Finally, you can test the Web Service with ant test-portal.

Guest mode

If want to have a guest mode for esup-lecture in servlet mode you have to define a new context in your application server. You have to deploy a new esup-lecture in this new context.

In this context you do not use CAS authentication mechanism
{note