From 70d423335a4e92c448f00b63186d819db7a3d1c7 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Sun, 28 Sep 2014 10:11:34 +0100 Subject: [PATCH] Restructed search docs --- .../advanced_topics/queryset_methods.rst | 2 +- docs/core_components/pages/creating_pages.rst | 2 +- docs/core_components/search/editors_picks.rst | 41 ------- docs/core_components/search/index.rst | 36 +++++- ...for_python_developers.rst => indexing.rst} | 79 +++++++++---- .../{frontend_views.rst => searching.rst} | 108 +++++++++++++++++- 6 files changed, 195 insertions(+), 73 deletions(-) delete mode 100644 docs/core_components/search/editors_picks.rst rename docs/core_components/search/{for_python_developers.rst => indexing.rst} (67%) rename docs/core_components/search/{frontend_views.rst => searching.rst} (65%) diff --git a/docs/core_components/pages/advanced_topics/queryset_methods.rst b/docs/core_components/pages/advanced_topics/queryset_methods.rst index 2c221b8832..878831ff87 100644 --- a/docs/core_components/pages/advanced_topics/queryset_methods.rst +++ b/docs/core_components/pages/advanced_topics/queryset_methods.rst @@ -170,7 +170,7 @@ Reference .. automethod:: search - See: :ref:`wagtailsearch_for_python_developers` + See: :ref:`wagtailsearch_searching_pages` Example: diff --git a/docs/core_components/pages/creating_pages.rst b/docs/core_components/pages/creating_pages.rst index 52d187890f..c31c0b1130 100644 --- a/docs/core_components/pages/creating_pages.rst +++ b/docs/core_components/pages/creating_pages.rst @@ -133,7 +133,7 @@ In addition to the model fields provided, ``Page`` has many properties and metho .. attribute:: search_fields - A list of fields to be indexed by the search engine. See Search docs :ref:`wagtailsearch_for_python_developers` + A list of fields to be indexed by the search engine. See Search docs :ref:`wagtailsearch_indexing_fields` .. attribute:: subpage_types diff --git a/docs/core_components/search/editors_picks.rst b/docs/core_components/search/editors_picks.rst deleted file mode 100644 index 59ae647de4..0000000000 --- a/docs/core_components/search/editors_picks.rst +++ /dev/null @@ -1,41 +0,0 @@ - -.. _editors-picks: - - -Editor's picks -============== - -Editor's picks are a way of explicitly linking relevant content to search terms, so results pages can contain curated content in addition to results from the search algorithm. In a template using the search results view, editor's picks can be accessed through the variable ``query.editors_picks``. To include editor's picks in your search results template, use the following properties. - -``query.editors_picks.all`` - This gathers all of the editor's picks objects relating to the current query, in order according to their sort order in the Wagtail admin. You can then iterate through them using a ``{% for ... %}`` loop. Each editor's pick object provides these properties: - - ``editors_pick.page`` - The page object associated with the pick. Use ``{% pageurl editors_pick.page %}`` to generate a URL or provide other properties of the page object. - - ``editors_pick.description`` - The description entered when choosing the pick, perhaps explaining why the page is relevant to the search terms. - -Putting this all together, a block of your search results template displaying editor's picks might look like this: - -.. code-block:: django - - {% with query.editors_picks.all as editors_picks %} - {% if editors_picks %} -
-

Editors picks

