2. Working with Liferay's Developer Tools
2.3. Developing Plugins Using Maven
2.3.8. Liferay Plugin Types to Develop with Maven
You can develop all Liferay plugin types with Maven: portlets, themes, layout templates, hooks, and Ext. Next, you'll learn how to create each plugin type using Maven, and we'll point out where each plugin's directory structure is different than if you created it using the Plugins SDK. We'll often refer to the previous sections for creating and deploying these plugin types in Maven using Liferay artifacts. We'll also reference sections of some other chapters in this guide, since they're still relevant to Maven developers: they explain how you develop each type of plugin regardless of development environment.
Let's start with portlet plugins.
2.3.8.1. Creating a Portlet Plugin
To create a Liferay portlet plugin project, follow the Creating Liferay Plugins with Maven section.
Tip: As you use Maven's Archetype tool to generate your portlet project, you can filter
on group ID liferay, or even the group ID/artifact ID combination liferay:portlet, to find the Liferay portlet archetypes more easily.
2.3.8.1.1. Anatomy
A portlet project created from the com.liferay.maven.archetypes:liferay- portlet-archetype has the following directory structure:
Liferay 6.2 Developer Guide Page 82 ‣ src/ ⁃ main/ • java/ • resources/ • webapp/ ‣ css/ ⁃ main.css ‣ js/ ⁃ main.js ‣ WEB-INF/ ⁃ liferay-display.xml ⁃ liferay-plugin-package.properties ⁃ liferay-portlet.xml ⁃ portlet.xml ⁃ web.xml ‣ icon.png ‣ view.jsp ‣ pom.xml
Maven creates the src/main/java/ directory automatically. It holds the portlet's Java source code (e.g., com.liferay.sample.SamplePortlet.java), and portlet-
plugin/src/main/webapp holds its web source code. If you've created any portlet plugins using the Plugins SDK, you might have noted it uses a different directory structure.
The following table illustrates the differences in location of the Java source and web source code for a Maven project and a Plugins SDK project:
Location Maven project Plugins SDK project
Java source src/main/java docroot/WEB-INF/src Web source src/main/webapp docroot
To view the full directory structure of a portlet developed by Ant, visit our Anatomy of a Portlet section in this guide.
2.3.8.1.2. Deployment
To deploy your portlet plugin, follow the instructions detailed above in Deploying Liferay Plugins with Maven.
Congratulations! You successfully created a Liferay portlet plugin using Maven.
2.3.8.1.3. More Information
For detailed information on creating portlet plugins, see Developing Portlet Applications. Next, let's run through a brief example for developing a theme plugin using Maven.
2.3.8.2. Developing Liferay Theme Plugins with Maven
Liferay 6.2 Developer Guide Page 83 introduction; shadows dance on the tapestry-covered wall, and Lenore II (your cat) is purring atop the mantle. Yes, you're passing this cold winter's night in grand style (in front of your computer, of course). Now imagine yourself sitting on a cold hard wooden chair inside an off- white cubicle with empty walls (you're still in front of your computer, of course). These two descriptions paint two very different pictures, but both describe what you're doing (sitting and computing). Changing the "scenery" of your portal sets the mood for your users. We'll show you how to develop your own theme plugin (i.e., your "scenery") using Maven so your portal has a lasting impression on anyone who visits.
2.3.8.2.1. Creating a Theme Plugin
Theme plugin creation is similar to portlet plugin creation. We'll start by assuming you already created the sample-parent-project and its pom.xml.
To create your Liferay theme plugin project follow the Creating Liferay Plugins with Maven section, making sure to select Theme as the plugin type.
Tip: As you use Maven's Archetype tool to generate your theme project, you can filter
on group ID liferay, or even the group ID/artifact ID combination liferay:theme, to more easily find the Liferay portlet archetypes.
2.3.8.2.2. Anatomy
A theme project created from the com.liferay.maven.archetypes:liferay- theme-archetype has the following directory structure:
• sample-theme/ ‣ pom.xml ‣ src/ ⁃ main/ • resources/ ‣ resources-importer/ ⁃ document_library/ ⁃ journal/ • articles/ • structures/ • templates/ ⁃ readme.txt ⁃ sitemap.json • webapp/ ‣ WEB-INF/ ⁃ liferay-plugin-package.properties ⁃ web.xml
‣ css/ * Optionally add to hold CSS customizations
Liferay 6.2 Developer Guide Page 84
‣ js/ * Optionally add to hold JavaScript customizations
‣ templates/ * Optionally add to hold template customizations
The src/main/webapp/ folder holds your theme's customizations. If you've ever created a theme plugin using Liferay IDE or the Plugins SDK, this folder is used the same way as the docroot/_diffs/ folder. For example, custom.css should go in
src/main/webapp/css/custom.css.
Here's a table describing the directory structure differences between themes created using Maven and themes created using the Plugins SDK:
Location Maven project Plugins SDK project
customizations src/main/webapp/ docroot/_diffs/
To view the directory structure of a theme developed by Ant, visit the Anatomy of a Theme Project section in this guide.
2.3.8.2.3. Theme POM
The theme plugin project POM has two additional properties:
• liferay.theme.parent: Sets the parent theme. You can define almost any WAR
artifact as the parent using the syntax groupId:artifactId:version, or use the core themes by specifying _unstyled, _styled, classic, or control_panel.
• liferay.theme.type: Sets the template theme language.
The default settings for the two theme properties look like this:
<properties>
<liferay.theme.parent>_styled</liferay.theme.parent> <liferay.theme.type>vm</liferay.theme.type>
</properties>
2.3.8.2.4. Deployment
To deploy your theme plugin, follow the instructions in the Deploying Liferay Plugins with Maven section.
Note: When you execute the package goal, a WAR file is created; it's just like the
Maven WAR type project. Simultaneously, the parent theme is downloaded and copied, and your theme's customizations are overlaid last. A thumbnail image of the theme is created and placed in the target directory. Its path is
target/[theme]/images/screenshot.png in your theme project.
2.3.8.2.5. More Information
For more information on Liferay themes and its settings, see Creating Liferay Themes and Layout Templates.
You successfully developed a Liferay theme using Maven. Find out about developing hook plugins next.
Liferay 6.2 Developer Guide Page 85
2.3.8.3. Developing Liferay Hook Plugins with Maven
Hooks are the optimal plugin type for customizing Liferay's core features. Creating a hook is almost identical to portlet plugin creation in Maven. Let's take a look.
2.3.8.3.1. Creating a Hook Plugin
To create a Liferay hook plugin project, follow the steps outlined in the Creating Liferay Plugins with Maven section, making sure to select Hook as the plugin type.
Tip: As you use Maven's Archetype tool to generate your hook you can filter on group
ID liferay, or even the group ID/artifact ID combination liferay:hook, to more easily find the Liferay portlet archetypes.
2.3.8.3.2. Anatomy
A hook project created from the com.liferay.maven.archetypes:liferay-hook- archetype has the following directory structure:
• hook-plugin/ ‣ src/ ⁃ main/ • java/ • resources/ • webapp/ ‣ WEB-INF/
⁃ lib/ * Optionally add to hold required libraries
⁃ liferay-hook.xml
⁃ liferay-plugin-package.properties
⁃ web.xml
‣ pom.xml
The hook-plugin/src/main/java/ directory holds the hook's Java source code (e.g., com.liferay.sample.SampleHook.java) and hook-plugin/src/main/webapp holds the hook's web source code. If you're familiar with creating hook plugins using the Plugins SDK, you probably noticed that Maven uses a different plugin directory structure.
The following table illustrates the differences in location of the Java source and web source code for a Maven project and a Plugins SDK project:
Location Maven project Plugins SDK project
Java source src/main/java docroot/WEB-INF/src Web source src/main/webapp docroot
To view the directory structure of a hook developed by Ant, visit the Anatomy of the Hook section of the Creating a Hook section in this guide.
Liferay 6.2 Developer Guide Page 86
2.3.8.3.3. Deployment
To deploy your hook plugin, follow the instructions from the Deploying Liferay Plugins with Maven section.
2.3.8.3.4. More Information
For detailed information on creating hooks, see Customizing and Extending Functionality with Hooks.
You're nearly a Maven expert now; you're able to create portlets, themes, and hooks. Let's round things out by learning to develop layout templates.
2.3.8.4. Developing Liferay Layout Template Plugins with
Maven
You can create layout templates to customize the display of portlets on your page and to embed commonly used portlets. In our introduction to themes, we described a nice scene where you're relaxing in a luxurious chair, computer in your lap, Lenore II (your cat) purring on the mantle above a dancing fire. Sounds nice, doesn't it? It would be, but the chair's too small, so your knees are up in the air when your feet are flat on the ground, and your laptop is balanced precariously on top of them. The fire is also surprisingly large for that fireplace. In fact, its flames are already licking at the bottom of the mantle--which is made of wood! Remember Lenore II, softly purring on the mantle? She's going to cook just like the original Lenore if we don't do something! But it's so hard to get out of this tiny chair. Someone save Lenore II!
"Tell this soul with sorrow laden if, within the distant Aidenn, It shall clasp a sainted kitten whom the angels named Lenore II--"
In memory of the late, now crispy Lenore II, let's create a layout template plugin with Maven.
2.3.8.4.1. Creating a Layout Template Plugin
To create a Liferay layout template plugin project follow the Creating Liferay Plugins with Maven section, making sure to select Layout Template as the plugin type.
Tip: As you use Maven's Archetype tool to generate your layout template project, you
can filter on group ID liferay, or even group ID / artifact ID combination liferay:layout, to find the Liferay layout template archetypes.
2.3.8.4.2. Anatomy
A layout template project created from thecom.liferay.maven.archetypes:liferay-layouttpl-archetype has the following directory structure:
• layouttpl-plugin/
Liferay 6.2 Developer Guide Page 87 ⁃ main/ • resources/ • webapp/ ‣ WEB-INF/ ⁃ liferay-layout-templates.xml ⁃ liferay-plugin-package.properties ⁃ web.xml ‣ sample-layout.png ‣ sample-layout.tpl ‣ sample-layout.wap.tpl ‣ pom.xml
There's a directory structure difference between plugin projects created using Liferay Maven archetypes and those created using the Liferay Plugins SDK. The following table illustrates this difference:
Location Maven project Plugins SDK project
Web source src/main/webapp docroot
To view the directory structure of a layout template developed by Ant, visit the Anatomy of a Layout Template Project section in this guide.
2.3.8.4.3. Deployment
To deploy your layout template plugin, follow the instructions detailed above in the Deploying Liferay Plugins with Maven section.
2.3.8.4.4. More Information
For detailed information on creating layout templates, see Creating Liferay Themes and Layout Templates.
You've passed your trial by fire (the cat thanks you), developing yet another plugin type with Maven. Way to go! In the next section we'll cover other Liferay-provided Maven archetypes.
2.3.8.5. Developing More Liferay Plugins with Maven
Did you think we covered all the available archetypes for developing Liferay plugins? The Liferay team has been busy expanding our archetype list, and we're proud to show you some additional plugins that you can create using Maven archetypes.
Check out these exciting archetypes that are available:
• Liferay ServiceBuilder portlets
• Liferay webs
• Liferay Ext
• JSF Portlet Archetype
• ICEFaces Portlet Archetype
• PrimeFaces Portlet Archetype
• Liferay Faces Alloy Portlet Archetype
Liferay 6.2 Developer Guide Page 88 In addition, there are some Maven goals Liferay has provided:
• DBBuilder - The build-db goal lets you execute the DBBuilder to generate SQL files.
• SassToCSSBuilder - The build-css goal precompiles SASS in your css; this goal has been added to theme archetype.
You now have plenty of archetypes at your disposal!
"But the chair whose violet lining with the lamp-light gloating o'er, Lenore II shall press, ah, nevermore!"
Lenore II didn't make it through the Maven section, but you did. You can develop all your Liferay plugins using Maven; there's a standard process for generating the archetypes and selecting your plugin options for each plugin type. You can then customize the archetype to your liking. Using Maven to develop plugins offers an easy and effective way to customize your Liferay Portal.
Are you wondering if we're going to make more terrible jokes that steal from classic poetry? Quoth the Maven, "Probably." Let's move on to exploring the differences between hot deploy and auto deploy, with respect to your plugins.