Plugin Management

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, hook, and web module Java EE .war files. Though Liferay comes bundled with a number of functional portlets, themes, layout templates, hooks, and web modules, plugins provide a means of extending Liferay to be able to do almost anything.

Portlets

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 the core doesn't contain application code. Instead, all of the features and functionality of your portal application must reside 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 allows for the consuming of PHP and Ruby applications as "portlets," so you do not need to be a Java developer in order to take advantage of Liferay's built-in features (such as user management, communities, page building and content management). You can use the Plugins SDK to deploy your PHP or Ruby application as a portlet, and it will run seamlessly inside of Liferay. We have plenty of examples of this; to see them, check out the Plugins SDK from Liferay's public code 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

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.

Illustration 66: Fruitopia theme from Liferay's theme repository.

Illustration 67: Blue Pigment theme from Liferay's theme repository. Layout Templates

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.

Hook Plugins

Hook plugins are new to Liferay 5.2. As the name implies, they allow "hooking" into Liferay's core functionality. This means that they enable developers to override or replace functionality that is in the core of the system. You can hook into the eventing system, model listeners, and portal properties. You can also override Liferay's core JSPs with your own. Hooks are very powerful and have been designed to replace some of the reasons for using the extension environment with something that is easier to use and hot deployable.

Web Plugins

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 Repositories

Liferay Portal has a section of the Control Panel which can handle plugin installation: Plugins Installation, which is in the Server category. This not only allows you to see what plugins are installed in your portal, but also it enables you to run the search indexer on those portlets that support it and install new portlets.

Go to the Dock and select Control Panel. In the Server category, select Plugins Installation.

You should now see the screen which allows you to configure and install portlets.

The default look of the Plugin Installer shows which plugins are already installed on the system, whether it is active, and what Portal roles have access to it.

Illustration 68: Plugins Installation in the Control PanelIf you would like to see what plugins are available, you can do so by clicking the Install More [Plugin Type] button, where [Plugin Type] changes based on which tab you are viewing. 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 navigate to the different pages of plugins, as they are all in alphabetical order. You can also change the number of items per page and navigate to a specific page if you know where a particular plugin appears in the list. This is a standard feature of Liferay, and you will see it in most of Liferay's portlets.

After the Install More [Plugin Type] button is clicked, a new view 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 69: Installing Plugins

To install a plugin, choose the plugin by clicking on its name. For example, if you want to provide a handy weather forecast to your web site, you might want to install the Weather portlet. This portlet provides a handy interface to which shows the current weather for a particular zip code which your users can customize.

Find the Weather Portlet 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.

Illustration 70: Adding the Weather Portlet to LiferayThe 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 Application window and add your new plugin to a page in your portal.

The same procedure is used for installing new Liferay Themes, Layout Templates, hooks, 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.

After 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 Control Panel 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, hook, 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 Liferay Home folder. This folder generally resides one directory up from where your application server is installed, though it sometimes is elsewhere depending on which application server you are running. To find out where the Liferay Home folder is for your application server, please see the section on your server in Chapter 1. The first time Liferay is launched, it will create a folder structure in Liferay Home 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 Plugin Installer in the Control Panel. In fact, this is what the Plugin Installer is 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 [Liferay Home]/deploy. If you are watching the Liferay console, you should see messages like the following:

16:16:19,450 INFO [AutoDeployDir:183] Processing web-form-portlet-5.2.2.1.war
16:16:19,452 INFO [PortletAutoDeployListener:77] Copying portlets for /opt/liferay/liferay-portal-5.2.2/deploy/web-form-portlet-5.2.2.1.war
Expanding: /opt/liferay/liferay-portal-5.2.2/deploy/web-form-portlet-5.2.2.1.war into /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617
Copying 1 file to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617/WEB-INF
Copying 1 file to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617/WEB-INF/classes
Copying 1 file to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617/WEB-INF/classes
Copying 1 file to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617/META-INF
Copying 38 files to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/webapps/web-form-portlet
Copying 1 file to /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/webapps/web-form-portlet
Deleting directory /opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/20090423161619617
16:16:20,925 INFO [PortletAutoDeployListener:87] Portlets for /opt/liferay/liferay-portal-5.2.2/deploy/web-form-portlet-5.2.2.1.war copied successfully. Deployment will start in a few seconds.
16:16:27,993 INFO [PortletHotDeployListener:333] Unregistering portlets for web-form-portlet
16:16:28,000 INFO [PortletHotDeployListener:362] 1 portlet for web-form-portlet was unregistered
Apr 23, 2009 4:16:27 PM org.apache.catalina.startup.HostConfig checkResources
INFO: Undeploying context [/web-form-portlet]
16:16:28,408 INFO [PortletHotDeployListener:219] Registering portlets for web-form-portlet
Loading file:/opt/liferay/liferay-portal-5.2.2/tomcat-5.5.27/temp/6-web-form-portlet/WEB-INF/classes/portlet.properties
16:16:28,570 INFO [PortletHotDeployListener:298] 1 portlet for web-form-portlet is available for use

As long as you see the available for use message, your plugin was installed correctly, and will be available for use in the portal.

Plugin Troubleshooting

Sometimes for various reasons plugins fail to install. There are different reasons for this based on several factors, including

• Liferay configuration

• 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 an available for use 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. If you are running a newer version of Liferay, you can skip this section.

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:

auto.deploy.dest.dir=/java/glassfish/domains/domain1/autodeploy

Remember, if you are on a Windows system, use forward slashes instead of back slashes, like so:

auto.deploy.dest.dir=C:/java/glassfish/domains/domain1/autodeploy

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 71: 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. You can deploy plugins manually using the application server's deployment tools. 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.

