Creating Search Form and Search Results Pages

Many web applications feature a common two-page experience for user searches:

  1. A page for entering searches—typically a small search form at the center of the page, or at the top of the page if there are many different components.
  2. A second page that lists all matching results from the first page’s search query.

You can see an experience like this on the Google or Bing search engines.

It’s possible to replicate this functionality in Skuid using the following:

  • Two pages: The first page is used for entering search queries, the second for listing search results.
  • The {{searchTerm}} merge variable: This variable is accessible through the $Component global merge variable, and it will be used to pass the user’s search query to the second page.
  • A query string URL parameter: The results page will look to its query string parameter—a parameter inside the page’s URL—to know which results to query for.

This tutorial will guide you through building an example search form page, which returns matching account records and allows users to go directly to those account detail pages. However, this search form will also have a “Go to search results” button, which will navigate to a full page that displays all matching results.

While these pages are simple, the concepts they describe can be expanded into intuitive search user experiences. Follow along to learn more.

Building the search page

  1. Click Pages in the Skuid navbar.

  2. Click Create.

  3. Set the following fields:

    • Page name: example_search_page
    • Page API version: v2

You won’t need to worry about the other fields for this example.

  1. Click Create.

With the page created, you’re redirected to the Composer. Time to start building!

Use a Responsive Grid to center the search form on the page

We want the search form to be centered in this page, and to accomplish this structure we’ll use a Responsive Grid—a key layout component.

Without a Responsive Grid, components line up along the left side of the page. Let’s use a Responsive Grid with three divisions to instead center our components:

  1. Click the components Components tab.
  2. Find the Responsive Grid component in the component list.
  3. Drag and drop it into the canvas.
  4. Within the Responsive Grid header, click Add division twice.

Now we’ll adjust the flex ratios for each division. Flex ratios determine the amount of space to give a division compared to the other divisions of the Responsive Grid, with higher numbers taking up more space relative to the other divisions.

For this example, let’s set the center division to have the most space:

  1. Click the center division.
  2. In the Properties pane, set the Flex ratio property to 2.

With the first Responsive Grid providing a division to center all of the components, we’ll use another Responsive Grid within that division to place the Search component and the Button Set component next to each other.

We’ll do this by placing the components in two adjacent divisions within the inner Responsive Grid. If placed in the same division, our components would stack vertically instead.

  1. Click the components Components tab.
  2. Find the Responsive Grid component in the component list.
  3. Drag and drop it into the canvas within the center division of the first Responsive Grid.
  4. Within the Responsive Grid header, click Add division.

For this inner Responsive Grid, let’s adjust the spacing. We’ll set the column gutter to have some padding between the two divisions and set the second division to a lower flex ratio so the Search component’s division always has the most space:

  1. With the Responsive Grid still selected, set its Column gutter size property to Small (8px).
  2. Click the second division in the current Responsive Grid.
  3. Set the Flex ratio property 0.
  4. Click Save.

With the layout of the page set, it’s time to add the components that provide the search functionality.

Add Search component

First, we’ll add the Search component and set its unique ID. The unique ID property determines the “name” of the component, which is how we’ll retrieve its search value through the $Component global merge variable.

  1. Click the components Components tab.

  2. Find the Search component in the component list.

  3. Drag and drop it into the canvas into the left division of the innermost Responsive Grid.

  4. With the newly created Search component selected, set the following General properties:

    1. Fields to search: All text fields
    2. Search results: Match exactly
    3. Placeholder Text: Search accounts
  5. Click the Advanced tab

  6. Set the Unique ID property to globalSearch.

  7. Click Save.

With the basic properties set, it’s time to configure the essential parts of the component:

  • The global actions, which run when a search result is selected. We’ll configure a global action that sends the user to the detail page of a selected record—in contrast to our Go to search results button.
  • The return objects, which determine the Salesforce objects that will be searched. For this example we’ll add the Account object as a return object.

For the global action, we’ll configure a Go to URL action that sends the user directly to a selected results detail page:

  1. With the Search component selected, click the Global Actions tab in the Properties pane.
  2. Click + Add action.
  3. Click the newly created action.
  4. Click + Add action step.
  5. Click the newly created action step.
  6. Set the following properties:
    • Action type: Go to URL
    • URL: /{{Id}}
    • Open URL in: Current window

Now we’ll add a single return object for the Account object:

  1. With the Search component selected, click the Return Objects tab in the Properties pane.
  2. Click + Add return object.
  3. Click the newly created object.
  4. Set the following properties:
    • Data source: salesforce
    • Entity: Account
    • Header display icon: sk-webicon-ink:home
    • Header display name: Accounts
    • Display template: {{Name}}
    • Fields: Account Name (Name), Account ID (Id)
  5. Click Save.

Add Button Set for navigating to results page

