Friday, May 30, 2014

Liferay Search Container

Introduction:

Liferay have very build in UI components and we can simply use those UI components when we develop portlets.

Liferay Search Container is Liferay UI component to display data in Grid format and its containing pagination. This is simple JSTL tag we can use in JSP pages.

In the real time if we want display result in gird format with pagination then we will use search container and its JSTL tags.

As we know these are JSTL tags in Liferay UI section so we need to specify the respective tag URI in the JSP page so that we can use in JSP pages.

The following is URI declaration in JSP page


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


Liferay Search Container

Liferay Search Container tag has many features so that we can simply display data in Grid format and we can apply pagination.

Generally search container has configured with multiple other tags which are inside search container.

The following is combination of tags we should use all as I mention below and order also we need consider.

Search container declaration syntax


<liferay-ui:search-container>
<liferay-ui:search-container-results/>  
<liferay-ui:search-container-row>              
<liferay-ui:search-container-column-text/>
<liferay-ui:search-container-column-text/>     
</liferay-ui:search-container-row>
<liferay-ui:search-iterator/>
</liferay-ui:search-container>


Note:

In the above declaration each and every tag has its required and optional tag attributes and its valued we need to pass.

Search container required some other tags to display data in grid format.

<liferay-ui:search-container>:

Search container tag is root tag and it has different attributes

The following is some important attributes

iteratorURL :

This attribute is mandatory so that we need to pass the URL. This will represent when page nation happened then it will use this URL.

Generally iterator URL is simple render URL and one more important thing is we need maintain search container jsp page in iterator URL as request parameter otherwise after pagination it will go portlet default page irrespective of where your search container.

We also need maintain all search parameters and its values when we perform search

Example:

A simple iterator URL


<liferay-portlet:renderURL varImpl="iteratorURL">
       <portlet:param name="mvcPath" value="/html/jsps/view_all_students.jsp" />
</liferay-portlet:renderURL>


Iterator URL with Search Parameters:


<liferay-portlet:renderURL varImpl="iteratorURL">
<portlet:param name="firstName" value="<%= firstName %>" />
<portlet:param name="lastName" value="<%= lastName %>" />
<portlet:param name="studentAge" value="<%= String.valueOf(studentAge) %>" />
<portlet:param name="studentGender" value="<%= String.valueOf(studentGender) %>" />
<portlet:param name="studentAddress" value="<%= String.valueOf(studentAddress) %>" />
<portlet:param name="mvcPath" value="/html/jsps/student_search_container.jsp" />
</liferay-portlet:renderURL>


Empty Results Message:

If the data is not there then it will show the message we have given to this attribute

Header Names:

In the result required Column Header name we will pass as comma separated values.

Delta:

This will decide how many record for page.

Delta Configurable:

This will give the option to change Delta values after result renders in the JSP page means end User can change records display per page.

Finally Search Container Tag as follows


<liferay-ui:search-container
emptyResultsMessage="there-are-no-students"
headerNames="firstName,lastName,studentAge,studentGender,studentAddress"
iteratorURL="<%= iteratorURL %>
delta="20"
deltaConfigurable="true">
</liferay-ui:search-container>


Note:

There are many attributes you can see in respective TLD file for more details


<liferay-ui:search-container-results/>

Container result maintains the current records which display in page and this will be depends the on Delta value.

We need to assign the value to result attribute or result variable and it is List of objects.

Once we get total and result values we need to set those values to search Container.

The following is example:


<liferay-ui:search-container-results>
<%
total = StudentLocalServiceUtil.getStudentsCount();

results=StudentLocalServiceUtil.getStudents(searchContainer.getStart(), searchContainer.getEnd());

searchContainer.setTotal(total);
searchContainer.setResults(results);

%>
</liferay-ui:search-container-results>


We can also display same as follows

