Developing and Publishing Apps
Let’s jump right in with an example. In this section, we’ll walk you through the creation and publication steps (but we won’t actually publish the app on the Marketplace, since this example app isn’t very useful!). After walking through this, you should understand how Marketplace App development typically occurs.
Develop a Sample App
Before you can publish anything, you first have to create (develop) an app! Apps are nothing more than collections of individual plugins, so the first step in development an app for the Marketplace is to develop the functionality in the form of one or more Liferay plugins. To create a sample app (which will consist of a single portlet), follow the detailed instructions in the Portlet Development chapter of this guide. After creating and deploying your sample app, return here to continue.
In the real world, apps usually consist of multiple components (e.g. multiple
.war file plugins), are spread across multiple plugin types, and present non-trivial functionality which in many cases requires some configuration. How these advanced tasks are dealt with is out of scope for this section, but some tips and considerations for Marketplace development can be found later in this chapter.
Specify App Packaging Directives
When publishing your app, each plugin you upload is packaged into one or more packages for each Liferay release you intend to support. When you upload your plugins to the Liferay Marketplace, your app is scanned, and the embedded packaging directives you have specified are extracted and used to create different downloadable packages of your app for different Liferay releases. You must insert this information into each plugin in your app before you can publish it to the Marketplace.
The packaging directives are related to the Liferay releases with which your app is compatible. In order to specify which release of Liferay your app is compatible with (and therefore which packages should be created for eventual download on the Marketplace), you first need to understand how Liferay releases are named and how they relate to the underlying Liferay release version. Details can be found in the Liferay User Guide. Accordingly, Liferay 6.2 CE GA1 is designated as version
6.2.0. CE GA2 is then
6.2.1, and so on. Liferay 6.2 EE GA1 is designated as
6.2.10. EE versioning follows a slightly different policy given then presence of fix packs and service packs, so 6.2 EE GA2 will be
For each plugin that makes up your app, packaging directives must be placed in the
liferay-plugin-package.properties file (located in the
WEB-INF/ directory of your plugin’s
.war file). Within this file, you must specify a comma-separated list of Liferay releases with which your app is compatible and for which packages should be generated using the
liferay-versions keyword. Marketplace will create packages that contain your plugins based on these packaging directives (and will intelligently group them together as each plugin is uploaded). You should specify CE versions first, followed by EE versions, using this form:
EE are replaced with the corresponding Liferay Releases with which your app is compatible).
Note: If your app is compatible with both CE and EE, you must specify a set of versions for both CE and EE releases. If you only specify compatibility with CE, then your app will not be compatible with (and will fail to deploy to) any EE release.
For example, to specify that a particular plugin in your app is compatible with Liferay 6.1 CE GA3 (and later), and 6.1 EE GA3 (and later), add this line to your
This means that the app works with any 6.1 CE release starting with CE GA3, and and 6.1 EE release starting with EE GA3. Marketplace will create two packages, one that is compatible with the 6.1 CE GA3 release and later, and another that is compatible with 6.1 EE GA3 release and later.
Note: Any CE or EE versions you include in your packaging directives must be terminated with a version using the
+ symbol. This ensures that your app will be deployable onto future versions of Liferay (but does not guarantee your app will work in future versions). So,
liferay-versions=6.1.1,6.1.2 will not work, but
liferay-versions=6.1.1,6.1.2+ will work. Similarly,
liferay-versions=6.1.2+,6.1.30,6.1.31 will not work (as the EE versions are not properly terminated), but
liferay=versions=6.1.2+,6.1.30,6.1.31+ will work.
Here are some additional examples:
# works with Liferay 6.1 CE and EE GA3 and later (NOT compatible with 6.1
# CE or EE GA2). This is most likely what you want to use.
# works with Liferay 6.1 CE GA2, GA3, and GA5 (but not GA4), and EE GA2
# and later
# works with Liferay 6.1 EE GA3 and later (NOT compatible with CE)
You may find it advantageous to implement one of your app’s plugins in multiple ways, customizing that plugin for different Liferay releases. We’ll illustrate this with an example.
Example App: Using Different Versions of a Hook
Suppose your app consists of two plugins: a portlet and a hook. The portlet uses standard API calls that work on all Liferay 6.1 releases. Your hook, on the other hand, needs to interact with EE GA3 differently than it does with CE GA3, because you want the hook to take advantage of an exclusive EE feature. For your app, how do you provide one version of your hook plugin for EE and another version of it for CE, while applying your portlet plugin to both EE and CE?
It’s easy. In this case, you’d specify versions
liferay-versions=6.1.2+,6.1.30+ for your portlet plugin, indicating that it is compatible with CE GA3 and later, and EE GA3 and later. As for your hook plugin, you’d create and build two versions of it, one version of the hook to use with Liferay EE and the other version of the hook to use with Liferay CE. You’d specify
liferay-versions=6.1.30+ for your EE hook and
liferay-versions=6.1.2+ for your CE hook. The EE hook would work exclusively with EE GA3 and later, while the CE hook would work exclusively with CE GA3 and later. You might think that it’s difficult to arrange the packaging for an app that has plugins targeted to different Liferay releases, but it’s easy. Marketplace takes care of it based on the
liferay-versions values you specified for each plugin. We’ll talk about that next.
Marketplace Packages Your App’s Plugins
When you upload your app’s plugins, as demonstrated later on in this chapter, you’ll notice that Marketplace groups them into separate packages based on the respective releases each plugin supports. Marketplace copies a plugin into each of the release packages corresponding to its list of
liferay-versions values. If Marketplace cannot verify the version of Liferay the plugin supports, it rejects the plugin. For example, if you specify
liferay-versions=1.0.0+ for your plugin–perhaps because you are confident it can work on any Liferay release–Marketplace will likely reject it, because it doesn’t know of a
1.0 release of Liferay. So take care in specifying the Liferay version information for each your app’s plugins.
Now that you’ve developed your app and specified its packaging directives, it’s time to get it to the Marketplace!
Establish a Marketplace Account
Before you can publish anything to the Marketplace, you must first have an account on liferay.com. If you do not have an account, visit http://liferay.com and click Register in the upper-right corner of the screen. Once you have registered, you can visit the Marketplace at http://liferay.com/marketplace. The Marketplace home page is shown below:
This is the front page of the Marketplace and is where users go to find new and interesting apps. You’ll visit here often during the course of development, so it might be a good idea to bookmark it now.
You can publish Marketplace apps as an individual or as part of a company. Before you can submit apps to the Marketplace, you must register yourself as an app developer. It’s easy. Simply click the link Become a Developer in the Marketplace column on the left. You’re now in the Marketplace registration wizard. If you’re registering with a company and the company is already registered, you can search for it from these Marketplace registration screens and request to join the company in publishing apps to the Marketplace. On completing the Marketplace registration, Liferay sends you an email confirming your acceptance as a Marketplace Developer–Congratulations!
Now that you’re a Marketplace Developer, your liferay.com App Manager provides options for adding new apps and viewing your published apps. Your App Manager is accessible from your user profile page. Let’s go there now. In the upper right corner on liferay.com select your name → User Profile.
Your profile page contains links to often-used functionality of liferay.com, including app creation and management. There are several links on the left of your home page, including one called App Manager. This link allows you to manage the apps that you have for either personal or company use and to manage the apps that you or your company have developed. You’ll use this page heavily, so a bookmark would be useful here. Click App Manager to visit this page.
You’ll notice three tabs across the top:
Purchased: This shows apps you have personally purchased, and those apps that have been purchased on behalf of companies you are associated with.
Apps: This shows apps you have personally published.
Add an App: This screen begins the process of publishing a new app.
Since you have not purchased or published any apps, the first two tabs are likely empty. Let’s get publishing!
Upload (Publish) your App
To begin the process of publishing your app, click Add an App. A form appears, allowing you to fill in your app’s details.
Initial App Details
The first step is to enter the basic details about your app.
This screen allows you to enter basic details about the app you are publishing.
App Owner: Choose to whom the app “belongs” once it is uploaded–either yourself (personal) or a company. If you wish to publish your app on behalf of your company, but your company does not yet have a Marketplace profile, you can enter the company name in the Company Name field. If you are a representative of your company, you can register your company by clicking the Register My Company link.
Publishing on behalf of yourself is the default. When you publish on behalf of yourself, the app appears in your App Manager → Apps list, and your name appears in the Marketplace as the Publisher/Author. You are the only one who can manage this app (add new releases, new versions, edit details, etc).
Publishing on behalf of a company effectively hands the keys over to the admins of the company. The app only appears on the company’s App Manager → Apps list. In addition to yourself, company admins can manage this app (add new releases, new versions, edit details, etc). The app appears to be authored/developed by the company, not you personally. It also appears on the company’s public profile page under its list of apps.
Name: The name of your application. Arguably the most important detail of your app, the name of your app should be a good title that conveys the function of the App but is not overly wordy or misleading. Choosing a good name for your app is key to its success, so choose wisely! See the Marketplace Considerations chapter for more guidance on how to pick good names. Do not include versions in the title unless it is a vital part of the name, for example Angry Birds 2: More Anger. Each app on the Marketplace must have a unique name.
Description: Like the name says, this is a description of your app. You can put anything you want here, but a good guideline is no more than 4-5 paragraphs. This field does not allow any markup tags or other textual adornments–it’s just text.
Icon: The icon is a small image representation of the app. See the Marketplace Basics section of this chapter for detailed requirements for icons.
Screen Captures: You can supply multiple screenshots of your app in action. The screenshots you upload here are displayed when your app is viewed on the Marketplace, using a carousel of rotating images. See the Marketplace Basics section of this chapter for detailed requirements for screen captures.
Category: Choose the Marketplace category that most accurately describes what your app does. Users looking for specific types of apps will often browse categories by clicking on a specific category name in the main Marketplace home page. Having your app listed under the appropriate category will help them find your app.
Developer Website URL: This is a URL that should reference the web site associated with the development of the app. For open source apps, this typically points at the project site where the source is maintained. For others, links to a home page of information about this app would be appropriate.
Support URL: This is a URL that should reference a location where purchasers or users of the app can get support for the app.
Documentation URL: What better way to showcase the amazing capabilities of your app than to have a live, running version of it for potential buyers to see and use? This field can house a URL pointing to exactly that.
Source Code URL: If you’d to provide a link to the source code of your app, do so here.
Labs: You can denote an app as experimental by flagging the appropriate box.
Security: If your app does not use Liferay’s PACL Security Manager, flag the appropriate box. Otherwise, make sure to enable the security manager in your app by including the setting
security-manager-enabled=true in your
Tags: A set of descriptive words that categorize your app. These tags are free-form and can help potential purchasers find your app through keyword searches, tag clouds, and other search mechanisms. You can click on Suggestions to let Marketplace suggest some tags for you based on the data you’ve already entered. Click Select to select from existing tags, or you can manually type in new tags. See the Marketplace Basics section of this chapter for detailed requirements for tags.
EULA: You can either use the default end user license agreement or provide your own. There’s a link to the minimum terms which custom EULAs must satisfy.
Liferay Only: If you’re publishing a CE-only or EE-only app, select CE Only or EE Only in the Product Type dropdown selector. If you’re providing an app that runs on both CE and EE, just flag the Liferay EE Plugin checkbox. If you’re uploading a bug fix or would like to replace a previous version of your app, specify the app entry IDs of the apps to be replaced by the new app in the Supercedes App Entry IDs field.
Make up some sample data to use during this example, and enter it into the form. Once you have entered all your app’s details, click Next to move on to the next screen.
Upload Files (Plugins) for your App
On this screen, you must specify the version of your app and upload its plugin files. Review the guidance in the What is a version section in this chapter to choose a good version specifier and enter it here. For our example, since this is the first version, enter
Then you must upload the different sets of plugin files (variations) to support different Liferay versions. You must upload at least one plugin file before advancing beyond this screen. So, click the Browse button, and select the plugins that make up your app. Each time you add plugins to the list, they automatically begin uploading and their compatibility information is scanned (read the previous sections in this chapter to understand what compatibility information is read from your plugins).
Figure 12.5: Specify a set of files for each version of Liferay Portal you wish to support.
As a more complicated example, let’s consider an app that consists of a hook and a portlet. The portlet works across all Liferay releases, but the hook is built separately for CE and EE. Therefore, you would upload 3 plugins that make up the app: 1 portlet plugin for all releases, 1 hook plugin for CE, and 1 hook plugin for EE. Once the files are uploaded, a check mark appears next to each plugin, and the plugins are displayed based on their compatibility information.
This indicates that the files were successfully uploaded. Notice that the portlet plugin was automatically copied for use in both the EE and CE variations, even though you only uploaded the portlet plugin once. Click Next to advance to the final screen.
Preview and Submit Your App
Whenever you make a change (app details, adding files, adding new versions), you always wind up at a Preview screen. This allows you to preview your app as it will appear in the Marketplace, so you can confirm your changes.
For this example, review the information. Is it as you expect? If not, click Edit to go back and continue making changes until you are satisfied.
Once you are satisfied, click Submit for Review. If you’re walking through this example on Liferay’s Marketplace, don’t do it, since this is only an example app. The next section describes what happens when you submit apps or app changes.
The Review Process
When you submit apps to the Marketplace, they are reviewed by Liferay Marketplace staff to ensure that your app meets the minimum standards described in the above Requirements section of this chapter.
Each of the following changes require a review by Marketplace staff before the change is published to the Marketplace:
- Submitting a new app
- Changing details of an app (for example, changing the description or the screenshots)
- Adding a new package (set of files) to an existing app, in order to support more Liferay releases
- Adding a new version of an existing app
While your submitted change is under review, you can view the status of your change by visiting Home → App Manager → Apps. You can also cancel your submission by clicking Cancel Submission on the Preview screen for each app.
Once your app is approved by Marketplace staff, congratulations! You will receive an email confirmation and at that moment, your app is available on Marketplace. The app is also shown on your public Profile page, which lists all apps that you have personally developed and published.
If your app is rejected, an email will be sent to the email address associated with the app, along with a note explaining the reasons for rejection. At that point, you can make the requested changes, and re-submit the app for approval.
Now that you have successfully published your first app, you’ll likely get all kinds of feedback from users and yourself about what’s right and wrong with it. In the next section, we’ll explore how to make changes once you have published your app.