Customizing search panel settings
This section describes Brightspot’s search panel and how you can customize its behavior.
@ToolUi annotations described in Content modeling annotations. These annotations are already optimized for many use cases and require only one line of code to implement.
When you open the search panel the following events occur:
- Initialize—Receives Search and ToolPageContext objects. Using the
initializeSearchcallback, you can override this event to examine the state of the application. - Write search filters—Displays the standard filters in the search panel. Using the
writeSearchFilterscallback, you can add additional filters to the search panel. - Update search query—Builds the search command based on the search text and filters. Using the
updateSearchQuerycallback, you can modify the search command so that it includes criteria different from what appears in the search panel. - Execute search—Performs the search based on the latest result of
updateSearchQuery.
The standard search panel includes a field for full-text search and filters for content type, publish dates, and status.
Referring to the previous illustration, Brightspot performs a search using the following MySQL pattern:
SELECT fieldnames FROM datatable WHERE (contentType="Article")
AND (status="Published")
AND ((headline LIKE '%fermentation%') OR (body LIKE '%fermentation%'))
ORDER BY lastUpdateDate
LIMIT 10;
This section shows how to override the search panel's callbacks to modify its default appearance and behavior. This example describes a customized search panel and search query for users who are assigned a role other than the global role.
Step 1: Declare modified search class
All of the search panel's callbacks receive a Search object. When customizing the search panel, as a best practice modify the Search object and save state variables for use with search results.
This step creates a CustomSearch class that is a modification of Search. This class has a single field that is one of the following:
-
nullif the current user has no specific role (equivalent to being a global user). - Populated with the user's record.
import com.psddev.cms.db.ToolUser; import com.psddev.cms.tool.Search; import com.psddev.dari.db.Modification; public class CustomSearch extends Modification<Search> { private ToolUser nonGlobalUser; public ToolUser getNonGlobalUser() { return nonGlobalUser; } public void setNonGlobalUser(ToolUser nonGlobalUser) { this.nonGlobalUser = nonGlobalUser; } }
The previous snippet is a class declaration only; the instantiation occurs in Step 3.
Step 2: Declare class for custom search settings
Declare a class that extends Tool.
import com.psddev.cms.tool.Tool;
public class CustomSearchSettings extends Tool {
}
Steps 3–5 detail how to implement methods in this new class to customize search settings.
Step 3: Initialize search environment
The Tool class includes an empty method initializeSearch. The purpose of this method is to examine the search environment and set flags and values required for customization. The following snippet provides an example for overriding this method.
@Override
public void initializeSearch(Search search, ToolPageContext page) {
if (page.getUser().getRole() != null) {
search.as(CustomSearch.class).setNonGlobalUser(page.getUser());
} else {
search.as(CustomSearch.class).setNonGlobalUser(null);
}
}
The previous snippet tests the current user's role. Depending on the results of the test, a CustomSearch object is instantiated accordingly.
Step 4: Display customized search filters
The Tool class includes an empty method writeSearchFilters. The purpose of this method is to display custom filters above the Advanced Query field in the search panel. The following snippet provides an example for overriding this method.
@Override
public void writeSearchFilters(Search search, ToolPageContext page) throws IOException {
if (search.as(CustomSearch.class).getNonGlobalUser() != null) {
String userName = search.as(CustomSearch.class).getNonGlobalUser().getName();
String userId = search.as(CustomSearch.class).getNonGlobalUser().getId().toString();
page.writeHtml("Editor:");
page.writeStart("select",
"placeholder", "Editor");
page.writeStart("option",
"value", userId,
"selected", "selected");
page.writeHtml(userName);
page.writeEnd(); /* option */
page.writeEnd(); /* select */
}
}-
Examines the value of
CustomSearch#nonGlobalUser. If the value is not null, the user is not a global user and the custom filters appear. -
Retrieves the current user's name.
-
Retrieves the current user's ID.
-
Displays a label
Editor. -
Creates an HTML
<select>element and populates it with a single<option>for the current user.
Step 5: Customize the query object
The Tool class includes an empty method updateSearchQuery. The purpose of this method is to modify the default query object that reflects settings in the search filters. The following snippet provides an example for overriding this method.
@Override
public void updateSearchQuery(Search search, Query<?> query) {
if (search.as(CustomSearch.class).getNonGlobalUser() != null) {
String userId = search.as(CustomSearch.class).getNonGlobalUser().getId().toString();
query.and("cms.content.publishUser = ?", userId);
}
}-
Examines the value of
CustomSearch#nonGlobalUser. If the value is not null, the user is not a global user and the query string is modified. -
Retrieves the current user's ID.
-
Appends the condition
ANDLastPublishedUser=userIdto he search string.
When this method is complete, Brightspot performs the actual retrieval and displays the results.
The following snippet is a complete implementation of the methods described in steps 2–5.
import com.psddev.cms.tool.Search;
import com.psddev.cms.tool.Tool;
import com.psddev.cms.tool.ToolPageContext;
import com.psddev.dari.db.Query;
public class CustomSearchSettings extends Tool {
@Override
public void initializeSearch(Search search, ToolPageContext page) {
if (page.getUser().getRole() != null) {
search.as(CustomSearch.class).setNonGlobalUser(page.getUser());
} else {
search.as(CustomSearch.class).setNonGlobalUser(null);
}
}
@Override
public void writeSearchFilters(Search search, ToolPageContext page) throws IOException {
if (search.as(CustomSearch.class).getNonGlobalUser() != null) {
String userName = search.as(CustomSearch.class).getNonGlobalUser().getName();
String userId = search.as(CustomSearch.class).getNonGlobalUser().getId().toString();
page.writeHtml("Editor:");
page.writeStart("select",
"placeholder", "Editor");
page.writeStart("option",
"value", userId,
"selected", "selected");
page.writeHtml(userName);
page.writeEnd(); /* option */
page.writeEnd(); /* select */
}
}
@Override
public void updateSearchQuery(Search search, Query<?> query) {
if (search.as(CustomSearch.class).getNonGlobalUser() != null) {
String userId = search.as(CustomSearch.class).getNonGlobalUser().getId().toString();
query.and("cms.content.publishUser = ?", userId);
}
}
}
The following illustration shows the effect of this customization sample on the search panel.