<liferay-ui:search-container emptyResultsMessage="there-are-no-students"
headerNames="firstName,lastName,studentAge,studentGender,studentAddress"
iteratorURL="<%=iteratorURL %>"
delta="20"
deltaConfigurable="true"
total="<%=StudentLocalServiceUtil.getStudentsCount()%>"
> 
<liferay-ui:search-container-results
results="<%= StudentLocalServiceUtil.getStudents(searchContainer.getStart(), searchContainer.getEnd()) %>"
/>
</liferay-ui:search-container>


The above two declarations are same.

Note:

In the search container we have some deafly variables like total, result and seachContainer so that we can directly use no need declare anywhere and make sure jsp scriptlet should be enclosed by tag.

Search container always maintain the start and end values based the delta values so we can use these values to get the records with that limit from the table and we will use it as result.

<liferay-ui:search-container-row>

Search container row represent the rows which are rendered in the page. This row need model object so that it will use the model object to render the data.

The following are some important attributes:

ClassName:

This attribute represent the Model Class Name.

Key Property:

This is generally a primary key column or primary Key setter property in model class. This will used to row identification.

Model Var:

Model var maintain the model object current instance so that we will use this object to get the data and display in the columns. For each row there is one instance and its values so we can display in columns.

The following is example:


<liferay-ui:search-container-row
className="com.meera.dbservice.model.Student"
keyProperty="studentId" modelVar="currentStudent">
</liferay-ui:search-container-row>


<liferay-ui:search-container-column-text/>

This will represent column in Grid. How many columns we want display   those many column-text tags should be declared and all these tags should be enclosed by search-container-row tag. So in each row it will display data in the columns and it will use Model object and Model Setter key property to display data.

The following are some impotent attributes

Name:

Name represents the column header name and we already we can specify the column header in search-container tag. If we specify name it will use as header for the column.

Propetry:

Its model class setter property so that it will use this property is used to fetch data from model object and display in the row column.

Value:

Values also used to display data in the column.

Href:

This will represent the row URL so that when we click row then it will navigate to specified URL.

Generally if we mode columns for row then we will specify the limited columns in the grid and when we click the row we will show full details in other page of complete row.

So we need create some render URL and carry some important data as request parameters to the Row URL. Make sure row URL creation enclosed by search container-row tag then only it will carry distinct values.

The following are the different delectation of column-text tag

Simple column text with property attribute


<liferay-ui:search-container-column-text
name="lastName" property="lastName" />


Simple column text get the data from model object for value attribute


<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="studentGender"
value='<%=currentStudent.getStudentGender()==1?"Male":"Female"%>'/>


We will display data between Tag

<liferay-ui:search-container-column-text name="Action">
<a href="">Delete</a>
</liferay-ui:search-container-column-text>

Simple column text with Row URL


<liferay-ui:search-container-row className="com.meera.dbservice.model.Student"
keyProperty="studentId" modelVar="currentStudent">

<liferay-portlet:renderURL varImpl="rowURL">
<portlet:param name="backURL" value="<%= currentURL %>" />
<portlet:param name="mvcPath" value="/html/jsps/display_student.jsp" />
<portlet:param name="studentId" 
value="<%= String.valueOf(currentStudent.getStudentId()) %>" />
</liferay-portlet:renderURL>

<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="firstName" property="firstName" />
</liferay-ui:search-container-row>


In the details display Page code as follows (/html/jsps/display_student.jsp)


<%
String redirect = ParamUtil.getString(request, "backURL");
long studentId = ParamUtil.getLong(request, "studentId");

Student selecteStudentObject = null;
if (studentId > 0) {
selecteStudentObject = StudentLocalServiceUtil.getStudent(studentId);
}
%>

<a href="<%=redirect %>">Back</a>

<br/><br/>
<%if(selecteStudentObject!=null){%>
<h3>The following are the selected Student Information</h3><br/>
Student Name:<%=selecteStudentObject.getFirstName()+"&nbsp;"+
selecteStudentObject.getLastName()%>
<br/>
Student Age:
<%=selecteStudentObject.getStudentAge() %><br/>
Student Gender:
<%=selecteStudentObject.getStudentGender()==1?"Male":"Famale"%>
<br/>
Address: <%=selecteStudentObject.getStudentAddress()%><br/>
<%}%>


