Wednesday, December 10, 2014

Liferay Hook Plugin Development with Liferay IDE

  
Liferay hook Plugin is one of the Plugin type in liferay to customize liferay portal.
Hook have many capabilities so that we can customize liferay portal and its hot deployable plugins. Liferay Plugins SDK have support to develop hook plugins.

Please follow the articles before start this development.



We have many choices to start liferay development




In this article we are going to see hook development with Liferay IDE. Before start development we need to be ready with development environment that is using Liferay IDE.

Please follow the below articles to setup Liferay Development Environment with Liferay IDE



Liferay Hook Plugin Project Creation

Start your eclipse

go to File-->New-->Liferay Plugin Project

Once we click on new project it will open New Liferay Project Plugin Dialog window

Provides the Information as follows

Project Name: Sample

Project Display Name: Sample Hook

Check the Use Default Location Check box.

Build Type: ANT

Plugins SDK: Select your Plugins SDK( you already configured this when you setup development environment)

Liferay Runtime: Select your run time ( you already configured this when you setup development environment)

Plugin Type: Hook

The following screen shows the New Liferay Project Dialog



Once you fill the all the above information then click on Finish button then your Sample-hook project will be created.

The following screen shows Sample-hook project in the project explorer


Note:

Project Name always appended with Plugin type when we create any liferay project. In our case we just given Sample but finally project will be created with name Sample-hook. Now we just created Liferay Hook project and its just have project skeleton.

Deployment of Hook Plugin

As soon as we created hook project then respective build file will be appeared in the Eclipse ANT view. There we can see many ANT targets. Simply we have to double click on deploy target or we can simply double click on Project Name in the ANT view then it will execute deploy target then hook Plugin will be deployed into server. deploy is the default ant target for hook Plugin.

The following screen shows sample-hook ant targets in the Eclipse ANT view


Once we deploy the hook Plugin then we can see following message in server log view. When we see below message then hook is successfully deployed.

10:11:20,647 INFO [localhost-startStop-2][HookHotDeployListener:687] Registering hook for Sample-hook
10:11:20,651 INFO [localhost-startStop-2][HookHotDeployListener:814] Hook for Sample-hook is available for use

Note:

In General ant deploy is target for deploy the hook project.

Each liferay hook Plugin project have it own project ANT build file called build.xml in the root directory of project there all build process will be defined.

Anatomy of the Liferay Hook Project

When we created hook plugin through Liferay IDE it will create hook project with all required configuration files and its folder sturcture from here we can start our development as for our needs.

The following is general liferay hook plugin files and its structure.

Sample-hook/
   docroot/WEB-INF/src/
   docroot/
      META-INF/
        MANIFEST.MF
     WEB-INF/
       lib/
       liferay-hook.xml
       liferay-plugin-package.properties
       web.xml
build.xml

The following is Liferay Hook Project In the Liferay IDE project explorer


docroot/WEB-INF/src/ :

consist all Java source files and related resource files such as language properties and portal properties.

lib/ :

consist required libraries for project.

liferay-hook.xml :

This is hook configuration file and its consist all predefined configuration tags and it will be available in liferay-hook_6_x_x.dtd file. Here we will define what we should customize in the portal.

A sample “liferay-hook.xml ” with some configuration


liferay-plugin-package.properties :

its common to all liferay plugins projects and here we will defined all properties related to project such as build number, version ant many which we can find from liferay-plugin-package_6_2_0.dtd file.

Example “liferay-plugin-package.properties” file


web.xml :

Its general deployment description for liferay hook project.

buil.xml:

This is ant build file to defined project build process its internally called another build files from plugins SDK to provide different ANT targets.

Example build.xml file as Follows



Liferay Hook Project Development with ANT+Plugins SDK

In the above we have created liferay hook project using Liferay IDE now we will create same project with ANT command line interface.

Liferay Plugins SDK provides ANT command line interface to create liferay Plugin projects.

Before start this we need to be ready with Liferay Plugins SDK+ANT development environment.


Once you ready with Plugins SDK+ANT environment then open command prompt or Linux terminal based on your Operating System.

From command prompt/terminal navigate to hooks directory( /liferay-plugins-sdk-6.2/hooks )

Now issue the following command

Linux and Mac OS X

./create.sh Sample "Sample"

In Windows

create.bat Sample "Sample"

A BUILD SUCCESSFUL message from ANT tells you there’s a new folder named Sample-hook inside the Plugins SDK’s hooks folder.

Project Name always appended with Plugin type when create any liferay project. In our case we just given Sample but finally project will be created with name Sample-hook

Once project is created then navigate to project root directory(/liferay-plugins-sdk-6.2/hooks/Sample-hook) then issue following ANT target then project will be deployed in the server.

ant deploy

Once we deploy the hook then we can see following message ,then hook is successfully deployed.