In the Plugin Installer section of the Control Panel, 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.

Example: WebSphere® Application Server

• If you don't have one already, create a portal-ext.properties file in the Liferay Home folder of your Liferay installation. Add the following directive to it:

  auto.deploy.dest.dir=${liferay.home}/websphere-deploy

• Create a folder called websphere-deploy inside your $LIFERAY_HOME folder. This is the folder where the Lucene index, Jackrabbit config, and deploy folders are.

• Make sure the web.xml file inside the plugin you want to install has the following context parameter in it:

<context-param>
<param-name>com.ibm.websphere.portletcontainer.PortletDeploymentEnabled</param-name>
<param-value>false</param-value>
</context-param>

Liferay versions 5.2.2 and higher will automatically inject this into the web.xml file on WebSphere containers.

• The WebSphere deploy occurs in two steps. You will first use Liferay's tools to "pre-deploy" the file, and then use WebSphere's tools to do the actual deployment. This is because Liferay makes deployment-time modifications to the plugins right before they are actually deployed to the application server. For other application servers, this can usually be done in one step, because Liferay can make the modifications and then copy the resulting .war file into an autodeploy folder to have it actually deployed. Because WebSphere does not have an autodeploy feature, we need to separate these two steps.

• Deploy your .war file using Liferay's Plugin Installer or by copying it into $LIFERAY_HOME/deploy. Liferay will make its modifications and because we changed the auto.deploy.dest.dir in the first step, it will copy the resulting .war file into $LIFERAY_HOME/websphere-deploy. You will see a copied successfully message in the log.

• Use WebSphere's tools to deploy the .war file. Make the context root for the .war file equal to the file name (i.e., /my-first-portlet). Once the .war file is deployed, save it to the master configuration.

• Go back to the Applications -> Enterprise Applications screen in the WebSphere Admin Console. You will see that your portlet is deployed, but not yet started. Start it.

• Liferay will immediately recognize that the portlet has been deployed and register it. The portlet will be automatically started and registered upon subsequent restarts of WebSphere.

Experienced WebSphere system administrators can further automate this by writing a script which watches the websphere-deploy directory and uses wsadmin commands to then deploy plugins automatically.

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 Control Panel. If this happens, the value in the Control Panel takes precedence over the value in the properties file. If you go into the Control Panel 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.

Tomcat'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:

• Use the Software Catalog in the Control Panel to create the repository by using its graphical interface and an HTTP server.

• Create an XML file using the Liferay Plugin Repository DTD (http://www.liferay.com/dtd/liferay-plugin-repository_5_2_0.dtd) and an HTTP server.

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 Control Panel's graphical user interface. Liferay will then generate the XML necessary to connect the repository to a Control Panel running on 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 in the Control Panel running on an instance of Liferay.

We will first look at creating a plugin repository using the Software Catalog in the Control Panel.

The Software Catalog

You will want to use the Software Catalog 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.

Each community in your portal can have an instance of the Software Catalog. The Control Panel will keep track of which community or organization you are in and present you with the software catalog for that community or organization. This means that different communities/organizations 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 or organizations.

Illustration 72: Software Catalog with no productsChoose the community that will host the plugin repository and go to the Control Panel. You will see at the top of the screen a message that says "Content for [Organization/Community]," where [Organization/Community] is the organization or community you were on when you selected the Control Panel from the Dock. If you want to administer the software catalog for a different community or organization, you can select it from the selection box.

The Software Catalog 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 73: 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 a more privileged 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.

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. 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 74: Adding a product to the Software Catalog (partial view)Name: The name of your software product.

Type: Select whether this is a portlet, theme, layout template, hook, or web 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 75: 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 was 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. For version 5.2, the WOL portlet itself has been broken down so that the social components can be installed separately from the software management components.

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, make the WOL portlets available to those who are using 5.1.x, and make the newer social portlets available to those using 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. If you connect to Liferay's software repositories with a Liferay 5.2 version, you will see the social portlets.

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 5.2.2 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 76: 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:

http://localhost:8080/software_catalog?10148

If you have also created a friendly URL called old-computers for this organization or community, you would use the following URL:

http://localhost:8080/software_catalog?old-computers

If you have configured everything properly, an XML document should be returned:

<?xml version="1.0" encoding="UTF-8"?>

<plugin-repository>
<settings/>
<plugin-package>
<name>My Summary</name>
<module-id>old-computers/my-summary-portlet/1.0/war</module-id>
<modified-date>Thu, 23 Apr 2009 20:40:16 +0000</modified-date>
<types>
<type>portlet</type>
</types>
<tags>
<tag>social</tag>
<tag>profile</tag>
</tags>
<short-description>My Summary</short-description>
<long-description>My Summary</long-description>
<change-log>Initial Version</change-log>
<download-url>http://www.liferay.com/portlets/my-summary-portlet-5.2.2.war
</download-url>
<author>Rich Sezov</author>
<screenshots/>
<licenses>
<license osi-approved="true">MIT License</license>
</licenses>
<liferay-versions/>
</plugin-package>
</plugin-repository>

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

As you can see, the Software Catalog makes it easy for you to create a repository of your software. Users of Liferay can configure their Plugin Installers 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 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.

How can you do this? The Software Catalog is also available as a portlet. You can add it to any page on your web site through the Add Application menu. You will find the portlet in the Tools category.

Manually Creating A Software Catalog

If you do not wish to use the Control Panel to create your software catalog, you can create it manually by manually typing out the XML file that the Software Catalog section of the Control Panel would normally generate. Note that if you do this, you will not be able to use the Software Catalog portlet as 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.

If you still wish to use a text editor to create your software catalog, you can. 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_2_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 the Plugin Installer in your Control Panel 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.