Skip to content

HowToBuildLiferayIntegration

Jump to bottom Edit New page
Quintin Siebers edited this page Jun 18, 2015 · 1 revision

Introduction

This document shows how to set up the Liferay integration from source. It covers the creation of a build environment for liferay plugins as well, because that's what the integration technically is.

Prerequisites:

  • An Ontopia 5.1.0 installation. (Must be built from source, since the integration requires changes made since the 5.1.0 release.)
  • Java 1.5.
  • Ant (for the plugins SDK).

Get the building blocks

1. Get Liferay 5.2.x or 6.0.x from www.liferay.com

2. Get the Liferay Plugins-SDK from www.liferay.com

3. Get Ontopia

  • (http://code.google.com/p/ontopia/) in case you don't have it already
  • set up a build env following ontopias docs or get the distribution
  • get the integration sourcecode from svn in sandbox/liferay-integration.

Note: The liferay-integration folder from svn contains two folders: WEB-INF and misc. misc contains the Liferay topic map. WEB-INF contains the integration's source and config files.

Put everything in place

4. Create a folder called portal, then unzip the Liferay bundle into it.

  • There will be a folder called liferay-portal-x.x.x within portal.
  • This is where Liferay lives.

5. Inside portal, create a new directory called sdk, then unzip the plugins-sdk into it.

  • This is where the plugins are built and deployed into Liferay.

6. Get necessary files from Ontopia into Liferay's Tomcat server:

  • Build your ontopia distribution (in case you downloaded the source code).
  • Within the distribution folder navigate to apache-tomcat/webapps copy the folders omnigator and ontopoly to the corresponding webapps directory within Liferay's Tomcat.
  • Make the Liferay topic map available somehow. If you use the default setup, copy misc/liferay.ltm to webapps/omnigator/WEB-INF/topicmaps.
  • copy also common/classes/tm-sources.xml to the corresponding directory within liferay's tomcat server (common/classes in Liferay 5.2, lib in Liferay 6.0).
  • copy also the contents of ontopia-5.x.x/lib to common/lib/ext for Liferay 5.2 and lib/ext for Liferay 6.0.
    • Accept replacement of files when prompted.
    • Remove velocity.jar, otherwise Liferay breaks completely.
  • copy jstl.jar and standard.jar from ontopia-5.x.x/apache-tomcat/common/lib to the same directory.

Create environment for building plugins

7. Change to portal/sdk

8. Go to hooks and run ./create.(sh|bat) ontopia. Then, edit ontopia-hook/docroot/WEB-INF/liferay-hook.xml and add <portal-properties>portal-ext.properties</portal-properties>.

  • This creates a new folder for the Ontopia integration.

9. create a file named build.{$Username}.properties within the sdk folder

  • This file contains information about the paths that shall be used.
  • Here is an example you might want to copy (change the paths though):
        app.server.dir=/Users/mfi/Projects/portal/liferay-portal-5.2.3/tomcat-5.5.27
        app.server.classes.portal.dir=${app.server.portal.dir}/WEB-INF/classes
        app.server.lib.global.dir=${app.server.dir}/common/lib/ext
        app.server.lib.portal.dir=${app.server.portal.dir}/WEB-INF/lib
        app.server.portal.dir=${app.server.dir}/webapps/ROOT

Note that on Liferay 6 common/lib needs to be just lib.

This is the content of the file I have been using for development. The Liferay book says you can add more info like:

    ant.build.javac.source= .... 
    ant.build.javac.target= ....

I didn't make use of that, though.

10. copy the contents of WEB-INF from the svn into the WEB-INF folder of your project's directory.

  • Your project's directory is the one that has been created for you using create.sh.
  • Accept replacement of files if prompted (config files are overwritten)
  • If using Liferay 5.2 then replace WEB-INF/jsps/html/portlets/journal/edit-article.jsp with edit-article-5.2.jsp

11. Create a file called ontopia.properties in docroot/WEB-INF/classes in the project directory. Add the following to it topicmapname=liferay.ltm. The topic map ID can of course be changed.

12. change to the root of the directory created by create.sh

  • Run ant deploy.
    • The sources are now being built and deployed as a .war file to your Liferay's tomcat server (given that all paths are right + Java is able to build)
    • Other available targets are clean and compile.
    • If it can't find the Ontopia classes, make sure ontopia.jar is in the directory pointed to by app.server.lib.global.dir in the build.${user}.properties file.

Once this works the plugin has been built and deployed into the Liferay server.

Configuration

13. In order to make the jsp integration work a nasty configuration hack is in place:

  • Open portal/liferay-portal-x.x.x/tomcat-x.x.xx/conf/catalina.properties in an editor of your choice.
  • Look up the line starting with: common.loader= and append ${catalina.home}/webapps/{$YourProjectName}/WEB-INF/classes
  • If you are unsure about the name, you can easily look it up in the webapps directory of liferay's tomcat. Just copy the name of the plugin's directory.

Info: This needs be done in order to ensure availability of the OntopiaAdapter to the tweaked JSPs.

Attention: For reasons yet to be investigated this seems to cause conflicting versions of antlr.jar to be used.

  • Please remove the antlr.jar version from: portal/liferay-portal-5.2.3/tomcat-5.5.27/webapps/ROOT/WEB-INF/lib

(An alternative approach is to use the build.xml file in ontopia-sandbox/liferay-integration (ant compile jar) to create an ontopia-liferay.jar and to put this into lib/ext. If you do, ontopia.properties must be moved to lib.)

14. For better logging you may want to do the following:

rm webapps/ontopia-hook/WEB-INF/lib/log4j.jar
rm webapps/ROOT/WEB-INF/lib/slf4j-api.jar
rm webapps/ROOT/WEB-INF/lib/slf4j-log4j12.jar
rm webapps/ROOT/WEB-INF/lib/log4j.jar

Finish

15. run ./startup.sh for liferay's tomcat and wait for the browser to pop up with liferays default page.

Using the plugin

Now that the plugin is installed everytime new webcontent, wikis or wiki pages are added the integration will create a topic for the object. It also keeps the topic map in sync with later changes.

UI Integration of Ontopoly

Once you have created web content i.e. and you open that web content in the "edit" mode, you will notice that a dropdown box, with the caption "Ontopoly" has been added right over the text area. This will let you pick an instance of the "Category" Topic as a tag for your webcontent. However, this does not work on creation of the article because the integration uses an iFrame with a URL that has to refer to an actually existing topic inside the topic map.

This works as well for wiki pages as of now (and for nothing else yet).

Portlets

If you would like to see something more of the integration you should use the portlets that are being developed at the moment. As of now there are two:

  • ShowTags
  • TopicName

How To Build Portlets

The procedure here is quite straight forward, because you probably already have the build environment set up from the above part. If not, you'll need to set it up first.

1. from the svn copy both folders from liferay-integration/portlets into the portlets folder in your sdk directory.

2. Build ontopia-liferay.jar. Go into ontopia-sandbox/liferay-integration, edit the reference to the lib directory in build.xml, then run ant compile jar to produce the jar file.

3. Copy ontopia-liferay.jar into portlets/*/docroot/WEB-INF/lib for each portlet.

3. Enter one of the portlet's directories and run the familiar ant deploy. If everything has been configured properly before, that portlet should be built and deployed just the same way as the hook.

ShowTags

This portlet shall display the tags of an article (webcontent) that is displayed on the same page in a WebcontentDisplay Portlet. It shall also produce links to pages, that can give further information on a given Topic (like other documents related to that topic). It uses different ways to obtain the information what article or topic that is:

  1. Check if it has been configured (not yet implemented)
  2. Check if the topic id for this article has been encoded in the url
  3. Check if the article id of this article has been encoded in the url
  4. Look for the next WebContentDisplay Portlet on that page and retrieve the article which it displays.

If #4 fails, an Exception is thrown.

(mini) Customization

Please note that ShowTags will produce all sorts of associations to an article/topic. This can be configured by clicking the "..." icon in the upper right corner and selecting "Preferences". A textbox will show up, in which you can enter the Object Ids of the associations NOT to display separated by commas. By clicking "Save" the changes will be applied.

Two possible Use Cases for this portlet were:

  1. A WebcontentDisplay Portlet + ShowTags on one page -> ShowTags produces a list of tags (including links). Those links lead to site that gives more detailed information on the selected tag.

  2. A TopicName Portlet + ShowTags Portlet on one page -> ShowTags produces a list of other documents that are about the same topic i.e.

TopicName

This portlet shall display information on a topic from the topicmap. As of now this only includes the topics name (hence the name) and a link to the psi of that topic. Eventually everything could be displayed here, as you have a reference to a topic. You could go and query the tm for whatever you like. This Portlet has 2 ways to obtain information on what topic to display:

  1. Check if it has been configured (not yet implemented)
  2. Check if the topic id for this article has been encoded in the url

If #2 fails, an Exception is thrown. This portlet can read out topic ids from urls of this form: http://localhost:8080/web/guest/something?topic=2887 for instance.

Ontology Annotations

As mentioned earlier, the ShowTags Portlet's job is to produce a list of tags for an article AND to provide useful links to pages giving more information on those tags. Such pages though are portal specific and therefore their location is unknown to the portlet.

To provide this information, you will find that all topic types have an occurrence named "template" that should be filled with a url that points to a place in your portal where you can display information about instances of this topic type.

To make ShowTags produce useful links you would want to fill in a value into the occurrence field attached to the typing topic "Categories" (of which all concepts/tags are instances). That could look like this: http://localhost:8080/web/guest/something?topic%topicid%. %topicid% is the placeholder that will be replaced by the portlet with the appropriate value.

To make ShowTags produce useful links to webcontent , you would want to fill in a value like http://localhost:8080/web/guest/home/-/journal_content/56/%groupid%/%articleid% into the occurrence field "template" in the "Article" typing topic (because "Article" is the type of all instances of normal webcontent within liferay). Again %groupid% and %articleid% serve as placeholders, that will be replaced with values by the portlet.

Displaying dynamic Webcontent

Because I was unable to find an easy way of telling a WebcontentDisplay what Webcontent to display by means of i.e. url parameters or the like, I made a portlet that reads the article=${articleid} and group=${groupid} parameters from the url and displays the appropriate content. This portlet gets an extra section here because it is not really bound to the integration in any way, as it doesn't use any of the integration's code.

If you place this portlet on the page http://localhost:8080/web/guest/mysite i.e. you would provide the parameters like: http://localhost:8080/web/guest/mysite?article=%articleid%&group=%groupid% (which could be the url-template for Webcontent for instance). This can be very useful together with the ShowTags portlet, which is now able to find the topic for a certain article by the same means (reading articleid from the url).

Building this

To build this you might need to include /portal/*/webapps/ROOT/WEB-INF/lib/util-taglib.jar in your classpath, because the portlet makes use of liferay's tag library for displaying the article.

It also does not require the integration's jar-file to be in the classpath.

Apart from that it is the same procedure as before:

1. from the svn copy the folder dynamicWcd-portlet from liferay-integration/portlets into the portlets folder in your sdk directory.

2. cd into dynamicWcd-portlet

3. run ant deploy to make and deploy it to your portal.

Where to find the portlets in Liferay

Now if you want to add such a portlet to one of your portlet pages, you need to select the "Add Application" item from the dropdown field in the upper right corner. As of now the portlets are filed under "Sample".

Notes

Default Group has been added to the topicmap

Group "guest" with GroupId 16 has been added to the topicmap to make creation of webcontent in the default group easier. Otherwise you'd have to create that group right in the beginning, before adding webcontent to it.

Add a custom footer

Sandbox

Clone this wiki locally