| Volet | ||
|---|---|---|
| ||
Esup Lecture Portlet - Installation Guide
|
| Sommaire | ||||||
|---|---|---|---|---|---|---|
|
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
...
...
- projectsite
- Unzip the file somewhere on a working directory
Remarque 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.
...
Remarque
...
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
Remarque This Command will erase all existing data in your database !!!!
Your database (configured in config.properties) must exists.
- ant init-data
- 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:
Bloc de code <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:
Remarque 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.
...
Remarque You can specify a preference with name "context"
...
here
...
too.
...
See
...
chapter
...
2.2.1
...
about
...
context
...
id
...
for
...
more
...
information
...
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.xmlabout this.
...
- .
...
- 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
...
- :
Bloc de code <?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 :
Bloc de code @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:
| Bloc de code |
|---|
{code} h1. Configuration \\ You can configure your application. For this: adapt file(s) in properties directory and use *ant deploy* to deploy again your application. \\ h2. Technical configuration \\ Adapt to your environment these configuration files: * *logging/log4j.properties* for logging configuration * *esup-lecture.xml* for global configuration h3. esup-lecture.xml \\ This file contents some global configuration properties: * element *guestUser* in *esup-lecture.xml*: {code} <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" > <channelConfig> <guestUser>guest</guestUser> {code} *guestUser* is an optional propertie. Default value is "guest". If 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. \\ h2. Content configuration \\ To adapt to your environment, edit these configuration files: * *esup-lecture.xml*: main configuration file. Contexts and CategoryProfiles definition. It also deals with *<category>.xml*: remote xml file referecend by CategoryProfiles. \\ * *mappings.xml*: declarations about xslt transformation for interface display * *portlet.xml*: it needs declaration of portal user attributes used by Lecture Portlet * *auth.xml*: auth configuration {note}XML Elements or attributes not explained here (but in dtd) implements features that are not yet supported. {note} h3. esup-lecture.xml and <category>.xml \\ These files describe 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*: \\ {code} <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE channelConfig SYSTEM "lecture-config.dtd" > <channelConfig> <!-- contexts definition --> <context> ... </context> <context> ... </context> ... <!-- category profile definition --> <categoryProfile> ... </categoryProfile> <categoryProfile> ... </categoryProfile> ... </channelConfig> {code} * element *context*: \\ {code} <context name = "Démonstration Esup-Lecture" id = "default"> <description>Context de démo</description> <refCategoryProfile refId="demo1"/> <refCategoryProfile refId="demo2"/> ... </context> {code} 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. {note}Before uPortal 2.5.4, because of a bug ([http://www.ja-sig.org/issues/browse/UP-1040|http://www.ja-sig.org/issues/browse/UP-1040]) you can't use this feature. {note} * _name_ (displayed on interface) * _description_ (displayed on interface) * _refCategoryProfile_ references 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*: {code} <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> {code} Here are defined category profile _id_, _name_, and ** _urlCategory_ : url to get back a xml category file on a remote server ** _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_ (seconds) : time to live of the remote category and its sources ** _timeout_ (milliseconds) : time trying to get the category ** _visibility_ : define group visibility for category referenced by this category profile. It is used only if _trustCategory_ is set to "no" * element{*}visibility*: \\ {code} <visibility> <!-- allowed and autoSubscribed not yet supported --> <allowed/> <autoSubscribed/> <obliged> <group name="local.0"/> <group .../> ... <regular attribute="sn" value="user" /> <regular .../> ... </obliged> </visibility> {code} 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 : \\ {code} <?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> {code} 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 : \\ {code} <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> {code} 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 ** _timeout_ (milliseconds) : Time trying to get the source. Parent category timeout is used is it is not defined here ** _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. {note} h3. mappings.xml \\ {span:class=command}mappings.xml {span} : it describes a list of mappings used to parse xml stream of a source (see {span:class=command}mappings.dtd {span} ): \\ {code} <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mappings SYSTEM "mappings.dtd" > <mappings> <mapping> ... </mapping> <mapping> ... </mapping> ... </mappings> {code} 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 : {code} <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> {code} * _xsltFile_ : url of the xslt file used to parse an item * _itemXPath_ : xpath expression to locate an item in the xml stream source * element _XPathNameSpace_ : used by itemXPath definition - optionnal * _sourceURL_ : url of the source, key entry of this mapping * _dtd_ : dtd of the source, key entry of this mapping * _xmlns_ : xml namespace of the source, key entry of this mapping * _xmlType_ : xmlType of the source, key entry of this mapping * _rootElement_ : rootElement of the source,key entry of this mapping Priority to find xslt informations on key entry of a mapping are : sourceURL, DTD, xmlType, xmlns and finally rootElement. h3. portlet.xml \\ All portal user attributes used by portlet must be declared in the {span:class=command}webapp/WEB-INF/portlet.xml {span} , here is an example: \\ {code} <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> {code}\\ \\ \\ \\ \\ \\ h3. auth.xlm \\ This file ( {span:class=command}properties/auth.xml {span} ) is used to define auth mecanism. For example when using CAS in servlet mode or a portal in portlet mode: \\ {code} <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> {code} h1. Servlet mode \\ h2. Introduction \\ You can used 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 "context". Example: \\ {code} <context name="Simple context" id="contextdefault"> <description>Simple context</description> <refCategoryProfile refId="rss" /> </context> {code}\\ \\ \\ \\ \\ To used serlvet mode you just have to adapt \\ {span:class=command}buil.properties {span} with {span:class=command}deploy.type=servlet {span} before using {span:class=command}ant deploy {span} . \\ h2. Authentication \\ In servlet mode you can't used your portal for authentication. If you used CAS you don't have to modify the {span:class=command}auth.xml {span} file but you have to adapt CAS parameters. For this, you will find properties ( {span:class=command}tomcat.host {span} , {span:class=command}tomcat.port {span} , {span:class=command}cas.url {span} ) in {span:class=command}buil.properties {span} file. With these properties {span:class=command}ant deploy {span} will automatically make appropriate changes in your {span:class=command}web.xml {span} file. \\ h2. Authorization \\ Authorizations defined in your {span:class=command}esup-lecture.xml {span} 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 [ |
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.
Remarque 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/).
| Remarque |
|---|
| |http://sourcesup.cru.fr/projects/ esup-portal-ws /]). After, you have to configure esup-lecture to used this Web Service. For this, you have {span:class=command}portalService.url {span} , {span:class=command}portalService.testUserId {span} , {span:class=command}portalService.testGroupId {span} , {span:class=command}portalService.testGroupName {span} properties in the {span:class=command}config.properties {span} file. Finally, you can test the Web Service with {span:class=command}ant test-portal {span} . \\ h2. 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 ?????is now included in all 2.6-esup-2.0 and newer versions of esup-portail packaging of uPortal |
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.
| Remarque |
|---|
In this context you do not use CAS authentication mechanism
{note