Note:

In the row URL we need carry Current URL and it will use as Back URL in details page.

Container Column JSP

Some time we may need to include JSP page in the column instead of only text such scenario we have container-column-jsp so that we can include jsp page in the column.



<liferay-ui:search-container-column-jsp
align="left"
path="/html/jsps/student_address_details.jsp"/>


In the given JSP page we can get Row object from that we can fetch required data

Container Row Parameters

Some time we may need to maintain some required paramours for row then we will use following tag


<liferay-ui:search-container-row-parameter
name="rowURL"
value="<%= rowURL.toString() %>"/>


Column JSP page may as follows (/html/jsps/student_address_details.jsp)


<%@page import="com.meera.dbservice.model.Student"%>
<%@page import="com.liferay.portal.kernel.util.WebKeys"%>
<%@page import="com.liferay.portal.kernel.dao.search.ResultRow"%>
<%@ include file="init.jsp" %>
<%
ResultRow row = (ResultRow)request.getAttribute(WebKeys.SEARCH_CONTAINER_RESULT_ROW);
Student student = (Student)row.getObject();
String rowURL = (String)row.getParameter("rowURL");
%>
<%=student.getStudentAddress()%>


<liferay-ui:search-iterator/>

Search interator tag is iterates the result and pass the data to row.

Make sure this tag after end tag of container-row then only it can iterate the specified row. We need to pass search container object as attribute value. if we not pass then it will take default declared search container object that is searchContainer.


<liferay-ui:search-iterator searchContainer="<%=searchContainer %>" />



Note:

If change the search container reference variable in the tag then we need to pass that variable in search-iterator.

Complete Search Container Code.

I am taking StudentLiferayMVC portlet and we will display all students and when we click on row we show more details.

View all students JSP page (html/jsps/view_all_students.jsp)


<%@page import="com.meera.dbservice.service.StudentLocalServiceUtil"%>
<%@page import="javax.portlet.PortletURL"%>
<%@ include file="init.jsp"%>
<liferay-portlet:renderURL varImpl="iteratorURL">
<portlet:param name="mvcPath" value="/html/jsps/view_all_students.jsp" />
</liferay-portlet:renderURL>
<a href="<portlet:renderURL />">&laquo;Home</a>
<div class="separator"></div>
<liferay-ui:search-container emptyResultsMessage="there-are-no-students"
headerNames="firstName,lastName,studentAge,studentGender,studentAddress"
iteratorURL="<%=iteratorURL %>"
delta="5"
deltaConfigurable="true"
> 
<liferay-ui:search-container-results>
<%
total = StudentLocalServiceUtil.getStudentsCount();
results=StudentLocalServiceUtil.getStudents(searchContainer.getStart(), searchContainer.getEnd());
searchContainer.setTotal(total);
searchContainer.setResults(results);
%>
</liferay-ui:search-container-results>
<liferay-ui:search-container-row className="com.meera.dbservice.model.Student"
keyProperty="studentId" modelVar="currentStudent">
<liferay-portlet:renderURL varImpl="rowURL">
<portlet:param name="backURL" value="<%= currentURL %>" />
<portlet:param name="mvcPath" value="/html/jsps/display_student.jsp" />
<portlet:param name="studentId"
value="<%= String.valueOf(currentStudent.getStudentId()) %>" />
</liferay-portlet:renderURL>
<liferay-ui:search-container-row-parameter
name="rowURL"
value="<%= rowURL.toString() %>"/>
<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="firstName" property="firstName" />

<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="lastName" property="lastName" />

<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="studentAge" property="studentAge" />

