Liquid portal search: display results, tag filters and paging

Portal search should help a customer choose the right answer, understand active filters and recover when nothing matches. sb.search contains the authorized knowledge search result model for the current search page. Use its supplied result and navigation values to improve discovery without changing the underlying access rules or inventing search URLs.

What this object gives you  ·  Choose the correct page and customer context  ·  Supported values and how to use them  ·  Example: explain a search and show readable article results  ·  Make selected tags and unavailable tags understandable  ·  Make and verify the change  ·  Common problems and recovery  ·  Keep the portal useful over time

What this object gives you

sb.search is one search object containing a results collection. It also includes counts, paging URLs and tag-filter context. The current Core knowledge-search path supports article results; the legacy forum type value is retained in the model but is not evidence of a working forum-search result set.

A zero-result page should explain the current query and any selected tag, then offer a useful way to broaden the search. It should not tell a customer that their product is unsupported merely because this query has no authorized matches.

Choose the correct page and customer context

Use the portal’s existing search page and search controls. Search text is handled through the supported route/context; do not replace it with a guessed ?q= URL. The supplied URLs preserve relevant paging and tag state.

Open the intended portal in Settings → Customer Portal, then choose Page templates. You need permission to administer communities or the applicable portal-edit override. Work on the existing page for this task; adding an object name to a different page does not make its records available. Keep existing forms, input names, navigation and scripts intact.

Liquid is a presentation language. Expressions inside {{ ... }} print values; statements inside {% ... %} control a loop or condition. A collection must be looped through before reading an individual row. These examples are display fragments to adapt within a working template, not replacement page templates.

Supported values and how to use them

Example: explain a search and show readable article results

<h1>Search results for “{{ sb.search.query | escape }}”</h1>
{% for result in sb.search.results %}
 <section class="search-result">
 <h2><a href="/article/{{ result.id | escape }}">{{ result.plain_title | escape }}</a></h2>
 <p>{{ result.plain_summary | escape }}</p>
 </section>
{% else %}
 <p>No knowledge articles match this search in the current portal context.</p>
 <p>Try the product name and a shorter symptom or task phrase.</p>
{% endfor %}
{% unless sb.search.next_url == blank %}
 <a href="{{ sb.search.next_url | escape }}">Next results</a>
{% endunless %}

Keep the existing search form, previous-page controls and tag-clearing controls around this fragment. For an equipment issue, “pump pressure alarm” is a useful starting query; an exact article ID is useful when the customer was already given a specific reference.

Make selected tags and unavailable tags understandable

A selected tag narrows the search. Display its name and an obvious way to clear it using clear_tag_url, so the customer can tell whether a filter—not just their wording—is limiting the results. An unavailable tag should produce a clear message and a broader route, not a dead end.

Referencing next_url, previous_url or facets opts this template into paged search. A selected tag also enables paging. The paged mode uses 20 results per page, while the legacy unpaged mode returns up to 50. Adding the pager in this example is therefore an intentional search-behavior choice, not merely a decorative link. Keep both navigation directions and the relevant filters, then verify the first, middle and last result pages. A template-side loop limit only hides supplied rows and is not server paging.

Make and verify the change

1. Write down the customer task this change should improve. For example, make the correct request or relevant knowledge easier to find. Decide what should appear when there is no data.
2. Copy the current template into your approved change record before editing. Add the fragment in the correct page context without removing functional controls.
3. Choose Save Changes to save the draft, then Design to preview it. Check a populated example and an empty or signed-out example as applicable.
4. Inspect desktop and narrow-screen layouts. Test long customer names, long titles, missing optional values, readable links and keyboard navigation.
5. Use Review changes → Publish when the draft is ready. A saved draft does not update the live visitor page.
6. Open the actual portal as an intended customer and follow the full task. Verify another relevant role or customer scope where visibility differs. Record the account, page, role and outcome with the change.

Common problems and recovery

Keep the portal useful over time

Review the queries customers actually use and improve article titles, summaries and content around those tasks. Add relevant synonyms only where they describe the article accurately. Useful content and correct access must be verified separately from visual search-page polish.

Use clear labels and meaningful empty states. Do not display a raw ID when a customer needs a descriptive name, and do not describe an absent value as a service failure. After changes to portal roles, topic placement, custom fields or language coverage, revisit the relevant customer examples. A successful render alone does not establish that the instructions, links and customer visibility are still correct.

Continue learning

• Plan and publish a safe Liquid portal customization
• Search and use knowledge effectively
• Display the chosen article
• Configure the customer portal