Introduction #

Liferay's Search Container gives developers a utility to easily paginate their data.

Demystifying Liferay's Search Container #

Here's a basic example that will help get you started:

<liferay-ui:search-container delta="10" emptyResultsMessage="no-users-were-found">
	<liferay-ui:search-container-results
		results="<%= UserLocalServiceUtil.search(
			company.getCompanyId(), searchTerms.getKeywords(), searchTerms.getActiveObj(), 
			userParams, searchContainer.getStart(), searchContainer.getEnd(),
 			searchContainer.getOrderByComparator()); %>"
		total="<%= UserLocalServiceUtil.searchCount(
			company.getCompanyId(), searchTerms.getKeywords(), searchTerms.getActiveObj(), 
			userParams); %>"
	/>

	<liferay-ui:search-container-row
		className="com.liferay.portal.model.User"
		keyProperty="userId"
		modelVar="user"
	>
		<liferay-ui:search-container-column-text
			name="name"
			value="<%= user.getFullName() %>"
		/>

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

	<liferay-ui:search-iterator />

</liferay-ui:search-container>

This is the container. It performs a lot of set up work behind the scenes like instantiating the searchContainer object.

• delta - The number of results per page
• emptyResultsMessage - The message shown where there aren't results (it can be a key from your language.properties)

	<liferay-ui:search-container-results
		results="<%= UserLocalServiceUtil.search(
			company.getCompanyId(), searchTerms.getKeywords(), searchTerms.getActiveObj(), 
			userParams, searchContainer.getStart(), searchContainer.getEnd(),
 			searchContainer.getOrderByComparator()); %>"
		total="<%= UserLocalServiceUtil.searchCount(
			company.getCompanyId(), searchTerms.getKeywords(), searchTerms.getActiveObj(), 
			userParams); %>"
	/>

• results - This is where you input the results. results should be of type List. The important part is to make sure that your method supports some way to search from a beginning index to an end index in order to provide a good performance pagination. Note how we use searchContainer.getStart() for the first index and searchContainer.getEnd() for the second index. As mentioned above, the searchContainer object is available because it has been instantiated already. Some other methods you can use:
• searchContainer.getStart() - gets starting index of current results page.
• searchContainer.getResultsEnd() - gets ending index of current results page or index of last result (i.e. will return 3 if delta is 5 but there are only 3 results).
• searchContainer.getEnd() - gets last index of current results page regardless of size of actually results (i.e. will return 5 if delta is 5 even if there is only 3 results. Will throw out of bounds errors).
• searchContainer.getCur() - gets number of current results page.
• searchContainer.setTotal() - must be set so getResultsEnd() knows when to stop.
• total - This is where you input the total number of items in your list:

<liferay-ui:search-container-row className="com.liferay.portal.model.User" keyProperty="userId" modelVar="user">

• className - The type of Object in your List. In this case, we have a List of User objects.
• keyProperty - Primary Key
• modelVar - The name of the variable to represent your model. In this case the model is the User object.

<liferay-ui:search-container-column-text name="name" value="<%= user.getFullName() %>" />

• <liferay-ui:search-container-column-text> - Text column
• name - Name of the column
• value - Value of the column
• href - the text in this coulmn will be a link the this URL
• orderable - allows the user to order the list of items by this column:

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

• property - This will automatically look in the User object for the "firstName" property. It's basically the same thing as user.getFirstName().

Important to note here; regardless of attribute capitalisation in your service.XML, the property value must always start lower case. After that it seems to follow what you defined.

<liferay-ui:search-iterator />

• <liferay-ui:search-iterator /> - This is what actually iterates through and displays the List

Hopefully, this gives you a jump start on how to use Liferay's SearchContainer in your own portlets.