<liferay-ui:search-container-column-text href="<%= rowURL %>"
name="studentGender"
value='<%=currentStudent.getStudentGender()==1?"Male":"Female"%>' />
<liferay-ui:search-container-column-jsp
align="left"
name="Student Address"
path="/html/jsps/student_address_details.jsp"/>
</liferay-ui:search-container-row>
<liferay-ui:search-iterator searchContainer="<%=searchContainer %>" />
</liferay-ui:search-container>


Column JSP page (/html/jsps/student_address_details.jsp)


<%@page import="com.meera.dbservice.model.Student"%>
<%@page import="com.liferay.portal.kernel.util.WebKeys"%>
<%@page import="com.liferay.portal.kernel.dao.search.ResultRow"%>
<%@ include file="init.jsp" %>
<%
ResultRow row = (ResultRow)request.getAttribute(WebKeys.SEARCH_CONTAINER_RESULT_ROW);

Student student = (Student)row.getObject();
String rowURL = (String)row.getParameter("rowURL");
%>
<%=student.getStudentAddress()%>


Display Student Details JSP page(/html/jsps/display_student.jsp)


<%@page import="com.liferay.portal.kernel.util.ParamUtil"%>
<%@page import="com.meera.dbservice.service.StudentLocalServiceUtil"%>
<%@page import="java.util.List"%>
<%@page import="com.meera.dbservice.model.Student"%>
<%@ include file="init.jsp" %>
<portlet:defineObjects />
<h2>Display Student Information</h2>
<%
String redirect = ParamUtil.getString(request, "backURL");
long studentId = ParamUtil.getLong(request, "studentId");
Student selecteStudentObject = null;
if (studentId > 0) {
selecteStudentObject = StudentLocalServiceUtil.getStudent(studentId);
}
%>
<a href="<%=redirect %>">Back</a><br/><br/>
<%if(selecteStudentObject!=null){%>
<h3>The following are the selected Student Information</h3><br/>
Student Name:<%=selecteStudentObject.getFirstName()+"&nbsp;"+
selecteStudentObject.getLastName()%>
<br/>
Student Age: <%=selecteStudentObject.getStudentAge() %><br/>
Student Gender: <%=selecteStudentObject.getStudentGender()==1?"Male":"Famale"%>
<br/>
Address: <%=selecteStudentObject.getStudentAddress()%><br/>
<%}%>



Init.jsp page maintain all Tag lib URL declarations, Common Imports and Common Variables for all JSP pages

Init.jsp (html/jsps/init.jsp)


<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>
<%@ taglib uri="http://liferay.com/tld/aui" prefix="aui" %><%@
taglib uri="http://liferay.com/tld/portlet" prefix="liferay-portlet" %><%@
taglib uri="http://liferay.com/tld/security" prefix="liferay-security" %><%@
taglib uri="http://liferay.com/tld/theme" prefix="liferay-theme" %><%@
taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %><%@
taglib uri="http://liferay.com/tld/util" prefix="liferay-util" %>
<portlet:defineObjects />
<liferay-theme:defineObjects />
<%
String currentURL = PortalUtil.getCurrentURL(request);
String firstName = ParamUtil.getString(request, "firstName");
String lastName = ParamUtil.getString(request, "lastName");
int studentAge = ParamUtil.getInteger(request, "studentAge");
int studentGender = ParamUtil.getInteger(request, "studentGender");
String studentAddress = ParamUtil.getString(request, "studentAddress");%>


Download Search Container Portlet


Environment:

Liferay IDE 2.x+Eclipse (Kepler) +Liferay Plugins SDK 6.2+Tomcat 7.x Liferay Portal Bundle

Deployment and its Working.

Download portlet you can source or war file to deploy into liferay portal as your convenient.
Once portlet successfully deployed drag the portlet in any desired page. Portlet is available in sample category.

In the portlet page you can click View All Students link then you can see the search container with student’s data.

Portlet Screens:

Default Page


Search container Grid


Student details page


Reference Links



Author