feat: Enhance SimpleSearch with AJAX, Highlighting & Pagination

README.md

@@ -4,6 +4,17 @@
 
 `SimpleSearch` is a simple, yet very powerful [Grav][grav] plugin that adds search capabilities to your Grav instance. By default it can search Page **Titles**, **Content**, **Taxonomy**, and also a raw page **Header**.
 
+## Key Features
+
+*   **Flexible Searching:** Search page titles, content, taxonomy, and raw page headers.
+*   **AJAX Search Suggestions (Autocomplete):** Provides instant search suggestions as you type for a faster, more interactive search experience.
+*   **AJAX Search Results:** Optionally, load full search results dynamically on the current page without a full page reload.
+*   **Search Term Highlighting:** Automatically highlights the searched terms in the results (titles and snippets) for improved visibility.
+*   **Pagination:** Search results are paginated in both traditional (server-rendered) and AJAX modes.
+*   **Configurable:** Fine-tune search behavior with various options, including filters, content source (rendered HTML vs. raw Markdown), and more.
+*   **Customizable Templates:** Easily customize the appearance of the search box and search results.
+*   **Event for Extensibility:** Hook into SimpleSearch to add custom data sources to your search results.
+
 # Installation
 
 Installing the SimpleSearch plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
@@ -52,6 +63,63 @@ searchable_types:
     taxonomy: true
     header: false
 header_keys_ignored: ['title', 'taxonomy','content', 'form', 'forms', 'media_order']