Hook for Sample-hook is available for use

Note:

well we have successfully created liferay hook Plugin project and here still we did not customize anything of portal. We will see how to customize liferay portal with this hook project in future articles. We simply do some configuration in liferay-hook.xml then it will change the portal behavior as for our need.

Follow the below articles to know more about Different Liferay Hook Plugins


Author
Meera Prince
Liferay Contributor of The Year 2014
Liferay Top Contributor Award Winner 2013

Saturday, December 6, 2014

Liferay Dockbar Custom User Notifications

  
Liferay 6.2 added new feature in dockbar. One of the feature is user notifications already well aware of dockbar in liferay. Liferay dockbar consist many options it will be appear once user login into the liferay and the options are based on user role.

The following screen shows Liferay Dockbar after user login into the portal


Assumption:

Assume portal administrator wants to send notification to all portal users when portal got new features.

This just example scenario we can make it better approach to send notifications but for understanding purpose i just took this assumption.

One of the Liferay Dockbar feature is User Notification display. This will be display user notifications and relevant messages with respect to users. If some document is added then we will notify to user about document is added. Some new blog post was added then we will notify to the user.

To Display User Notification in the Dockbar we need to deploy the Notifications Portlet then only we can see User Notifications in the dockbar.

Notification portlet available for Community Edition(Notifications CE) and Enterprise Edition(Notifications EE) in Liferay Market Place.

You must download portlet and deploy the portlet into your current Liferay Portal Instance. When you download make sure portlet version.

The following is Market Place Dowload URL (Notifications CE.lpkg)


You can also download from following URL



Once you downloaded and deploy the portlet, then you can see Notification Feature in the dockbar as like following screen.



Liferay have given flexibility to add custom notifications and we can show these notification in the Dockbar using Notification Portlet with respect to each login user.

Custom User Notification Implementation:

Liferay already have given some API classes and mechanism to implement custom notification and we can show in the dockbar. We need follow some set of steps to implement custom notifications.

In our portlet development we may get requirement to send notification to users now we will see how to implement custom user notifications.

Steps to Implement it in the Portlet Development
  1. Implement Custom User Notification Handler Class
  2. Define User Notification Definitions in XML file
  3. Configure User Notification Handler Class and User Notification Definitions Xml file in liferay-portlet.xml file
  4. Add user notifications using UserNotificationEventLocalServiceUtil
Implement Custom User Notification Handler Class

First we need to Implement Custom User Notification Handler class and it will take care of adding notifications in the dockbar. We implement logic like it will fetch respective user notifications and add html markup in the dockbar. Here we can design html to show the notification in the better way.

We should implement “UserNotificationHandler” interface for our Custom User Notification handler class.

Instead of directly implement “UserNotificationHandler” interface we can extends “BaseUserNotificationHandler” class so that we need not to implement all methods.

Do Design Html to add to dockbar we mainly implement the “getBody” and “getBodyTemplate” methods.

“getBodyTemplate” We will design Notification Template and “getBody” we will fill the template with actual dynamic content.

The dynamic content will be getting from payload JSON object that will prepared at the time of user notification added in the database.

The example Implementation As follows


public class DockBarUserNotificationHandler extends BaseUserNotificationHandler {
public static final String PORTLET_ID = "dockbarnotificationaction_WAR_DockBarCustomNotificationportlet";

public DockBarUserNotificationHandler() {

setPortletId(DockBarUserNotificationHandler.PORTLET_ID);

}
@Override
protected String getBody(UserNotificationEvent userNotificationEvent,
ServiceContext serviceContext) throws Exception {
JSONObject jsonObject = JSONFactoryUtil
.createJSONObject(userNotificationEvent.getPayload());
//long userId = jsonObject.getLong("userId");
String notificationText=jsonObject.getString("notificationText");
String title = "<strong>Dockbar Custom User Notification for You</strong>";
String body = StringUtil.replace(getBodyTemplate(), new String[] {
"[$TITLE$]", "[$BODY_TEXT$]" },
new String[] { title, notificationText });
return body;
}
protected String getBodyTemplate() throws Exception {
StringBundler sb = new StringBundler(5);
sb.append("<div class=\"title\">[$TITLE$]</div><div ");
sb.append("class=\"body\">[$BODY_TEXT$]</div>");
return sb.toString();
}
}

Define UserNotification Definitions in XML file

This is very important step that we will define the notification information in the xml file. We have set of predefined tags to define notifications. We need to follows the “liferay-user-notification-definitions_6_2_0.dtd” for better understanding about notification tags. We have different type of Notification like Website and Email. Web Site type notification will be displayed in the dockbar.

We need to distinguish each notification by its Notification Type in our example we will distinguish by out custom PortetID.

The following is Example Notifications Configuration