- -
- {% endif %} - {% endwith %} diff --git a/docs/core_components/search/index.rst b/docs/core_components/search/index.rst index e343f76c87..65754d761a 100644 --- a/docs/core_components/search/index.rst +++ b/docs/core_components/search/index.rst @@ -1,17 +1,43 @@ .. _wagtailsearch: - +====== Search ====== Wagtail provides a comprehensive and extensible search interface. In addition, it provides ways to promote search results through "Editor's Picks." Wagtail also collects simple statistics on queries made through the search interface. - .. toctree:: :maxdepth: 2 - for_python_developers - frontend_views - editors_picks + indexing + searching backends + + +Indexing +======== + +To make objects searchable, they firstly need to be added to the search index. This involves configuring the models/fields that you would like to index (this is done for you for Pages, Images and Documents) and then actually inserting them into the index. + +See :ref:`wagtailsearch_indexing_update` for information on how to keep the objects in your search index in sync with the objects in your database. + +If you have created some extra fields in a subclass of ``Page`` or ``Image``, you may want to add these new fields to the search index too so a users search query will match on their content. See :ref:`wagtailsearch_indexing_fields`. + +If you have a custom model which doesn't derive from ``Page`` or ``Image`` that you would like to make searchable, see :ref:`wagtailsearch_indexing_models`. + + +Searching +========= + +Wagtail provides an API for performing search queries on your models. You can also perform search queries on Django QuerySets. + +See :ref:`wagtailsearch_searching`. + + +Backends +======== + +Wagtail provides two backends for storing the search index and performing search queries: Elasticsearch and the database. It's also possible to roll your own search backend. + +See :ref:`wagtailsearch_backends` diff --git a/docs/core_components/search/for_python_developers.rst b/docs/core_components/search/indexing.rst similarity index 67% rename from docs/core_components/search/for_python_developers.rst rename to docs/core_components/search/indexing.rst index b254a2e1f9..3f61553971 100644 --- a/docs/core_components/search/for_python_developers.rst +++ b/docs/core_components/search/indexing.rst @@ -1,34 +1,63 @@ -.. _wagtailsearch_for_python_developers: +.. _wagtailsearch_indexing: -===================== -For Python developers -===================== +======== +Indexing +======== + +To make a model searchable, you'll firstly need to add it into the search index. All pages, images and documents are indexed for you and you can start searching them right away. + +If you have created some extra fields in a subclass of Page or Image, you may want to add these new fields to the search index too so a users search query will match on their content. See :ref:`wagtailsearch_indexing_fields` for info on how to do this. + +If you have a custom model that you would like to make searchable, see :ref:`wagtailsearch_indexing_models`. -Basic usage -=========== - -By default using the :ref:`wagtailsearch_backends_database`, Wagtail's search will only index the ``title`` field of pages. - -All searches are performed on Django QuerySets. Wagtail provides a ``search`` method on the queryset for all page models: - -.. code-block:: python - - # Search future EventPages - >>> from wagtail.wagtailcore.models import EventPage - >>> EventPage.objects.filter(date__gt=timezone.now()).search("Hello world!") +.. _wagtailsearch_indexing_update: -All methods of ``PageQuerySet`` are supported by wagtailsearch: +Updating the index +================== -.. code-block:: python +If the search index is kept separate from the database (when using Elasticsearch for example), you need to keep them both in sync. Theres two ways to do this: using the search signal handlers or calling the ``update_index`` command periodically. For best speed and reliability, it's best to use both if possible. - # Search all live EventPages that are under the events index - >>> EventPage.objects.live().descendant_of(events_index).search("Event") - [, ] +Signal handlers +--------------- + +Wagtailsearch provides some signal handlers which bind to the save/delete signals of all indexed models. This would add and delete them from all backends you have registered in ``WAGTAILSEARCH_BACKENDS`` automatically. + +To register the signal handlers, add the following code somewhere it would be executed at startup. We reccommend adding this to your projects ``urls.py``: + +.. code-block: python + + # urls.py + from wagtail.wagtailsearch.signal_handlers import register_signal_handlers + + register_signal_handlers() + + +.. note:: + + If your project was made with the ``wagtail start`` command, this should already be set up for you. + + +The ``update_index`` command +---------------------------- + +Wagtail also provides a command for rebuilding the index from scratch. + +:code:`./manage.py update_index` + +It is recommended to run this command once a week and at the following times: + + - whenever any pages have been created through a script (after an import, for example) + - whenever any changes have been made to models or search configuration + +The search may not return any results while this command is running, so avoid running it at peak times. + + +.. _wagtailsearch_indexing_fields: Indexing extra fields ===================== @@ -51,7 +80,7 @@ Fields must be explicitly added to the ``search_fields`` property of your ``Page Example -------------- +------- This creates an ``EventPage`` model with two fields ``description`` and ``date``. ``description`` is indexed as a ``SearchField`` and ``date`` is indexed as a ``FilterField`` @@ -75,7 +104,7 @@ This creates an ``EventPage`` model with two fields ``description`` and ``date`` ``index.SearchField`` ------------------------ +--------------------- These are added to the search index and are used for performing full-text searches on your models. These would usually be text fields. @@ -89,7 +118,7 @@ Options ``index.FilterField`` ------------------------ +--------------------- These are added to the search index but are not used for full-text searches. Instead, they allow you to run filters on your search results. @@ -128,6 +157,8 @@ One use for this is indexing ``get_*_display`` methods Django creates automatica ) +.. _wagtailsearch_indexing_models: + Indexing non-page models ======================== diff --git a/docs/core_components/search/frontend_views.rst b/docs/core_components/search/searching.rst similarity index 65% rename from docs/core_components/search/frontend_views.rst rename to docs/core_components/search/searching.rst index 1e1ad3fd32..a5876d77f0 100644 --- a/docs/core_components/search/frontend_views.rst +++ b/docs/core_components/search/searching.rst @@ -1,4 +1,67 @@ +.. _wagtailsearch_searching: + + +========= +Searching +========= + + +.. _wagtailsearch_searching_pages: + +Searching Pages +=============== + +Wagtail provides a ``search`` method on the QuerySet for all page models: + +.. code-block:: python + + # Search future EventPages + >>> from wagtail.wagtailcore.models import EventPage + >>> EventPage.objects.filter(date__gt=timezone.now()).search("Hello world!") + + +All methods of ``PageQuerySet`` are supported by wagtailsearch: + +.. code-block:: python + + # Search all live EventPages that are under the events index + >>> EventPage.objects.live().descendant_of(events_index).search("Event") + [, ] + + +Searching Images, Documents and custom models +============================================= + +You can search these by using the ``search`` method on the search backend: + +.. code-block:: python + + >>> from wagtail.wagtailimages.models import Image + >>> from wagtail.wagtailsearch.backends import get_search_backend + + # Search images + >>> s = get_search_backend() + >>> s.search("Hello", Image) + [, ] + + +You can also pass a QuerySet into the ``search`` method which allows you to add filters to your search results: + +.. code-block:: python + + >>> from wagtail.wagtailimages.models import Image + >>> from wagtail.wagtailsearch.backends import get_search_backend + + # Search images + >>> s = get_search_backend() + >>> s.search("Hello", Image.objects.filter(uploaded_by_user=user)) + [] + + +This should work the same way for Documents and custom models as well. + + .. _wagtailsearch_frontend_views: @@ -166,4 +229,47 @@ In this template, you'll have access to the same context variables provided to t Custom Search Views ------------------- -This functionality is still under active development to provide a streamlined interface, but take a look at ``wagtail/wagtail/wagtailsearch/views/frontend.py`` if you are interested in coding custom search views. \ No newline at end of file +This functionality is still under active development to provide a streamlined interface, but take a look at ``wagtail/wagtail/wagtailsearch/views/frontend.py`` if you are interested in coding custom search views. + + + +.. _editors-picks: + + +Editor's picks +============== + +Editor's picks are a way of explicitly linking relevant content to search terms, so results pages can contain curated content in addition to results from the search algorithm. In a template using the search results view, editor's picks can be accessed through the variable ``query.editors_picks``. To include editor's picks in your search results template, use the following properties. + +``query.editors_picks.all`` + This gathers all of the editor's picks objects relating to the current query, in order according to their sort order in the Wagtail admin. You can then iterate through them using a ``{% for ... %}`` loop. Each editor's pick object provides these properties: + + ``editors_pick.page`` + The page object associated with the pick. Use ``{% pageurl editors_pick.page %}`` to generate a URL or provide other properties of the page object. + + ``editors_pick.description`` + The description entered when choosing the pick, perhaps explaining why the page is relevant to the search terms. + +Putting this all together, a block of your search results template displaying editor's picks might look like this: + +.. code-block:: django + + {% with query.editors_picks.all as editors_picks %} + {% if editors_picks %} +
+

Editors picks

+ +
+ {% endif %} + {% endwith %}