+    enable_search_suggestions: true
+    min_query_length_suggestions: 3
+    max_suggestions: 5
+    enable_ajax_search: false
+    per_page: 10
+```
+
+By creating the configuration file: `user/config/plugins/simplesearch.yaml` you have effectively created a site-wide configuration for SimpleSearch. Most of these options can also be configured via the Grav Admin Panel.
+
+Below is a detailed explanation of the configuration options:
+
+*   `enabled`: (Default: `true`) Set to `false` to disable the plugin.
+*   `built_in_css`: (Default: `true`) Use the plugin's built-in CSS for styling the search box and results. Disable if you want to provide all styles from your theme.
+*   `built_in_js`: (Default: `true`) Use the plugin's built-in JavaScript for AJAX suggestions and results.
+*   `display_button`: (Default: `false`) Show a submit button next to the search input field.
+*   `min_query_length`: (Default: `3`) Minimum number of characters required in the search input before a search is performed (for non-AJAX traditional search).
+*   `route`: (Default: `/search`) The base route for displaying search results (for non-AJAX traditional search).
+*   `search_content`: (Default: `rendered`) Determines what content is searched:
+    *   `rendered`: Searches the fully rendered HTML content of the page (slower, but includes content generated by Twig or other plugins).
+    *   `raw`: Searches the raw Markdown content of the page (faster, but might miss dynamically generated content).
+*   `template`: (Default: `simplesearch_results`) The Twig template used to display the search results page (for non-AJAX traditional search).
+*   `filters`: (Default: `category: null`) Allows you to restrict searching to pages that match certain taxonomy filters. For example, `category: blog` would only search in pages with the category `blog`. Set to `@none` or leave empty to search all pages.
+*   `filter_combinator`: (Default: `and`) If multiple filters are specified, this determines how they are combined:
+    *   `and`: All filters must match.
+    *   `or`: Any of the filters can match.
+*   `ignore_accented_characters`: (Default: `false`) If true, searches will be accent-insensitive (e.g., "cafe" will match "café"). Requires the `en_US` locale to be installed on the server.
+*   `order.by`: (Default: `date`) How search results should be ordered. Common options: `date`, `title`, `folder`, `default` (page's default collection order).
+*   `order.dir`: (Default: `desc`) Direction of ordering: `asc` (ascending) or `desc` (descending).
+*   `searchable_types`: Defines which parts of a page are searched:
+    *   `title`: (Default: `true`) Search page titles.
+    *   `content`: (Default: `true`) Search page content (respects `search_content` setting).
+    *   `taxonomy`: (Default: `true`) Search page taxonomy values.
+    *   `header`: (Default: `false`) Search raw page headers (excluding those in `header_keys_ignored`).
+*   `header_keys_ignored`: (Default: `['title', 'taxonomy','content', 'form', 'forms', 'media_order']`) A list of page header keys to ignore when `searchable_types.header` is enabled.
+
+### Search Suggestions (Autocomplete)
+These options control the AJAX-powered search suggestions that appear as you type.
+*   **`enable_search_suggestions`**: (Default: `true`) Set to `false` to disable search suggestions.
+*   **`min_query_length_suggestions`**: (Default: `3`) The minimum number of characters a user needs to type before suggestions are fetched and displayed.
+*   **`max_suggestions`**: (Default: `5`) The maximum number of search suggestions to display in the dropdown.
+
+### AJAX Search Results
+This feature allows search results to be loaded and displayed directly on the current page without a full page reload.
+*   **`enable_ajax_search`**: (Default: `false`) Set to `true` to enable this mode. If `false`, submitting the search form will redirect to the traditional search results page defined by the `route` option.
+
+### Pagination
+These options control how search results are paginated.
+*   **`per_page`**: (Default: `10`) The number of search results to display on each page. This applies to both traditional (server-rendered) and AJAX search results.
+
+### Search Term Highlighting
+Search terms are automatically highlighted in the search results (titles and content snippets) using `<mark>` HTML tags. This feature is enabled by default and works for both AJAX and non-AJAX results.
+You can customize the appearance of these highlights using CSS. For example, to change the default yellow background:
+```css
+mark {
+    background-color: lightblue;
+    color: black;
+}
 ```
 
 By creating the configuration file: `user/config/plugins/simplesearch.yaml` you have effectively created a site-wide configuration for SimpleSearch.  However, you may want to have multiple searches.

blueprints.yaml

@@ -98,6 +98,60 @@ form:
         type: number
         min: 0
 
+    enable_search_suggestions:
+      type: toggle
+      label: PLUGIN_SIMPLESEARCH.ENABLE_SEARCH_SUGGESTIONS
+      help: PLUGIN_SIMPLESEARCH.ENABLE_SEARCH_SUGGESTIONS_HELP
+      highlight: 1
+      default: 0
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+
+    min_query_length_suggestions:
+      type: text
+      size: x-small
+      label: PLUGIN_SIMPLESEARCH.MIN_QUERY_LENGTH_SUGGESTIONS
+      help: PLUGIN_SIMPLESEARCH.MIN_QUERY_LENGTH_SUGGESTIONS_HELP
+      default: 3
+      validate:
+        type: number
+        min: 0
+
+    max_suggestions:
+      type: text
+      size: x-small
+      label: PLUGIN_SIMPLESEARCH.MAX_SUGGESTIONS
+      help: PLUGIN_SIMPLESEARCH.MAX_SUGGESTIONS_HELP
+      default: 5
+      validate:
+        type: number
+        min: 1
+
+    enable_ajax_search:
+      type: toggle
+      label: PLUGIN_SIMPLESEARCH.ENABLE_AJAX_SEARCH
+      help: PLUGIN_SIMPLESEARCH.ENABLE_AJAX_SEARCH_HELP
+      highlight: 1
+      default: 0
+      options:
+        1: PLUGIN_ADMIN.ENABLED
+        0: PLUGIN_ADMIN.DISABLED
+      validate:
+        type: bool
+
+    per_page:
+      type: text
+      size: x-small
+      label: PLUGIN_SIMPLESEARCH.PER_PAGE
+      help: PLUGIN_SIMPLESEARCH.PER_PAGE_HELP
+      default: 10
+      validate:
+        type: number
+        min: 1
+
     route:
       type: text
       size: medium

css/simplesearch.css

@@ -39,4 +39,94 @@
 
 .search-row:last-child hr {
 	display: none;
+}
+
+/* Search Suggestions Styles */
+.search-wrapper {
+    position: relative; /* Important for absolute positioning of suggestions */
+}
+
+.simplesearch-suggestions-container {
+    position: absolute;
+    left: 0;
+    /* Assuming the input is 80% and inside .search-wrapper. 
+       If .search-input is directly inside .search-wrapper, this might need adjustment 
+       or make .search-input 100% of .search-wrapper if that's the layout.
+       For now, let's assume it should span the same width as .search-input approximately.
+       A more robust way would be to set this width via JS based on the input's actual width.
+       Given the current .search-input width: 80%, this will make it 80% of the .search-wrapper.
+    */
+    width: 80%; 
+    top: 100%; /* Position it right below the input field */
+    background-color: #fff;
+    border: 1px solid #ccc;
+    border-top: none;
+    z-index: 1000; /* Ensure it's above other content */
+    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    max-height: 300px;
+    overflow-y: auto;
+}
+
+ul.simplesearch-suggestions-list {
+    list-style-type: none;
+    margin: 0;
+    padding: 0;
+}
+
+li.simplesearch-suggestion-item a {
+    display: block;
+    padding: 8px 12px;
+    text-decoration: none;
+    color: #333;
+    border-bottom: 1px solid #eee; /* Separator for items */
+}
+
+li.simplesearch-suggestion-item:last-child a {
+    border-bottom: none;
+}
+
+li.simplesearch-suggestion-item a:hover {
+    background-color: #f5f5f5;
+}
+
+/* Search Term Highlighting */
+mark {
+    background-color: yellow;
+    color: black;
+    padding: 0.1em 0.2em; /* Slightly less padding than example for subtlety */
+    border-radius: 3px; /* Optional: slightly rounded corners */
+}
+
+/* Specificity for simplesearch results if needed */
+.simplesearch .search-item mark {
+    /* Styles here would override generic mark if needed, e.g. different color */
+    /* For now, the generic mark style is likely fine */
+}
+
+/* Pagination Styles */
+.simplesearch-pagination {
+    margin-top: 20px;
+    text-align: center;
+}
+
+.simplesearch-pagination a,
+.simplesearch-pagination span.current {
+    padding: 5px 10px;
+    margin: 0 2px;
+    border: 1px solid #ddd;
+    text-decoration: none;
+    color: #337ab7; /* A common link color */
+    background-color: #fff;
+    border-radius: 4px;
+}
+
+.simplesearch-pagination span.current {
+    background-color: #eee;
+    color: #333;
+    border-color: #ccc;
+}
+
+.simplesearch-pagination a:hover {
+    background-color: #f5f5f5;
+    border-color: #bbb;
 }