<user-notification-definitions>
<definition>
<notification-type>${com.meera.notification.DockBarUserNotificationHandler.PORTLET_ID}</notification-type>
<description>receive-a-notification-when-administrator-triggered</description>
<delivery-type>
<name>email</name>
<type>${com.liferay.portal.model.UserNotificationDeliveryConstants.TYPE_EMAIL}</type>
<default>false</default>
<modifiable>true</modifiable>
</delivery-type>
<delivery-type>
<name>website</name>
<type>${com.liferay.portal.model.UserNotificationDeliveryConstants.TYPE_WEBSITE}</type>
<default>true</default>
<modifiable>true</modifiable>
</delivery-type>
</definition>
</user-notification-definitions>

For better understanding about notification configuration follow the micro-blogs portlet notification xml file


Configure Custom User Notification Handler Class and User Notification Definitions Xml file in “liferay-portlet.xml” file

Now we need to configure Custom User Notification Hander class and User Notification xml file in the our custom portlet “liferay-portlet.xml” file.
We will use two tags “<user-notification-definitions/>” and “<user-notification-handler-class/>”.We need to provide fully qualified path as value for the xml tags.

The following is configuration


<portlet>
<portlet-name>dock-bar-notification-action</portlet-name>
<icon>/icon.png</icon>
<user-notification-definitions>com/meera/notification/dockbar-user-notification-definitions.xml</user-notification-definitions>
<user-notification-handler-class>com.meera.notification.DockBarUserNotificationHandler</user-notification-handler-class>
<header-portlet-css>/css/main.css</header-portlet-css>
<footer-portlet-javascript>/js/main.js</footer-portlet-javascript>
<css-class-wrapper>dock-bar-notification-action-portlet</css-class-wrapper>
</portlet>

Add user notifications using “UserNotificationEventLocalServiceUtil”

We have to add User Notification using UserNotificationEventLocalServiceUtil so that notification will be added in the database.

Where ever particular information should notify to the user then we will use UserNotificationEventLocalServiceUtil to add notification.

Here the main important is we have to create Payload JSON object and fill with required information and this information will be gathered in the Custom User Handler “getBody” class to prepare notification with dynamic content.

Generally we will add notification in the portlet action class or some other business logic writing area we may need to add notification.

The following is example code.


public void sendUserNotification(ActionRequest actionRequest,
ActionResponse actionResponse) throws IOException, PortletException {
try {
List<User> users = UserLocalServiceUtil.getUsers(0,
UserLocalServiceUtil.getUsersCount());
ServiceContext serviceContext = ServiceContextFactory.getInstance(actionRequest);
String notificationText = ParamUtil.getString(actionRequest,"notifciationText");
for (User user : users) {
JSONObject payloadJSON = JSONFactoryUtil.createJSONObject();
payloadJSON.put("userId", user.getUserId());
payloadJSON.put("notificationText", notificationText);

UserNotificationEventLocalServiceUtil.addUserNotificationEvent(
user.getUserId(),DockBarUserNotificationHandler.PORTLET_ID,
(new Date()).getTime(), user.getUserId(),payloadJSON.toString(),false, serviceContext);
}
} catch (Exception e) {
e.printStackTrace();
}
}

Notifications are added in the “UserNotificationEvent” table.

Well done we have completed implementation part now we can deploy portlet can see the notifications.

Download Source Code and Portlet war file from below URL


Usage of Portlet

Download Notification Portlelt from market place or above specified URL and deploy into portal.

Download “DockBar Custom User Notification” from above URL there you can see “DockBarCustomNotification-portlet-6.2.0.1.war” file and Source code.

If you want use war file just place in liferay deploy directory then it will be deployed. From source also you can deploy it.

Now drag the portlet in the page,portlet name is “DockBar Custom User Notification” and available in “Sample” Category.

Once you add portlet to page you can see text area there enter some notification text then click on Notify button then notification will be send to all portal users.



Now notification is visible in each user dockbar.



Note:

This is not exact real time use case just for understanding purpose i have took the scenario and i am fetching all portal users, if your portal users are more then it take time to complete request so you can change logic in portlet cation class.

Reference Links:



Author
Meera Prince
Liferay Contributor of The Year 2014
Liferay Certified Professional Developer 
Liferay Top Contributor Award Winner 2013

Thursday, December 4, 2014

Introduction to Liferay Hook Plugins

  
Liferay offered different ways to extend and customize liferay portal. Liferay have come up with mechanism called plugins to extend and customize liferay portal.

Liferay Plugin environment offers different types of plugins based on their contextual use and what exactly they act upon liferay portal. One of the Plugin type is HOOK.

In general meaning of hook is a piece or item which can give additional capability where we use it and it can easily add or removable item.

