An unfamiliar UI can be tricky to navigate. Your users can feel as though they are lost in a jungle, wandering around aimlessly, desperately trying to get their bearings. The
liferay-ui tag library offers a helpful solution in the form of the
liferay-ui:icon-help tag. The Icon Help tag creates a handy tooltip UI. Tooltips are a useful way to communicate additional information to your users in a unobtrusive way. The tooltips render as an easy to identify question icon that informs the user through a informational pop-up on mouse over.
Now that you have a better understanding of the
liferay-ui:icon-help tag and all its informational powers, you can learn how to configure it to pack your user’s heads full of information!
Using the Liferay UI Icon Help Tag
The example here shows how to add and use the
liferay-ui:icon-help tag in the
view.jsp of a portlet. First, you need to reference the
liferay-ui taglib. The following steps show you how to do this:
Open your portlet’s
Add a directive to reference the
<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>
You can now use the
liferay-ui tags in your portlet! Follow these steps to add and configure the
view.jspof your portlet, add the
liferay-ui:icon-helptag at the bottom:
Now that you have your tag placed, you can add the
messageattribute is required and contains the text to display to users on mouse over.
messageattribute to the
liferay-ui:icon-helptag and give it the text you want to display for the tooltip:
<liferay-ui:icon-help message="Help, I'm trapped inside this icon!"/>
The message is supplied as a string at the moment. As this is not best practice, you should supply the message via a language key. You’ll take care of this next.
Creating a Language Key Hook for the Help Message
In order to supply the language key for the help message you will need to create a hook.
Follow the steps below to create the language key hook:
Goto File→New→Liferay Plugin Project.
Set the Project name as
help-message-language-hookand Display name as
Help Message Language Hook.
Set the proper SDK and runtime, select Hook for the Plugin type, and click Finish.
The skeleton for the hook is complete. Now you need to configure the hook to modify the existing language properties. In this case you’ll be modifying the English US language properties, but the process can be used to hook into any existing language properties file.
Right-click the language key hook you just created in the package explorer on the left and select New→Liferay Hook Configuration.
help-message-language-hookset as the Hook plugin project select Language properties for the hook type and click Next.
Leave the default Content folder and click Add.
Enter Language_en.properties for the property file, click OK and Finish.
docroot/WEB-INF/srcfolder of the
help-message-language-hookand open the
Language_en.propertiesfile in the
Add the following language key to the file and Save it:
help-trapped = Help, I'm trapped inside this icon!
Now that you have the language key defined you can update the tag to use it.
view.jsp, update the
liferay-ui:icon-helptag to look like the following code:
Redeploy the portlet, hover over top of the help icon. The help message now uses the language key you just created!
It’s important to note that the question icon for the
liferay-ui:icon-help tag shows wherever you put it in your
jsp. In other words, if you want it to be associated with a given UI element, you have to place it next to that UI element in the
jsp. For example, the figure below shows what the configuration above looks like when the
liferay-ui:icon-help tag is placed next to a default user icon:
Liferay Portal uses the
liferay-ui:icon-help tag to display tooltips for Control Panel items:
There you go! You can now arm your users with the information they need to better interact with your UI.