While the Search component provides an input form, it’s set to send the user directly to a detail page if they select a particular result. We’ll now build the button that users can click to see a full list of matching results.

  1. Click the components Components tab.
  2. Find the Button Set component in the component list.
  3. Drag and drop it into the canvas in the right division of the innermost Responsive Grid
  4. Click the newly created button.
  5. Set the Button label to Go to search results.
  6. Click the Actions tab.
  7. Click + Add action twice to create two new actions.
  8. Click the first newly created action.
  9. Set the following properties:
    • Action type: Block UI with message
    • Message: Searching for records that contain ‘{{$Component.globalSearch.searchValue}}’
    • Timeout (seconds): Never
  10. Click the second newly created action.
  11. Set the following properties:
    • Action type: Go to URL
    • URL: /apex/skuid__ui?page=example_search_results_page&searchterm={{$Component.globalSearch.searchValue}}
    • Open URL in: Current window
  12. Click Save.

Note: This example only uses Skuid’s previewing functionality to display the pages. If you were to deploy these pages for a production use case, then your Go to URL action would have a different URL. See the Deploy docs section for more information.

Building the results page

With the search page built, it’s time to create the results page. When creating this page, we have to set a very important property: the page name. The search page’s Go to search results button redirects the user to this page based on this name. If you follow the directions below you’ll be fine, but if you see issues, be sure that Go to URL action’s URL matches this page’s name.

  1. Click Pages in the Skuid navbar.
  2. Click Create.
  3. Set the following fields:
    • Page name: example_search_results_page
    • Page API version: v2

You won’t need to worry about the other fields for this example.

  1. Click Create.

Creating a model to source records from

While the previous page did not require a model since the return object was set in the Search component, this page will need a model on the Account object. This model will query the accounts and, through condition logic, only return the records that match the user’s search term.

  1. Click the models Models tab.

  2. Click + Add model.

  3. Set the following model properties:

    • Model ID: AccountList
    • Data source type: salesforce
    • Data source: Current Salesforce Org
    • Salesforce object name: Account

    Leave the other fields as their default values. You won’t need to adjust them for this example.

  4. Click Save.

Then add the Name field to the model:

  1. With the AccountList model model still selected, click Fields in the Elements pane.
  2. Click the checkbox beside the Account Name (Name) field.

Now to create a condition so that the model only queries for records matching the user’s search term. We’ll do this by adding a condition that looks to a URL page parameter. We set this parameter in the previous page’s Go to URL action as a query string &searchterm={{$Component.globalSearch.searchValue}}.

  1. With the AccountList model model still selected, click Conditions.

  2. Click + Add.

  3. Set the condition’s properties:

    • Field: Account Name (Name)

    • Operator: contains

    • Value:

      • Content: Page/URL parameter value
      • Parameter: searchTerm
      • If this parameter is not provided then…: Set its value to blank
    • State:

      • Condition state: Always on
      • Condition location: Server
  4. Click Save.

Displaying results in a List component

The page’s data is set, now to add the components. First let’s create some space around the results screen using a Wrapper component.

  1. Click the components Components tab.
  2. Find the Wrapper component in the component list.
  3. Drag and drop it into the canvas.
  4. Within the Styles tab in the Properties pane, click the Spacing subtab.
  5. Set the margin properties:
    • Top margin: Regular (16 px)
    • Right margin: Regular (16 px)
    • Left margin: Regular (16 px)
    • Right margin: Regular (16 px)

Next, we’ll add a Text component to add a header that labels the results list. For this header, we’ll access the $Model global merge variable to get the condition parameter used to query data. This allows the components header to reflect the user’s search.

  1. Click the components Components tab.

  2. Find the Text component in the component list.

  3. Drag and drop it into the canvas into the Wrapper.

  4. Click inside the Text component within the canvas to enter the following header text:

    Search results for '{{$Model.AccountList.conditions.0.value}}'

  5. (Optional) Set the header to a larger font size, for example 24, within the Rich Text Editor screen that hovers over the Text component.

Now to add and configure the List component, which will display the records that match the user’s search term.

  1. Click the components Components tab.
  2. Find the List component in the component list.
  3. Drag and drop it into the canvas into the Wrapper, beneath the Text component.
  4. If not already configured, set the List’s Model to AccountList.

Now add the Name field to the component:

  1. Within the List’s header in the canvas, click Add fields > Model fields.
  2. Click the checkbox beside Account Name.
  3. Click Apply.
  4. Click Save.

And with that, the search results page is complete!

End result

You can preview either of the pages to see the flow in action, but previewing the results page will prompt you to enter a search term. To see the full experience:

  1. Click Pages in the Skuid navbar.
  2. Beside the example_search_page you built earlier, click the dots-vertical More Options > Preview.
  3. Click Go.

The search form page opens. To test the link to the results page, type an account name (for example Edge Communications) then click Go to search results. You can also go directly to an account’s detail page by clicking a result in the Search component’s dropdown list.

https://s3.us-west-2.amazonaws.com/developer.skuid.com/assets/v16.4.4/api-versions/v2/skuid/components/ink/search/search-form-and-results-example/search-merge-variable-end-results.gif