Liferay hook plugins are is part of Liferay Plugins SDK so we can use Plugins SDK to develop hook plugins. when we look into parent directory of Plugins SDK you can see hooks directory there all created plugins are resided

Liferay Hook Plugin

Liferay Hook Plugin is used to customize liferay portal. Hooks are hot deployable plugins so when we modify we need not to restart server to apply changes in the portal.

We can modify portal web resources such as JSP , JSPF, CSS, Java Scrip files, Language properties files,some of portal properties,customize actions, modify portal struts actions,portlet struts actions,overriding portal services,create servlet filters and create indexser post processors.

When we create any hook Plugin we need to know one important file called liferay-hook.xml configuration files.

Liferay-hook.xml files consist set of predefined xml tags and there we will defined all configuratiion so that portlet container modify the files according to this file.

Liferay-hook.xml tags and its description are available in liferay-hook_6_x_x.dtd file.

The main parent tags as below

<!ELEMENT hook (portal-properties?, language-properties*, custom-jsp-dir?,
custom-jsp-global?, indexer-post-processor*, service*, servlet-filter*,
servlet-filter-mapping*, struts-action*)>

We have following types of Hooks

JSP Hooks
Application Adopter Hooks
Custom Action Hooks
Portal Properties Hooks
Language Properties Hooks
Struts Action Hooks
Indexer Post Processor Hooks
Portal Service Hooks
Servlet Filter Hooks

JSP Hooks

When ever we want modify the portal jsp pages or existed portlet JSP pages then we will use JSP hooks.

Assume we want add some new fields or write some new text in create account JSP pages then we can do it from JSP hooks.

We can create JSP hooks using Liferay IDE or we can use Command Line Interface to create hooks.

Reference:


Application Adopter Hooks

Application adopter hooks are special types of JSP hooks and we can define scope to the customization.

Generally when we use JSP hooks then changes will be applicable to through out the portal but we need a requirement the changes should be specific to particular site or site template then we will use Application Adopter Hooks.

Application Adapters are used to Customizing Sites and Site Templates and the changes are applicable to site level. They are used for overriding JSPs.

Reference:


Custom Action Hooks

Hooks are useful for triggering custom actions on common portal events, like user login or system startup. The actions for each of these events are defined in portal.properties so we need to extend this file to create a custom action. Hooks make this a simple task.

Reference:


Portal Properties Hooks

Portal properties hook overriding the existing portal properties and Portal properties hook can modify the some of the portal properties not all the portal properties. The modifiable list of properties are specified in liferay-hook_6_x_x.dtd file.

If the properties are not listen in the liferay-hook_6_x_x.dtd file then we cannot modify it from portal properties hooks.Assume we want to modify login.events.pre ,login.events.post properties then we will use Portal Properties Hooks.

Reference:


Language Properties Hooks

Language Properties Hooks are used to overriding the existed portal language properties.
We can aslo add new properties and we can modify existing portal properties lets we want change some properties French language properties i.e. Language_fr.properties then we can create Language Properties Hooks to make the changes.

Reference:


Struts Action Hooks

Struts Action Hooks are used to adding or overriding struts action Java classes. We have portal struts actions and portlet struts actions. Struts Action Hooks can modify the both struts actions.

Reference:


Indexer Post Processor Hooks

Indexer Post Processor Hooks can modify search summaries , indexes and queries in the existed portal.

We can create new Indexer post processor to create new search summaries lets say if want perform search on all fields of User then we can do it by Indexer Post Processor Hooks

Reference:


Portal Service Hooks

portal service hooks are used to modify the existed portal services. When we want overriding the existed portal services then portal service hooks are best choice. Lets say we want to modify the User services then we can use portal service hooks.

Reference:


Servlet Filter Hooks

Servlet filter hook: Servlet filters allow you to pre-process requests going to a servlet and post-process responses coming from a servlet. As server requests are received that match URL patterns or match servlet names specified in your servlet filter mappings, your specified servlet filters are applied. Hook elements servlet-filter and servlet-filter-mapping have been added to liferay-hook.xml so you can configure your servlet filters.

Reference:


Important Points

Liferay Hook plugins are hot deployable so we can easy deploy and undeploy it without restart servers the changes will be applied.

When we want customize liferay portal hooks are best choice and if it not possible form hook then only we should prefer some other choices like ext plugins.

Hooks plugins have xml configuration file liferay-hook.xml and it consist of predefined tags and these tags information available in liferay-hook_6_x_x.dtd there all tags are defined and we should use specified tags.

Liferay hook plugins are is part of Liferay Plugins SDK so we can use Plugins SDK to develop hook plugins.

Author
Meera Prince
Liferay Contributor of The Year 2014
Liferay Certified Professional Developer 
Liferay Top Contributor Award Winner 2013

Subscribe to: Posts ( Atom )

Recent Posts

Recent Posts Widget

Popular Posts