Table of Contents
We will assume that a JBoss is installed in /opt/jboss, and a Nuxeo platform is deployed on it.
The nuxeo-platform-restPack project contains some useful restlets, including the sample restlet used in the following project. You need to install it in your deployed Nuxeo EP.
Checkout the sources of the nuxeo-platform-restPack project:
svn co https://svn.nuxeo.org/nuxeo/nuxeo-addons/nuxeo-platform-restPack/trunk nuxeo-platform-restPack
Then, go into the newly created folder, build the project and copy the new .jar:
mvn clean package
cp target/nuxeo-platform-restPack-VERSION.jar /opt/jboss/server/default/deploy/nuxeo.ear/system
Restart JBoss
To enable the authentication between the portlet and the Nuxeo server, you need to install the nuxeo-platform-login-portal-sso project in your deployed Nuxeo EP.
Checkout the sources of the nuxeo-platform-login-portal-sso project:
svn co https://svn.nuxeo.org/nuxeo/nuxeo-addons/nuxeo-platform-login-portal-sso/trunk \
nuxeo-platform-login-portal-sso
To configure the authentication, edit the Sample-Portal-SSO-descriptor-bundle.xml file located in the Sample folder.
Then, copy it in the config folder of your deployed Nuxeo EP.
cp Sample/Sample-Portal-SSO-descriptor-bundle.xml /opt/jboss/server/default/deployed/nuxeo.ear/config
Then, go into the newly created folder, build the project and copy the new .jar:
mvn clean package
cp target/nuxeo-platform-login-portal-sso-VERSION.jar \
/opt/jboss/server/default/deploy/nuxeo.ear/system
Restart JBoss
Before creating a new project, you first need to install nuxeo-archetype-portlet on your local repository.
Checkout the sources:
svn co http://svn.nuxeo.org/nuxeo/org.nuxeo.archetypes/nuxeo-archetype-portlet/trunk \
nuxeo-archetype-portlet
Then, install the archetype on your local repository:
mvn clean install
To create a new project named my-portlet in the com.company.sandbox area:
mvn archetype:create -DartifactId=my-portlet -DgroupId=com.company.sandbox \
-DarchetypeArtifactId=nuxeo-archetype-portlet \
-DarchetypeGroupId=org.nuxeo.archetypes \
-DarchetypeVersion=1.0-SNAPSHOT
There are two arguments:
ArtifactId: usually the name of your project, with '-' to separate the words if there are many
GroupId: the domain name of your project. Usually the package parent name of your classes.
Maven should have generated the following source layout:
my-portlet
|-- pom.xml
`-- src
`-- main
|-- java
| `-- com
| `-- company
| `-- sandbox
| `-- portlet
| `-- sample
| `-- NuxeoSamplePortlet
|-- resources
| `-- org
| `-- nuxeo
| `-- portlet
| `-- sample
| `-- i18n
| |-- SamplePortletMessages_en.properties
| `-- SamplePortletMessages_fr.properties
|
`-- webapp
|-- index.jsp
`-- WEB-INF
|-- portlet.xml
|-- web.xml
|-- jsp
| |-- edit.jsp
| |-- sampleHelp.jsp
| `-- sampleView.jsp
`-- tld
|-- c.tld
|-- fmt.tld
`-- fn.tld
Right now, you can build the portlet, but it won't deploy on Jahia. In fact, portlet.xml still references the wrong class.
Edit portlet.xml and find the line:
<portlet-class>org.nuxeo.portlet.sample.NuxeoSamplePortlet</portlet-class>
In our example, the class is now in the package com.company.sandbox.portlet.sample, change the line to reference the right class:
<portlet-class>com.company.sandbox.portlet.sample.NuxeoSamplePortlet</portlet-class>
You can now build the portlet and deploy it on Jahia. In your project folder:
mvn clean package
cp target/my-portlet.war /opt/jahia/tomcat/webapps/jahia/WEB-INF/var/new_webapps
Just wait a few seconds that Jahia finds your new portlet and deploys it. Then, go to Jahia and add the portlet. Go to the edit page of the portlet and fill the different informations (like Nuxeo Server URL, UserName, Password, ...).
When all is configured, write your name and send it. You should have "Hello your_name!" as response.
Using NuxeoPortlet as base class make easier the developement of Portlets which have to communicate with Nuxeo EP.
NuxeoPortlet has some useful methods:
error handling
call a restlet on the configured NuxSeo server
global preferences handling (informations stored in global preferences are shared with all the users of the portlet)
If you use the archetype to make your project, you will have some default behaviors:
an administrator role is already defined (in web.xml and portlet.xml), so you can link, for instance,
Jahia administrator role to your portlet administrator role. In your code, use the method
isAdministrator() from NuxeoPortlet class to know if the current user is an administrator or not.
a basic, but with all the informations needed to connect to a Nuxeo EP, edition page for the portlet is already done.
All the informations are stored in global preferences for the portlet (through the getGlobalPreferences()
and saveGlobalPreferences() methods). That means you can allow only administrators to modify these
preferences, but they will be shared with all the users. You can of course create your own edition page and override the
default behaviour.
the action requests are dispatched in convenient methods, depending of the portlet mode. For instance, in the class
NuxeoSamplePortlet, we don't use the processAction() method, but
processViewAction() when portlet is in VIEW mode and processHelpAction() when in HELP mode.
You don't have to deal with the different portlet modes. Need to process a view action request? just use processViewAction().
See the nuxeo-portlet-search project as an example of how to use or override the defaults behaviours. This portlet allows the user to make a simple search or an advanced one (like in Nuxeo EP) on the configured Nuxeo server.
Beside the portlet class, portlet.xml lets you customize the portlet description, name, title.
There are also some default init parameters which are used to build the global preferences of the portlet. All the init parameters will be stored in the global preferences, so you can add the parameters you want and then use them in your portlet through the global preferences.
All the init parameters already in portlet.xml are needed by NuxeoPortlet to behave correctly.
The portlet communicates with the Nuxeo server through some restlets. In our example, we call the restlet sample with a name as parameter.
To do a restlet call, use the method doRestletCall() from NuxeoPortlet, it makes your call
and returns the result as a Representation (use getText() on it to have a String
containing the result). The doRestletCall() method takes a RestletCall object as argument which contains
the different parameters to do the restlet call: the restlet name, the path parameters and the query parameters.
See NuxeoSamplePortlet class or nuxeo-portlet-search project as example of how it works.
The doRestletCall() builds the URL to call from the configured Nuxeo server in the global preferences and from the parameters
of the RestletCall object. In our example:
http://localhost:8080/nuxeo/sample?name=my_name
--------------------------- ------ ------------
| | `-- the query parameters of the RestletCall object
| `-- the restlet name of the RestletCall object which will be
| in the path parameters
`-- the Nuxeo server URL from the global preferences
If all is well configured in the global preferences, you don't need to bother with authentication, just call the restlet.
To make a specific work, you have to develop your own restlets and contrib them to the nuxeo-platform-restPack project.
Then rebuild the project, copy the .jar in your deployed Nuxeo EP and restart JBoss. You can now call your newly created restlets in your portlet.
This portlet allows the user to search documents in a Nuxeo repository through a portlet container.
You just have to compile the portlet and install it into a portlet container, Jahia for instance, as explained in the previous sections.
After the installation of the prerequisites, you need to deploy on your portlet container the packaged portlet.
If you don't have already a packaged portlet, checkout the sources and package it:
svn co https://svn.nuxeo.org/nuxeo/nuxeo-addons/nuxeo-portlets/trunk/nuxeo-portlet-search \
nuxeo-portlet-search
cd nuxeo-portlet-search
mvn package
Then deploy the packaged portlet in Jahia, while Jahia is running:
cp target/nuxeo-portlet-search.war /opt/jahia/tomcat/webapps/jahia/WEB-INF/var/new_webapps
Before making any test, a Nuxeo EP should be running and you must configure the portlet for a Nuxeo EP:
Attach a group or a user from Jahia (the one who will be considered as Administrator for the portlet) to the Administrator role of the portlet.
Then, go to the edit view of the portlet and fill the different fields, so that the portlet can communicate with your Nuxeo EP.
This portlet provides the two search methods of Nuxeo EP, the simple one and the advanced one. They have the same behavior than the ones in Nuxeo EP.