12/10/2010

AlloyUI Tutorial Part 1 : Hello World & First Steps.

Part 1   Part 2   Part 3   Useful Links   Useful Literature

About AlloyUI

What is AlloyUI ? AlloyUI is the new and preferred way to create GUIs and GUI communication in Liferay6.
It offers a rich set of components, ready to be used by you. This allows to create GUIs in Liferay Portlets and Web Contents very fast and reduces the amount of backing bean code you have to program yourself.
It is built on top of a javascript library called YUI3.
If you want to know more, look here :
http://www.liferay.com/de/web/nathan.cavanaugh/blog/-/blogs/alloyui

Setup

How do you get a first AlloyUI example to run?

At first you need Liferay 6 - download the CE at
http://www.liferay.com/de/downloads/liferay-portal/overview.
Then it would be great for you to download the plugins SDK which you can use to easily create a blank portlet.
You can get it here:
http://sourceforge.net/projects/lportal/files/Liferay%20Portal/6.0.5/liferay-plugins-sdk-6.0.5.zip/download

Unzip the portal, unzip the plugins SDK and modify the build.properties to point to your tomcat installation.

Go to your plugins SDKs directory and into the folder "portlets".
Run create.bat "Hello World" hello-world to create your Hello World Portlet.

This all for the setup. Your Portlet is ready to be deployed.

First Steps

Change the liferay-portlet.xml.
Add the required javascript libraries to your portlets xml file like this:


<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 6.0.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_6_0_0.dtd">


<liferay-portlet-app>
<portlet>
 <portlet-name>hello-world</portlet-name>
 <icon>/icon.png</icon>
 <instanceable>true</instanceable>
 <header-portlet-css>/html/js/aui/aui-skin-classic/css/aui-skin-classic-all-min.css</header-portlet-css>
 <header-portlet-javascript>/html/js/aui/aui/aui.min.js</header-portlet-javascript>
 <footer-portlet-javascript>/js/main.js</footer-portlet-javascript> 
 <css-class-wrapper>hello-world-portlet</css-class-wrapper>
</portlet>
<role-mapper>
 <role-name>administrator</role-name>
 <role-link>Administrator</role-link>
</role-mapper>
<role-mapper>
 <role-name>guest</role-name>
 <role-link>Guest</role-link>
</role-mapper>
<role-mapper>
 <role-name>power-user</role-name>
 <role-link>Power User</role-link>
</role-mapper>
 <role-mapper>
 <role-name>user</role-name>
 <role-link>User</role-link>
</role-mapper>
</liferay-portlet-app>



Your portlet is now ready to execute some fine AlloyUI code ;)

For our first example, we will use the autocomplete Feature of AlloyUI:

At first, add a div to your portlet:

<div id="autoCompleteField"></div> 

This div we will later address within our AlloyUI code.
Then add the following AlloyUI code:


<script type="text/javascript" charset="utf-8"> 

AUI().use('aui-autocomplete', function(A) {

var people = [['Uncle Bob','Car Repairing'],['Dad','Finance'],['Mum','Cooking'],['Maria','Information Technology']];

var auto = new A.AutoComplete(
{
dataSource: people,schema: {resultFields: ['name', 'job']},matchKey: 'name',delimChar: ',',typeAhead: true,
minQueryLength:'3',contentBox: '#autoCompleteField'}

);
auto.render();
});
</script> 
We will go through it step by step:

At first we will create the data structure, that is used by the autocomplete feature:


[['Uncle Bob','Car Repairing'],
['Dad','Finance'],
['Mum','Cooking'],
['Maria','Information Technology']];

This you can replace later by JSP iteration. For now, we added some names with theier profession.
The next step is to create a new AutoComplete object and to configure it properly:


window.AC = new A.AutoComplete(
{
dataSource: people,
schema: { resultFields: ['name', 'job']},
matchKey: 'name',
delimChar: ',',
typeAhead: true,
minQueryLength:'3',
contentBox: '#autoCompleteField'
}
);
AC.render();

dataSource points to our javascript array.
schema maps the array to the internal autocomplete handling.
matchKey specifies the index the input field listens on.
minQueryLength specifies the length your query must have so that auto completion starts to work.

And that´s all for the first steps ... you now have your first AlloyUI component working:

If you liked this tutorial it would be very nice, if you could click on some of the google ads you see on the right side. It helps me run this block and motivates me ;)

If you have any questions, feel free to leave a comment.