Friday, February 14, 2014

Introduction to Liferay Custom Attributes/Custom Fields

Introduction:

Liferay have come up with custom attributes which help us to add additional fields to existed models/entities.

This will help us to add some more additional attributes to existed entities so that we can meet your requirements.

This pretty easy we can configure from Admin screen in Liferay Portal.

Liferay have given this feature to many existed entities such as User, Organization, Role and Site many more.

The following screen shows you liferay entities that liferay support custom attributes


What is use of custom attributes?

Custom attribute the way to add additional attributes to existed portal entities so that in our real requirement if any fields you wanted then you can add.

Example:

For User registration you may need special field but existed user table may not have that fields then you can create new filed so that you can use in user registration.

How can I create Custom attribute/Custom fields?

This is pretty easy and simple you can login as admin and go to control panel there you can see the custom fields link as soon as you click you can navigate to custom fields screen.

Where can I see custom fields?

It depends and for a user we can see in custom fields section there you can find all custom fields and you can also use in development. Liferay have UI tags for to show custom files through program.

Access Custom fields in program

User Custom Fields

user.getExpandoBridge().getAttribute("attirbute-key")

Role Custom Fields

role.getExpandoBridge().getAttribute("attirbute-key")


Site Custom Field

site.getExpandoBridge().getAttribute("attirbute-key")


Another way to access Custom Attributes


com.liferay.portlet.expando.model.ExpandoValue expandoObiect=ExpandoValueLocalServiceUtil.getValue(classNameId, tableName, columnName, classPK)
String fieldValue=expandoObiect.getData();


Example to Get User Custom Attribute


com.liferay.portlet.expando.model.ExpandoValue expandoObiect=ExpandoValueLocalServiceUtil.getValue
(ClassNameLocalServiceUtil.getClassNameId(User.class), "CUSTOM_FIELDS", "Mobile Number", curUser.getUserId())


Note:

You can see the ExpandoTables and ExpandoValue entity related classes in portal source code

The following are some of the important java classes


ExpandoTableLocalServiceUtil
ExpandoValueLocalServiceUtil
ExpandoValue
ExpandoTable


Note:

 Attribute key is field name this is we will give as input when we create custom filed

Display Custom Attribute as Input Fields

Liferay have Liferay UI tag library one of the tag is custom attribute tag form this we can show custom attribute as input filed. This will help us update/add new values to custom attributes

Note:

This tags we will use on JSP pages so we need to add Liferay UI tag library in the page


<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>


We have two tags


<liferay-ui:custom-attribute/>
<liferay-ui:custom-attribute-list />


<liferay-ui:custom-attribute/>

Custom attribute tag will display only one input files and it will take custom attribute name and respective model class as attributes

Tag Syntax


<liferay-ui:custom-attribute classPK="" name="" className=""></liferay-ui:custom-attribute>      


The following are the attributes for above tag

className(required = true):

The fully qualified name of the entity e.g. com.liferay.portal.model.User

classPK(required = true):

The primaryKey of the entity instance (or zero (0) if there is not currently an instance)

Name (required = true):

 The name of the specific attribute to render and its key of attribute we have given at the time of field creation as admin.

Editable:

It takes true or false values based on that we can edit the value in the input text box.

Label:

It is label for display filed it will take true/false.

Example:

Display User Custom Filed in JSP page


<%User user=themeDisplay.getUser();%>
<liferay-ui:custom-attribute
className="<%= User.class.getName() %>"classPK="<%= user!= null ? user.getUserId() : 0 %>"
editable="<%= true %>"
name="company-name"
label="true"/>


<liferay-ui:custom-attribute-list />

Custom attribute list tag display all custom fields for respective entity.

Tag Syntax


<liferay-ui:custom-attribute-list classPK="" className="">
</liferay-ui:custom-attribute-list>    
       

The following are the attributes for above tag

className(required = true):

