# JarrodNix {}

Search Assistant

Track and manage your users' search history to find popular searches, recent searches, and more in Craft CMS

Requirements

Search Assistant requires PHP 8.0.2 or greater and Craft CMS 4.0.0 or 5.0.0 or greater.

Installation

COMMAND LINE

1. Open your terminal and go to your Craft project:

cd /path/to/project

2. Then tell Composer to load the plugin:

composer require jrrdnx/craft-search-assistant

3. In the Control Panel, go to Settings -> Plugins and click the "Install" button for Search Assistant.

CONTROL PANEL

Visit the Search Assistant page in the Plugin Store in your control panel and click the Install button.

Plugin Settings

Plugin settings can be managed through Settings > Plugins > Search Assistant, or you can copy the `config.php` file from the package root to your craft/config/ directory as `search-assistant.php`. This file is multi-environment aware just like Craft's `general.php` so you can have different values for different environments.

ENABLED

Allows you to quickly enable/disable the tracking of searches as well as the control panel section. Helpful to disable on dev or staging environments but enable on production.

PLUGIN NAME

Change the name of the plugin as shown in the control panel navigation.

IP/CIDR IGNORE LIST

A list of IP addresses and/or CIDR blocks to ignore when tracking searches so internal organization usage doesn't skew the recent and popular search results.

IGNORE CONTROL PANEL USERS

When toggled on, searches will not be tracked for any users logged into the control panel so Craft users can use front-end searches without skewing the results.

lite vs pro editions

The Lite edition includes search tracking and Twig templating functionality, while the Pro edition adds a control panel section to view the full search history and the ability to disable and delete tracked searches.

Templating

If Search Assistant is enabled and the user is not logged into the control panel or visiting from an ignored IP address (see Plugin Settings), all instances of the search parameter on supported element queries will automatically be tracked:

{% for result in craft
    .entries
    .search(craft.app.request.getQueryParam('keywords'))
    .orderBy('score')
    .all()
%}

Search Assistant will track the site (for multi-site projects), page url, keywords, number of results returned, and increment a counter to track the number of times that keyword has been searched.

Craft variables

Two Craft variables are available to retrieve recent and popular searches. Each will automatically limit results to the current site, as well as exclude any keywords that did not return any results.

craft.recentsearches()

Two properties are returned for each result: `keywords` and `lastSearched`.

{% for search in craft.recentSearches() %}

    {{ search.keywords }} ({{ search.lastSearched|date('F j, Y H:i:s') }})

{% endfor %}

You can pass an optional object to change the number of recent searches returned (defaults to 5), as well as limit results to a particular page:

{% for search in craft.recentSearches({ pageUrl: craft.app.request.url, limit: 10 }) %}

    {{ search.keywords }} ({{ search.lastSearched|date('F j, Y H:i:s') }})

{% endfor %}
craft.popularSearches()

Two properties are returned for each result: `keywords` and `searchCount`.

{% for search in craft.popularSearches() %}

    {{ search.keywords }} ({{ search.searchCount }})

{% endfor %}

You can pass an optional object to change the number of recent searches returned (defaults to 5), as well as limit results to a particular page:

{% for search in craft.popularSearches({ pageUrl: craft.app.request.url, limit: 10 }) %}

    {{ search.keywords }} ({{ search.searchCount }})

{% endfor %}

CP Section

The Pro edition of Search Assistant adds a Control Panel section to view the full search history, including keywords that did not return any results, as well as more extensive recent and popular searches. From these screens, keywords can be disabled as well as deleted as restored.

disabling keywords

Disabling a keyword will prevent it from being included in any recent or popular searches, but its search count and last searched time will still be updated if otherwise searched.

deleting keywords

Deleting a keyword will also prevent it from being included in any recent or popular searches, but any new searches for the same keyword will simply add a new record so disabling may be a more suitable option.

Widgets

The Pro edition also includes the ability to add Recent Searches and Popular Searches widgets to the Dashboard. The number of results included can be set for each widget.

Search Assistant Widgets

Permissions

The Pro edition also adds custom permissions for non-Admin users (Admin users will always have full permissions).

To allow other users access to the Search Assistant control panel section, they will need the following options checked:

  1. Access the control panel
  2. Access Search Assistant
  3. For multi-site projects, access to any relevant Site(s)
  4. "View full history" to view the full search history and extended recent and popular searches
  5. "Can change status" to enable/disable individual keywords
  6. "Can delete" to delete individual keywords
Search Assistant Permissions