One of the primary ways of extending the functionality of Liferay Portal is by the use of plugins. Plugins are an umbrella term for installable portlet, theme, layout template, and web module Java EE .war files. Though Liferay comes bundled with a number of functional portlets, themes, layout templates, and web modules, plugins provide a means of extending Liferay to be able to do almost anything.
Portlets are small web applications that run in a portion of a web page. The heart of any portal implementation is its portlets, because all of the functionality of a portal resides in its portlets. Liferay's core is a portlet container. The container's job is to manage the portal's pages and to aggregate the set of portlets that are to appear on any particular page. This means that all of the features and functionality of a portal application must be in its portlets.
Portlet applications, like servlet applications, have become a Java standard which various portal server vendors have implemented. The JSR-168 standard defines the portlet 1.0 specification, and the JSR-286 standard defines the portlet 2.0 specification. A Java standard portlet should be deployable on any portlet container which supports the standard. Portlets are placed on the page in a certain order by the end user and are served up dynamically by the portal server. This means that certain "givens" that apply to servlet-based projects, such as control over URLs or access to the HttpServletRequest object, don't apply in portlet projects, because the portal server generates these objects dynamically.
Tip: Liferay 4.4.2 and below support the Portlet 1.0 standard: JSR-168. Liferay 5.0 and above support the Portlet 2.0 standard: JSR-286. You cannot run Portlet 2.0 portlets in Liferay 4.4.2, but because the Portlet 2.0 standard is backwards-compatible, portlets written to the 1.0 standard will run in Liferay 5.x and above.
Portal applications come generally in two flavors: 1) portlets can be written to provide small amounts of functionality and then aggregated by the portal server into a larger application, or 2) whole applications can be written to reside in only one or a few portlet windows. The choice is up to those designing the application. The developer only has to worry about what happens inside of the portlet itself; the portal server handles building out the page as it is presented to the user.
Most developers nowadays like to use certain frameworks to develop their applications, because those frameworks provide both functionality and structure to a project. For example, Struts enforces the Model-View-Controller design pattern and provides lots of functionality—such as custom tags and form validation—that make it easier for a developer to implement certain standard features. With Liferay, developers are free to use all of the leading frameworks in the Java EE space, including Struts, Spring, and Java Server Faces. This allows developers familiar with those frameworks to more easily implement portlets, and also facilitates the quick porting of an application using those frameworks over to a portlet implementation.
Additionally, Liferay supports "portlets" written in other programming languages. This allows you to take advantage of existing expertise in your organization with PHP, Ruby, or Python. Your developers can find sample portlets written in these environments in Liferay's plugin repository.
Does your organization make use of any Enterprise Planning (ERP) software that exposes its data via web services? You could write a portlet plugin for Liferay that can consume that data and display it as part of a dashboard page for your users. Do you subscribe to a stock service? You could pull stock quotes from that service and display them on your page, instead of using Liferay's built-in Stocks portlet. Do you have a need to combine the functionality of two or more servlet-based applications on one page? You could make them into portlet plugins and have Liferay display them in whatever layout you want. Do you have existing Struts, Spring MVC, or JSF applications that you want to integrate with your portal? It is a straightforward task to migrate these applications into Liferay, and then they can take advantage of the layout, security, and administration infrastructure that Liferay provides.
Themes are hot deployable plugins which can completely transform the look and feel of the portal. Most organizations have their own look and feel standards which go across all of the web sites and web applications in the infrastructure. Liferay makes it possible for a site designer to create a theme plugin which can then be installed, allowing for the complete transformation of the portal to whatever look and feel is needed. There are lots of available theme plugins on Liferay's web site, and more are being added every day. This makes it easier for those who wish to develop themes for Liferay, as you can now choose a theme which most closely resembles what you want to do and then customize it. This is much easier than starting a theme from scratch. There is more about theme development in the Liferay Developer's Guide.
Layout Templates are ways of choosing how your portlets will be arranged on a page. They make up the body of your page, the large area where you drag and drop your portlets to create your pages. Liferay Portal comes with several built-in layout templates, but if you have a complex page layout (especially for your home page), you may wish to create a custom layout template of your own. This is covered in the Liferay Developer's Guide.
Web plugins are regular Java EE web modules that are designed to work with Liferay. Liferay supports integration with various Enterprise Service Bus (ESB) implementations, as well as Single Sign-On implementations, workflow engines and so on. These are implemented as web modules that are used by Liferay portlets to provide functionality.
Installing Plugins from Liferay's Official and Community Repositories
Liferay Portal comes with two portlets which can handle plugin installation: the Plugin Installer and the Update Manager. Both portlets have similar functionality; the only difference between them is that the Update Manager can go out to the repositories and determine if you are running the most recent version of a plugin. For this reason, we will use the Update Manager portlet to install plugins.
From an appropriate private page on either a personal or public community, go up to the Dock and select Add Content. From the Admin category, click the Add button next to Update Manager. Then close the Add Content window.
You should now see the Update Manager on your page. Move it to an appropriate area of the page.
The default look of the Update Manager shows which plugins are already installed on the system, what their version numbers are, and whether an update is available.
Illustration 66: Update ManagerIf you would like to see what plugins are available, you can do so by clicking the Install More Plugins button. Please note that the machine upon which Liferay is running must have access to the Internet in order to be able to read the Official and Community repositories. If the machine does not have access to the Internet, you will need to download the plugins from the site and install them manually. We will discuss how to do this later in this chapter.
From the initial page you can also refresh the list of plugins. This causes the portlet to access the repository on the Internet and update the list of plugins that are available. When the refresh is complete, a status message is displayed which shows whether the refresh was successful.
After the Install More Plugins button is clicked, a new view of the portlet appears. This view has multiple tabs, and by default, displays the Portlet Plugins tab. Note that the list displayed is a list of all of the plugins that are available across all of the repositories to which the server is subscribed. Above this is a search mechanism which allows you to search for plugins by their name, by whether they are installed, by tag, or by which repository they are in.
Illustration 67: Google Maps portlet installationTo install a plugin, choose the plugin by clicking on its name. For example, if your web site is for an organization to which visitors are likely to travel, you might want to install the Google Maps plugin. This plugin provides a handy interface to Google Maps from inside of Liferay, and therefore from inside of your web site.
Find the Google Maps plugin in the list by searching for it or browsing to it. Once you have found it, click on its name. Another page will be displayed which describes the portlet plugin in more detail. Below the description is an Install button. Click this button to install your plugin.
The plugin chosen will be automatically downloaded and installed on your instance of Liferay. If you have the Liferay console open, you can view the deployment as it happens. When it is finished, you should be able to go back to the Add Content window and add your new plugin to a page in your portal.
The same procedure is used for installing new Liferay Themes, Layout Templates, and web modules. Instead of the Portlet Plugins tab, you would use the appropriate tab for the type of plugin you wish to install to view the list of plugins of that type. For themes, convenient thumbnails (plus a larger version when you click on the details of a particular theme) are shown in the list.
Illustration 68: Portlet Plugins in the Plugin InstallerAfter clicking on the Install button for a theme, the theme becomes available on the Look and Feel tab of any page.
Installing Plugins Manually
Installing plugins manually is almost as easy as installing plugins via the Plugin Installer. There are several scenarios in which you would need to install plugins manually rather than from Liferay's repositories:
Your server is firewalled without access to the Internet. This makes it impossible for your instance of Liferay to connect to the plugin repositories.
You are installing portlets which you have either purchased from a vendor, downloaded separately, or developed yourself.
For security reasons, you do not want to allow portal administrators to install plugins from the Internet before they are evaluated.
You can still use the Update Manager / Plugin Installer portlets to install plugins that are not available from the on line repositories. This is by far the easiest way to install plugins.
If your server is firewalled, you will not see any plugins displayed in the Portlet Plugins tab or in the Theme Plugins tab. Instead, you will need to click the Upload File tab. This gives you a simple interface for uploading a .war file containing a plugin to your Liferay Portal.
Click the Browse button and navigate your file system to find the portlet or theme .war you have downloaded. The other field on the page is optional: you can specify your own context for deployment. If you leave this field blank, the default context defined in the plugin (or the .war file name itself) will be used.
That's all the information the Plugin Installer needs in order to deploy your portlet, theme, layout template or web module. Click the Install button, and your plugin will be uploaded to the server and deployed. If it is a portlet, you should see it in the Add Content window. If it is a theme, it will be available on the Look and Feel tab in the page definition.
If you do not wish to use the Update Manager or Plugin Installer to deploy plugins, you can also deploy them at the operating system level. The first time Liferay starts, it creates a hot deploy folder which is by default created inside the home folder of the user who launched Liferay. For example, say that on a Linux system, the user lportal was created in order to run Liferay. The first time Liferay is launched, it will create a folder structure in /home/lportal/liferay to house various configuration and administrative data. One of the folders it creates is called deploy. If you copy a portlet or theme plugin into this folder, Liferay will deploy it and make it available for use just as though you'd installed it via the Update Manager or Plugin Installer. In fact, this is what the Update Manager and Plugin Installer portlets are doing behind the scenes.
You can change the defaults for this directory structure so that it is stored anywhere you like by modifying the appropriate properties in your portal-ext.properties file. Please see the above section on the portal-ext..properties file for more information.
To have Liferay hot deploy a portlet or theme plugin, copy the plugin into your hot deploy folder, which by default is in <User Home>/liferay/deploy. If you are watching the Liferay console, you should see messages like the following:
19:54:15,339 INFO [AutoDeployDir:76] Processing westminstercatechism-portlet-18.104.22.168.war
19:54:15,340 INFO [PortletAutoDeployListener:77] Copying portlets for /home/liferay/liferay/deploy/westminstercatechism-portlet-22.214.171.124.war
19:54:15,345 INFO [BaseDeployer:532] Deploying westminstercatechism-portlet-126.96.36.199.war
Expanding: /home/liferay/liferay/deploy/westminstercatechism-portlet-188.8.131.52.war into /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349
Copying 1 file to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349/WEB-INF
Copying 1 file to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349/WEB-INF/classes
Copying 1 file to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349/WEB-INF/classes
Copying 1 file to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349/META-INF
19:54:16,727 INFO [BaseDeployer:1248] Modifying Servlet 2.3 /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349/WEB-INF/web.xml
Copying 31 files to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/webapps/westminstercatechism-portlet
Copying 1 file to /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/webapps/westminstercatechism-portlet
Deleting directory /home/liferay/Documents/Liferay/code/portal/bundles/liferay-portal-5.1-tomcat-5.5/temp/20080804195415349
19:54:17,082 INFO [PortletAutoDeployListener:87] Portlets for /home/liferay/liferay/deploy/westminstercatechism-portlet-184.108.40.206.war copied successfully
19:54:23,170 INFO [PortletHotDeployListener:201] Registering portlets for westminstercatechism-portlet
19:54:23,192 INFO [PortletHotDeployListener:208] 1 portlets for westminstercatechism-portlet are ready for registration
19:54:23,261 INFO [PortletHotDeployListener:284] 1 portlets for westminstercatechism-portlet registered successfully
As long as you see the registered successfully message, your plugin was installed correctly, and will be available for use in the portal.
Sometimes for various reasons plugins fail to install. There are different reasons for this based on several factors, including
The container upon which Liferay is running
Changing the configuration options in multiple places
How Liferay is being launched
You will often be able to tell if you have a plugin deployment problem by looking at the Liferay server console. If you see the plugin get recognized by the hot deploy listener, you will see a plugin copied successfully message. If this message is not followed up by a plugin registered successfully message, you have an issue with your plugin deployment configuration, and it is likely one of the factors above.
We will look at each of these factors.
Liferay Configuration Issues
Tip: This applies to Liferay versions prior to version 4.3.5. Liferay versions above 4.3.5 are able to auto detect the type of server it is running on, which makes things a lot easier.
Liferay by default comes as a bundle or as a .war file. Though every effort has been made to make the .war file as generic as possible, sometimes the default settings are inappropriate for the container upon which Liferay is running. Most of these problems have been resolved in Liferay 4.3.5 with the addition of code that allows Liferay to determine which application server it is running on and adjust the way it deploys plugins as a result.
In versions of Liferay prior to 4.3.5, there is a property called auto.deploy.dest.dir that defines the folder where plugins are deployed after the hot deploy utilities have finished preparing them. This folder maps to a folder that the container defines as an auto-deploy or a hot deploy folder. By default, this property is set to ../webapps. This default value works for Tomcat containers (if Tomcat has been launched from its bin folder), but will not work for other containers that define their hot deploy folders in a different place.
For example, Glassfish defines the hot deploy folder as a folder called autodeploy inside of the domain folder in which your server is running. By default, this is in <Glassfish Home>/domains/domain1/autodeploy. JBoss defines the hot deploy folder as a root folder inside of the particular server configuration you are using. By default, this is in <JBoss Home>/server/default/deploy. WebLogic defines this folder inside of the domain directory. By default, this is in <Bea Home>/user_projects/domains/<domain name>/autodeploy.
You will first need to determine where the hot deploy folder is for the container you are running. Consult your product documentation for this. Once you have this value, there are two places in which you can set it: the portal-ext.properties file and in the Plugin Installer portlet.
To change this setting in the portal-ext.properties file, browse to where Liferay was deployed in your application server. Inside of this folder should be a WEB-INF/classes folder. Here you will find the portal-ext.properties file. Open this file in a text editor and look for the property auto.deploy.dest.dir. If it does not appear in the file, you can add it. The safest way to set this property—as we will see later—is to define the property using an absolute path from the root of your file system to your application server's hot deploy folder. For example, if you are using Glassfish, and you have the server installed in /java/glassfish, your auto.deploy.dest.dir property would look like the following:
Remember, if you are on a Windows system, use forward slashes instead of back slashes, like so:
Save the file and then restart your container. Now plugins should install correctly.
If you would rather change this setting via the Plugin Installer portlet (because you do not wish to restart your container), you can do that by clicking on the Configuration tab. On this page are a number of settings you can change, including the default folders for hot deploy, where Liferay should look for plugin repositories, and so on.
Illustration 69: Changing the hot deploy destination directoryThe setting to change is the field marked Destination Directory. Change this to the full path to your container's auto deploy folder from the root of your file system. When you are finished, click the Save button at the bottom of the form. The setting will now take effect without your having to restart your container.
Note that the setting in the portlet overrides the setting in the properties file.
If you are having hot deploy trouble in Liferay versions 4.3.5 and greater, it is possible that the administrator of your application server has changed the default folder for auto deploy in your application server. In this case, you would want to set auto.deploy.dest.dir to the customized folder location as you would with older versions of Liferay. In Liferay 4.3.5 and greater, this setting still exists, but is blank. Add the property to your portal-ext.properties file and set its value to the fully qualified path to the auto deploy folder configured in your application server.
The Container Upon Which Liferay Is Running
There are some containers, such as Oracle Application Server and WebSphere®, which do not have a hot deploy feature. Unfortunately, these containers do not work with Liferay's hot deploy system. But this does not mean that you cannot install plugins on these containers. Some users have had success deploying plugins manually using the application server's deployment tools. On some containers, Liferay is able to pick up the portlet plugins once they get deployed to the container manually, especially if you add it to the same Enterprise Application project that was created for Liferay.
When Liferay hot deploys portlet and theme .war files, it sometimes makes modifications to those files right before deployment. In order to successfully deploy plugins using an application server vendor's tools, you will want to run your plugins through this process before you attempt to deploy them.
Using the Plugin Installer portlet, click the Configuration tab. The second-most field on the form is labeled Destination Directory. Place the path to which you would like plugin .war files copied after they are processed by Liferay's plugin installer process. You will use this as a staging directory for your plugins before you install them manually with your server's deployment tools. When you are finished, click Save.
Now you can deploy plugins using the Plugin Installer portlet or by dropping .war files into your auto deploy directory. Liferay will pick up the files, modify them, and then copy the result into the destination directory you have configured. You may then deploy them from here to your application server.
Changing the Configuration Options in Multiple Places
Sometimes, especially during development when several people have administrative access to the server at the same time, the auto deploy folder location can get customized in both the portal-ext.properties file and in the Plugin Installer portlet. If this happens, the value in the Plugin Installer takes precedence over the value in the properties file. If you go into the Plugin Installer and change the value to the correct setting, plugin deployment will start working again.
How Liferay Is Being Launched
Tip: This applies to Liferay versions prior to version 4.3.5. Liferay versions above 4.3.5 are able to auto detect the type of server it is running on, and this property is no longer detected via the relative path from the server launch location.
In versions of Liferay prior to 4.3.5, the default value of the hot deploy destination directory is a relative path (e.g., ../webapps or ../server/default/deploy). This path is relative to the folder from which the application server is normally launched. For example, Tomcat has the pictured directory structure.
The start up and shut down scripts are in the bin folder. So to start Tomcat, you would normally go into the bin folder to run the startup script which starts Liferay running in Tomcat.
Illustration 70: Tomcat Directory StructureTomcat's hot deploy folder is the webapps folder. This folder is on the same level the bin folder is on. If you are at the command prompt inside of the bin folder (where you started Tomcat), to get to a file in the hot deploy folder you would reference it by using two dots to go back up one folder, and then the path separator (/), and then the name of the folder (webapps). So in the default configuration, the hot deploy destination directory is relative to the folder from which the application server was launched.
If you are launching your application server from another script—perhaps as part of a cron job—and your script does not enter the folder the application server's startup scripts are in (in this case, <Tomcat Home>/bin), the relative path that is set by default will not work. Instead, the path will be relative to the path from which you launched the startup script. This will cause Liferay to create—in the Tomcat example—a webapps folder one folder up from where the startup script was launched. Since this is not the correct hot deploy folder for your application server, you will see the copied successfully message in the server console, but you will never see the registered successfully message.
To fix this, you can do one of two things: 1) Change the relative path to an absolute path as recommended above; or 2) Change the way you launch Liferay by making sure you go into the folder where the application server's startup scripts are before you launch them. Either one of these methods should fix your hot deploy problem and will result in the successful deployment of portlet and theme plugins.
Creating Your Own Plugin Repository
As your enterprise builds its own library of portlets for internal use, you can create your own plugin repository to make it easy to install and upgrade portlets. This will allow different departments who may be running different instances of Liferay to share portlets and install them as needed. If you are a software development house, you may wish to create a plugin repository for your own products. Liferay makes it easy for you to create your own plugin repository and make it available to others.
You can create your plugin repository in two ways:
Both methods have their benefits. The first method allows users to upload their plugins to an HTTP server to which they have access. They can then register their plugins with the repository by adding a link to it via the portlet's graphical user interface. Liferay will then generate the XML necessary to connect the repository to a Plugin Installer portlet running another instance of Liferay. This XML file can then be placed on an HTTP server, and the URL to it can be added to the Plugin Installer, making the portlets in this repository available to the server running Liferay.
The second method does not require an instance of Liferay to be running. You can upload plugins to an HTTP server of your choice, and then create an XML file called liferay-plugin-repository.xml manually. If you make this file available on an HTTP server (it can be the same one upon which the plugins are stored, or a different one altogether), you can connect the repository to a Plugin Installer portlet running on an instance of Liferay.
We will first look at creating a plugin repository using the Software Catalog portlet.
The Software Catalog Portlet
You will want to use the Software Catalog portlet if you will have multiple users submitting portlets into the repository, and if you don't want to worry about creating the liferay-plugin-repository.xml file yourself.
Illustration 71: Software Catalog with no productsThe Software Catalog portlet is not an instanceable portlet, which means that each community can have only one instance of the portlet. If you add the portlet to another page in the community, it will hold the same data as the portlet that was first added. Different communities, however, can have different software repositories, so you can host several software repositories on the same instance of Liferay if you wish—they just have to be in different communities.
Choose the community that will host the plugin repository and add the Software Catalog portlet to the appropriate page in that community. You can do this by navigating to the page, selecting Add Content from the Dock, expanding the Admin category, and clicking the Add button next to the Software Catalog. Close the Add Content window and then drag the Software Catalog portlet to a wide column and drop it there.
The Software Catalog portlet has several tabs. The first tab is labeled Products. The default view of the portlet, when populated with software, displays what plugins are available for install or download. This can be seen in the version on Liferay's home page.
Illustration 72: Populated Software Catalog from liferay.comWe will use an example community in order to better illustrate how to use the Software Catalog portlet. Assume you, as the portal administrator, have created a community called Old Computers. This community will be a web site for users to collaborate on setting up and using old computers with obsolete hardware and operating systems. Users who participate in the site will eventually get upgraded to Power User status and get their own blog page. To implement this, you have created a My Summary portlet which displays the user's name, picture, and description from his or her user profile. Because this portlet is generic enough that it could be useful to anyone using Liferay, you have decided to make it available in your own software catalog.
In your Old Computers community, you have created a page called Software. This is where you have added your Software Catalog portlet.
The first step in adding a plugin to your software repository is to add a license for your product. A license communicates to users the terms upon which you are allowing them to download and use your software. Click the Licenses tab and then click the Add License button that appears. You will then see a form which allows you to enter the title of your license, a URL pointing to the actual license document, and check boxes denoting whether the license is open source, active, or recommended.
When you have finished filling out the form, click the Save button. Your license will be saved. Once you have at least one license in the system, you can begin adding software products to your software catalog. Click the Products tab, and then click the Add Product button.
Your next step will be to create the product record in the software catalog portlet. This will register the product in the software catalog and allow you to start adding versions of your software for users to download and / or install directly from their instances of Liferay. You will first need to put the .war file containing your software on a web server that is accessible without authentication to the users who will be installing your software. In the example above, the Old Computers site is on the Internet, so you would place the file on a web server that is accessible to anyone on the Internet. If you are creating a software catalog for an internal Intranet, you would place the file on a web server that is available to anyone inside of your organization's firewall.
To create the product record in the Software Catalog portlet, click the Products tab, and then click the Add Product button. Fill out the form with information about your product.
Illustration 73: Adding a product to the Software Catalog (partial view)Name: The name of your software product.
Type: Select whether this is a portlet or a theme plugin.
Licenses: Select the license(s) under which you are releasing this software.
Author: Enter the name of the author of the software.
Page URL: If the software has a home page, enter its url here.
Tags: Enter any tags you would like added to this software.
Short Description: Enter a short description. This will be displayed in the summary table of your software catalog.
Long Description: Enter a longer description. This will be displayed on the details page for this software product.
Permissions: Click the Configure link to set permissions for this software product.
Group ID: Enter a group ID. A group ID is a name space which usually identifies the company or organization that made the software. For our example, we will use old-computers.
Artifact ID: Enter an Artifact ID. The artifact ID is a unique name within the name space for your product. For our example, we will use my-summary-portlet.
Screenshot: Click the Add Screenshot button to add a screen shot of your product for users to view.
When you have finished filling out the form, click the Save button. You will be brought back to the product summary page, and you will see that your product has been added to the repository.
Illustration 74: Product has been added to the Software CatalogNotice that in the version column, N/A is being displayed. This is because there are not yet any released versions of your product. To make your product downloadable, you need to create a version of your product and point it to the file you uploaded to your HTTP server earlier.
Before you do that, however, you need to add a Framework Version to your software catalog. A Framework version denotes what version of Liferay your plugin is designed for and works on. You cannot add a version of your product without linking it to a version of the framework for which it is designed.
Why is this so important? Because as Liferay gains more and more features, you may wish to take advantage of those features in future versions of your product, while still keeping older versions of your product available for those who are using older versions of Liferay. This is perfectly illustrated in the example My Summary portlet we are using. Liferay had a My Summary portlet of its own, which does exactly what we have described here. For version 5.1, however, this portlet has been replaced by the World of Liferay (WOL) portlet, which makes use of the many social networking features which have been added to Liferay. So rather than just displaying a summary of your information, the WOL portlet adds features such as status updates, a "wall" for each user in his or her profile that other users can "write" on, the ability to become "friends" with other users—thereby granting them access to their profiles—and more.
None of this would work in older versions of Liferay, because the core engine that enables developers to create features like this is not there. So in this case, you would want to keep the older My Summary portlet available for users who have not yet upgraded, but also make the WOL portlet available to those who are using the latest version of Liferay. This is what Framework Versions does for you. If you connect to Liferay's software repositories with a Liferay 4.4.2 version, you will see the My Summary portlet. If you connect to Liferay's software repositories with a Liferay 5.1 version, you will see the WOL portlet.
So click the Framework Versions tab and then click the Add Framework Version button.
Give the framework a name, a URL, and leave the Active check box checked. For our example, we have entered 4.3.4 for the name, because our portlet should work on that version and higher, and http://www.liferay.com for the URL. Click Save.
Now go back to the Products tab and click on your product. You will notice that a message is displayed stating that the product does not have any released versions. Click the Add Product Version button.
Illustration 75: Adding a product version to the Software CatalogVersion Name: Enter the version of your product.
Change Log: Enter some comments regarding what changed between this version and any previous versions.
Supported Framework Versions: Select the framework version for which your software product is intended. Enter a + at the end of the version number if you want to specify a version plus any future versions.
Download Page URL: If your product has a descriptive web page, enter its URL here.
Direct Download URL (Recommended): Enter a direct download link to your software product here. The Plugin Installer portlet will follow this link in order to download your software product.
Include Artifact in Repository: To enable others to use the Plugin Installer portlet to connect to your repository and download your plugin, select yes here.
When you are finished filling out the form, click the Save button. Your product version will be saved, and your product will now be available in the software repository.
Generating The Software Catalog
The Software Catalog works by generating an XML document which the Plugin Installer reads. Using the data from this XML document, the Plugin Installer knows where it can download the plugins from, what version of Liferay the plugins are designed for, and all other data about the plugins that have been entered into the Software Catalog portlet.
In order to get your Software Catalog to generate this XML data, you will need to access a particular URL. If you have created a friendly URL for your community (for example, the default community, which is called guest, has a friendly URL of /guest already configured for it), you can use the friendly URL. If not, you will first need to know the Group ID of the community in which your Software Catalog portlet resides. You can do this by accessing the Manage Pages interface and looking at the URLs for any of the pages. The URL will look something like this: http://localhost:8080/web/10148/1.
Obviously, it is much easier if you are using Friendly URLs, and we highly recommend that you do.
Next, go to your browser and go to the following URL:
http://<server name>:<port number>/software_catalog?<Friendly URL name or Group ID>
For example, if you are on the same machine as your Liferay instance, and that instance is running on port 8080, and your group ID from the database is 10148, you would use the following URL:
If you have also created a friendly URL called old-computers for this organization or community, you would use the following URL:
If you have configured everything properly, an XML document should be returned:
<modified-date>Fri, 23 Nov 2007 17:07:33 -0500</modified-date>
<short-description>My Summary portlet</short-description>
<long-description>My Summary portlet</long-description>
<license osi-approved="true">MIT License</license>
Save this document to a file called liferay-plugin-package.xml and put this file on your HTTP server where you uploaded your portlet .war file. You can then give out the URL to the directory which holds this file on your web site, and anyone with an instance of Liferay will be able to point their Plugin Installer portlets to it.
Benefits of the Software Catalog Portlet
As you can see, the Software Catalog portlet makes it easy for you to create a repository of your software. Users of Liferay can configure their Plugin Installer portlets to attach to your repository, and the proper versions of your software will be automatically made available to them by a single click. This is by far the easiest way for you to keep track of your software, and for your users to obtain your software.
Another benefit of the Software Catalog portlet is that by using it, you make available to your users a standard interface for manually downloading your software. For those who prefer to manually download plugins, your Software Catalog gives them an interface to go in, find your software either by browsing or by searching, preview screen shots, and download your software—and you don't have to build any of those pages yourself. Simply configure your software in the portlet, and all of that is done for you.
Manually Creating A Software Catalog
If you do not wish to use the Software Catalog portlet to create your software catalog, you can create it manually by manually typing out the XML file that the Software Catalog portlet would normally generate. Note that if you do this, you will not have a graphical user interface to your software that end users can use to download your software manually: you will have to build this yourself. Keep in mind that many instances of Liferay Portal sit behind a firewall without access to the Internet. Because of this, if you are making your software available to Internet users, some of them will have to download it manually. In this case, the Software Catalog portlet is the easiest way to provide a user interface for downloading your software.
To manually create a software catalog, obtain the DTD for the XML file from Liferay's source code. You will find this DTD in the definitions folder in the Liferay source. It is a file called liferay-plugin-package_5_1_0.dtd. Use this DTD with a validating XML editor (a good, free choice is JEdit with all the XML plugins) to create your software catalog manually.
Connecting to a Software Catalog
If there is a software catalog of plugins that you would like to point your instance of Liferay to, all you need is the URL to the catalog. Once you have the URL, go to your Plugin Installer portlet and click the Configuration tab. You will see that there are two fields in which you can enter URLs to plugin repositories: Trusted Plugin Repositories and Untrusted Plugin Repositories. Currently, the only difference between the two is to provide a visual cue for administrators as to which repositories are trusted and untrusted.
Enter the URL to the repository to which you wish to connect in one of the fields and click Save. The portlet will connect to the repository, and items from this repository will be shown in the list.