The fully qualified name of the entity e.g. com.liferay.portal.model.User

classPK(required = true):

The primaryKey of the entity instance (or zero (0) if there is not currently an instance)

Name (required = true):

 The name of the specific attribute to render and its key of attribute we have given at the time of field creation as admin.

Editable:

It takes true or false values based on that we can edit the value in the input text box.

Label:

It is label for display filed it will take true/false.

IgnoreAttributeNames:

This will take attribute names that is you don’t want to display and its string value you need pass multiple values with COMMA separate.

Example:

Display User All Custom Fields in JSP page


<%User user=themeDisplay.getUser();%>
<liferay-ui:custom-attribute-list
className="<%= User.class.getName() %>"
classPK="<%= user!= null ? user.getUserId() : 0 %>"
editable="<%= true %>" label="true"/>


Update/Set the value to Custom Fields


Set User Custom Fields

user.getExpandoBridge().setAttribute("custome- attirbute-key ", "value");

Set  Role Custom Fields

role.getExpandoBridge().setAttribute("custome- attirbute-key ", "value");

Set  Site Custom Field

site.getExpandoBridge().setAttribute("custome- attirbute-key ", "value");



Example:


user.getExpandoBridge().setAttribute("company-name", "My Company");


Another way to add data/set value to Custom Fields


ExpandoValueLocalServiceUtil.addValue(classNameId, tableId, columnId, classPK, data);


Example:


ExpandoValueLocalServiceUtil. addValue (ClassNameLocalServiceUtil.getClassNameId(User.class), "CUSTOM_FIELDS", "Mobile Number", curUser.getUserId(),”90898990”)


Note:

You can see the ExpandoTable and ExpandoValue entity related classes in portal source code

The following are some of the important java classes


ExpandoTableLocalServiceUtil
ExpandoValueLocalServiceUtil
ExpandoValue
ExpandoTable


Search Data with Basis of Custom Fields

We can also perform search with basis of custom attributes

The following is simple search methods with custom attributes for User Entity


public static com.liferay.portal.kernel.search.Hits search(long companyId,
                        java.lang.String keywords, int status,
                        java.util.LinkedHashMap<java.lang.String, java.lang.Object> params,
                        int start, int end, com.liferay.portal.kernel.search.Sort sort)
                       

public java.util.List<com.liferay.portal.model.User> search(
                        long companyId,keywords, int status,
                        java.util.LinkedHashMap<java.lang.String, java.lang.Object> params,
                        int start, int end, com.liferay.portal.kernel.util.OrderByComparator obc)
                        throws com.liferay.portal.kernel.exception.SystemException


Example Search Users with basis of Custom Fields/Custom Attributes

Example: 1


LinkedHashMap userParams = new LinkedHashMap();
userParams.put("company-name", "vinculum");
boolean asc = true;
Sort sortOrderByAttribute = new Sort("lastName", Sort.STRING_TYPE, asc);
Hits hits = UserLocalServiceUtil.search(companyId, null, true, userParams, 0, 20, sortOrderByAttribute);
List<User> users =UserLocalServiceUtil.search(companyId, null,WorkflowConstants.STATUS_ANY,userParams, 0, 20,null);


Example: 2


LinkedHashMap userParams = new LinkedHashMap();
userParams.put("company-name", " vinculum ");
boolean asc = true;
Sort sort = new Sort("lastName", Sort.STRING_TYPE, asc);
Hits hits = UserLocalServiceUtil.search(companyId, null, true, userParams, 0, 20, sort);
List<User> users = new ArrayList<User>();
List<Document> hitsList = hits.toList();
for (Document doc : hitsList) {
            long userId = GetterUtil.getLong(doc.get(Field.USER_ID));
            users.add(UserLocalServiceUtil.getUserById(userId));
}



All observations I have done in Loferay 6.2 CE version and you can see similar things in lower version of liferay too and may be some changes we can expect in lower versions.

Author