97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# Pico-Search
|
|
|
|
A plugin for the flat file CMS [Pico](https://github.com/picocms/Pico). Allows you to create a very basic search form
|
|
that searches through titles and content of your pages. The search results page filters the `pages` array to only
|
|
contain pages matching the search terms.
|
|
|
|
You can optionally scope the search to only get results from within a certain folder. For example, on the page
|
|
`yoursite.com/blog/search/foobar`, the `pages` array will only contain results from pages in the `blog` folder.
|
|
|
|
Search results can be paginated using a plugin such as [Pico-Pagination](https://github.com/rewdy/Pico-Pagination).
|
|
The search plugin should be executed before the pagination plugin (execution order is determined by file name).
|
|
|
|
## Installation
|
|
|
|
- **Copy the file `40-PicoSearch.php` to the `plugins` sub-folder of your Pico installation directory.**
|
|
- **Add a file named `search.md` to your content root or the sub-folder you want to make searchable.**
|
|
This is your search results page. You can leave it empty of content, but set the `Template` meta tag to a template
|
|
that loops through the pages and displays them. Your `search.md` might look like this:
|
|
|
|
```
|
|
/*
|
|
Title: Search results
|
|
Template: search
|
|
*/
|
|
```
|
|
|
|
- **Add a template file with the name defined in `search.md`.**
|
|
Your template file (`search.twig` in the above example) should contain something like the following section, which
|
|
lists the pages matching the search (substitute `paged_pages` for `pages` if using Pico-Pagination):
|
|
|
|
```twig
|
|
{% if search_terms %}
|
|
<div class="SearchResults">
|
|
{% if pages %}
|
|
<h2>Search results for {{ search_terms|e('html') }}</h2>
|
|
{% for page in pages %}
|
|
<div class="SearchResult">
|
|
<h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
|
|
{% if page.description %}<p>{{ page.description }}</p>{% endif %}
|
|
</div>
|
|
{% endfor %}
|
|
{% else %}
|
|
<p>No results found for {{ search_terms|e('html') }}.</p>
|
|
{% endif %}
|
|
</div>
|
|
{% endif %}
|
|
```
|
|
|
|
If you simply want to make your search results page look like your standard page, you may want to edit your theme's `index.twig` file and change `{{ content }}` to `{% block content %} {{ content }} {% endblock %}`. This allows you to extend this base template and reuse all the other parts of it in your search results template:
|
|
|
|
```twig
|
|
{% extends "index.twig" %}
|
|
|
|
{% block content %}
|
|
{{ parent() }}
|
|
|
|
<div class="SearchResults">
|
|
<!-- Put the code for your search results here -->
|
|
</div>
|
|
{% endblock content %}
|
|
```
|
|
|
|
Now, you should be able to visit for example `yoursite.com/search/foobar` (adjust path accordingly if putting search.md
|
|
in a sub-folder) and see the search results for "foobar" listed.
|
|
|
|
## The search form
|
|
|
|
How to design your search form is up to you, but here's a very rudimentary example which you can put in a
|
|
template file:
|
|
|
|
```html
|
|
<form id="search_form" action="{{ "search"|link }}">
|
|
<label for="search_input">Search the site:</label>
|
|
<input type="search" id="search_input" name="q" value="{{ search_terms|e('html_attr') }}" />
|
|
<input type="submit" value="Search" />
|
|
</form>
|
|
<script type="text/javascript">
|
|
// Intercept form submit and go to the search results page directly, avoiding a redirect
|
|
document.getElementById('search_form').addEventListener('submit', function (e) {
|
|
var search_terms = document.getElementById('search_input').value;
|
|
location.href = '{{ "search"|link }}/' + encodeURIComponent(search_terms);
|
|
e.preventDefault();
|
|
});
|
|
</script>
|
|
```
|
|
|
|
If you want to put it in a content file, you'll have to adjust the template variables accordingly, ie. instead of `{{ "search"|link }}` you'd use something like `%base_url%?search`.
|
|
|
|
## Configuration options
|
|
|
|
You can exclude certain pages from being included in the search results by using the configuration option `search_excludes`.
|
|
Set it to an array of pages you'd like to exclude, where each page is specified as its path relative to the content root:
|
|
|
|
```php
|
|
$config['search_excludes'] = ['search', 'some/other/page'];
|
|
```
|