| Volet | ||
|---|---|---|
| ||
Esup Lecture Portlet - Installation Guide
|
| Sommaire | ||||||
|---|---|---|---|---|---|---|
|
Important note
Because of uPortal limitation before
...
2.6.1
...
release
...
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
- 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" />
...
- 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
...
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
...
- :
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>
...
Configuration
You can configure your application. For this: adapt file(s)
...
in
...
properties
...
directory
...
and
...
use
...
ant
...
deploy
...
to
...
deploy
...
again
...
your
...
application.
...
Technical configuration
Adapt to your environment these configuration files:
- logging/log4j.properties
...
- for
...
- logging
...
- configuration
- esup-lecture.xml
...
- for
...
- global
...
- configuration
esup-lecture.xml
...
This
...
file
...
contents
...
some
...
global
...
configuration
...
properties:
...
- element
...
- guestUser
...
- in
...
- esup-lecture.xml
...
- :
| Bloc de 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 |
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.
...
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
...
Remarque
...
XML
...
Elements
...
or
...
attributes
...
not
...
explained
...
here
...
(but
...
in
...
dtd)
...
implements
...
features
...
that
...
are
...
not
...
yet
...
supported.
...
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
...
- :
...
Bloc de 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>
...
- element context:
Bloc de code <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.
Remarque Before uPortal 2.5.4,
...
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)
- 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:
| Bloc de code |
|---|
|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"
- elementvisibility:
In this element, you define 3 groups of visibility;Bloc de code <visibility> <!-- allowed and autoSubscribed not yet supported --> <allowed/> <autoSubscribed/> <obliged> <group name="local.0"/> <group .../> ... <regular attribute="sn" value="user" /> <regular .../> ... </obliged> </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 categoryin xml category file (describe by dtd category.dtd), provided by remote server, requested by urlCategory of esup-lecture.xml :
Bloc de 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>
...
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 :
Bloc de 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>
...
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 -
Remarque Be carefull to manage unique id for every sources profiles defined in categories : application does not yet manage it.
mappings.xml
mappings.xml: it describes a list of mappings used to parse xml stream of a source (see mappings.dtd):
| Bloc de code |
|---|
** _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
...
:
| Bloc de 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} |
- 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.
portlet.xml
All portal user attributes used by portlet must be declared in the webapp/WEB-INF/portlet.xml
...
,
...
here
...
is
...
an
...
example:
| Bloc de code |
|---|
\\ {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
...
(
...
properties/auth.xml
...
)
...
is
...
used
...
to
...
define
...
auth
...
mecanism.
...
For
...
example
...
when
...
using
...
CAS
...
in
...
servlet
...
mode
...
or
...
a
...
portal
...
in
...
portlet
...
mode:
| Bloc de code |
|---|
\\ {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 |
Servlet mode
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:
| Bloc de code |
|---|
\\ {code} <context name="Simple context" id="context"> <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} |
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
...
used
...
CAS
...
you
...
don't
...
have to modify the auth.xml
...
file
...
but
...
you
...
have
...
to
...
adapt
...
CAS
...
parameters.
...
For
...
this,
...
you
...
will
...
find
...
properties
...
(
...
tomcat.host
...
,
...
tomcat.port
...
,
...
cas.url
...
) in buil.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.
| Remarque |
|---|
In this context you do not use CAS authentication mechanism {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 ????? |