kopia lustrzana https://github.com/wagtail/wagtail
Merge branch 'kaedroho-docs-changes'
Matt Westcott
commit
a481132798
|
|
@ -1,6 +1,172 @@
|
|||
Images
|
||||
======
|
||||
|
||||
|
||||
.. _image_tag:
|
||||
|
||||
Using images in templates
|
||||
=========================
|
||||
|
||||
.. versionchanged:: 0.4
|
||||
The 'image_tags' tags library was renamed to 'wagtailimages_tags'
|
||||
|
||||
The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
|
||||
|
||||
The syntax for the tag is thus::
|
||||
|
||||
{% image [image] [resize-rule] %}
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% load wagtailimages_tags %}
|
||||
...
|
||||
|
||||
{% image self.photo width-400 %}
|
||||
|
||||
<!-- or a square thumbnail: -->
|
||||
{% image self.photo fill-80x80 %}
|
||||
|
||||
In the above syntax example ``[image]`` is the Django object refering to the image. If your page model defined a field called "photo" then ``[image]`` would probably be ``self.photo``. The ``[resize-rule]`` defines how the image is to be resized when inserted into the page; various resizing methods are supported, to cater for different usage cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
|
||||
|
||||
Note that a space separates ``[image]`` and ``[resize-rule]``, but the resize rule must not contain spaces.
|
||||
|
||||
|
||||
The available resizing methods are:
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
``max``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo max-1000x500 %}
|
||||
|
||||
Fit **within** the given dimensions.
|
||||
|
||||
The longest edge will be reduced to the equivalent dimension size defined. e.g A portrait image of width 1000, height 2000, treated with the ``max`` dimensions ``1000x500`` (landscape) would result in the image shrunk so the *height* was 500 pixels and the width 250.
|
||||
|
||||
``min``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo min-500x200 %}
|
||||
|
||||
**Cover** the given dimensions.
|
||||
|
||||
This may result in an image slightly **larger** than the dimensions you specify. e.g A square image of width 2000, height 2000, treated with the ``min`` dimensions ``500x200`` (landscape) would have it's height and width changed to 500, i.e matching the width required, but greater than the height.
|
||||
|
||||
``width``
|
||||
(takes one dimension)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-640 %}
|
||||
|
||||
Reduces the width of the image to the dimension specified.
|
||||
|
||||
``height``
|
||||
(takes one dimension)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo height-480 %}
|
||||
|
||||
Resize the height of the image to the dimension specified..
|
||||
|
||||
``fill``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo fill-200x200 %}
|
||||
|
||||
Resize and **crop** to fill the **exact** dimensions.
|
||||
|
||||
This can be particularly useful for websites requiring square thumbnails of arbitrary images. For example, a landscape image of width 2000, height 1000, treated with ``fill`` dimensions ``200x200`` would have its height reduced to 200, then its width (ordinarily 400) cropped to 200.
|
||||
|
||||
**The crop always aligns on the centre of the image.**
|
||||
|
||||
``original``
|
||||
(takes no dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo original %}
|
||||
|
||||
Leaves the image at its original size - no resizing is performed.
|
||||
|
||||
|
||||
|
||||
.. Note::
|
||||
Wagtail does not allow deforming or stretching images. Image dimension ratios will always be kept. Wagtail also *does not support upscaling*. Small images forced to appear at larger sizes will "max out" at their their native dimensions.
|
||||
|
||||
|
||||
.. _image_tag_alt:
|
||||
|
||||
More control over the ``img`` tag
|
||||
---------------------------------
|
||||
|
||||
Wagtail provides two shortcuts to give greater control over the ``img`` element:
|
||||
|
||||
**1. Adding attributes to the {% image %} tag**
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Extra attributes can be specified with the syntax ``attribute="value"``:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-400 class="foo" id="bar" %}
|
||||
|
||||
No validation is performed on attributes added in this way so it's possible to add `src`, `width`, `height` and `alt` of your own that might conflict with those generated by the tag itself.
|
||||
|
||||
|
||||
**2. Generating the image "as foo" to access individual properties**
|
||||
|
||||
Wagtail can assign the image data to another variable using Django's ``as`` syntax:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-400 as tmp_photo %}
|
||||
|
||||
<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
|
||||
height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />
|
||||
|
||||
|
||||
This syntax exposes the underlying image "Rendition" (``tmp_photo``) to the developer. A "Rendition" contains just the information specific to the way you've requested to format the image i.e dimensions and source URL.
|
||||
|
||||
If your site defines a custom image model using ``AbstractImage``, then any additional fields you add to an image e.g a copyright holder, are **not** part of the image *rendition*, they're part of the image *model*.
|
||||
|
||||
Therefore in the above example, if you'd added the field ``foo`` to your AbstractImage you'd access it using ``{{ self.photo.foo }}`` not ``{{ tmp_photo.foo }}``.
|
||||
|
||||
(Due to the links in the database between renditions and their parent image, you could also access it as ``{{ tmp_photo.image.foo }}`` but this is clearly confusing.)
|
||||
|
||||
|
||||
.. Note::
|
||||
The image property used for the ``src`` attribute is actually ``image.url``, not ``image.src``.
|
||||
|
||||
|
||||
The ``attrs`` shortcut
|
||||
-----------------------
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
You can also use the ``attrs`` property as a shorthand to output the attributes ``src``, ``width``, ``height`` and ``alt`` in one go:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
<img {{ tmp_photo.attrs }} class="my-custom-class" />
|
||||
|
||||
|
||||
|
||||
Advanced topics
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
|
|
|||
|
|
@ -170,7 +170,7 @@ Reference
|
|||
|
||||
.. automethod:: search
|
||||
|
||||
See: :ref:`wagtailsearch_for_python_developers`
|
||||
See: :ref:`wagtailsearch_searching_pages`
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -86,13 +86,9 @@ Template tags & filters
|
|||
In addition to Django's standard tags and filters, Wagtail provides some of its own, which can be ``load``-ed `as you would any other <https://docs.djangoproject.com/en/dev/topics/templates/#custom-tag-and-filter-libraries>`_
|
||||
|
||||
|
||||
.. _image_tag:
|
||||
|
||||
Images (tag)
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. versionchanged:: 0.4
|
||||
The 'image_tags' tags library was renamed to 'wagtailimages_tags'
|
||||
|
||||
The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
|
||||
|
||||
|
|
@ -112,139 +108,8 @@ For example:
|
|||
<!-- or a square thumbnail: -->
|
||||
{% image self.photo fill-80x80 %}
|
||||
|
||||
In the above syntax example ``[image]`` is the Django object refering to the image. If your page model defined a field called "photo" then ``[image]`` would probably be ``self.photo``. The ``[resize-rule]`` defines how the image is to be resized when inserted into the page; various resizing methods are supported, to cater for different usage cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
|
||||
|
||||
Note that a space separates ``[image]`` and ``[resize-rule]``, but the resize rule must not contain spaces.
|
||||
|
||||
|
||||
The available resizing methods are:
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
``max``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo max-1000x500 %}
|
||||
|
||||
Fit **within** the given dimensions.
|
||||
|
||||
The longest edge will be reduced to the equivalent dimension size defined. e.g A portrait image of width 1000, height 2000, treated with the ``max`` dimensions ``1000x500`` (landscape) would result in the image shrunk so the *height* was 500 pixels and the width 250.
|
||||
|
||||
``min``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo min-500x200 %}
|
||||
|
||||
**Cover** the given dimensions.
|
||||
|
||||
This may result in an image slightly **larger** than the dimensions you specify. e.g A square image of width 2000, height 2000, treated with the ``min`` dimensions ``500x200`` (landscape) would have it's height and width changed to 500, i.e matching the width required, but greater than the height.
|
||||
|
||||
``width``
|
||||
(takes one dimension)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-640 %}
|
||||
|
||||
Reduces the width of the image to the dimension specified.
|
||||
|
||||
``height``
|
||||
(takes one dimension)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo height-480 %}
|
||||
|
||||
Resize the height of the image to the dimension specified..
|
||||
|
||||
``fill``
|
||||
(takes two dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo fill-200x200 %}
|
||||
|
||||
Resize and **crop** to fill the **exact** dimensions.
|
||||
|
||||
This can be particularly useful for websites requiring square thumbnails of arbitrary images. For example, a landscape image of width 2000, height 1000, treated with ``fill`` dimensions ``200x200`` would have its height reduced to 200, then its width (ordinarily 400) cropped to 200.
|
||||
|
||||
**The crop always aligns on the centre of the image.**
|
||||
|
||||
``original``
|
||||
(takes no dimensions)
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo original %}
|
||||
|
||||
Leaves the image at its original size - no resizing is performed.
|
||||
|
||||
|
||||
|
||||
.. Note::
|
||||
Wagtail does not allow deforming or stretching images. Image dimension ratios will always be kept. Wagtail also *does not support upscaling*. Small images forced to appear at larger sizes will "max out" at their their native dimensions.
|
||||
|
||||
|
||||
.. _image_tag_alt:
|
||||
|
||||
More control over the ``img`` tag
|
||||
---------------------------------
|
||||
|
||||
Wagtail provides two shorcuts to give greater control over the ``img`` element:
|
||||
|
||||
**1. Adding attributes to the {% image %} tag**
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Extra attributes can be specified with the syntax ``attribute="value"``:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-400 class="foo" id="bar" %}
|
||||
|
||||
No validation is performed on attributes added in this way so it's possible to add `src`, `width`, `height` and `alt` of your own that might conflict with those generated by the tag itself.
|
||||
|
||||
|
||||
**2. Generating the image "as foo" to access individual properties**
|
||||
|
||||
Wagtail can assign the image data to another variable using Django's ``as`` syntax:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
{% image self.photo width-400 as tmp_photo %}
|
||||
|
||||
<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
|
||||
height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />
|
||||
|
||||
|
||||
This syntax exposes the underlying image "Rendition" (``tmp_photo``) to the developer. A "Rendition" contains just the information specific to the way you've requested to format the image i.e dimensions and source URL.
|
||||
|
||||
If your site defines a custom image model using ``AbstractImage``, then any additional fields you add to an image e.g a copyright holder, are **not** part of the image *rendition*, they're part of the image *model*.
|
||||
|
||||
Therefore in the above example, if you'd added the field ``foo`` to your AbstractImage you'd access it using ``{{ self.photo.foo }}`` not ``{{ tmp_photo.foo }}``.
|
||||
|
||||
(Due to the links in the database between renditions and their parent image, you could also access it as ``{{ tmp_photo.image.foo }}`` but this is clearly confusing.)
|
||||
|
||||
|
||||
.. Note::
|
||||
The image property used for the ``src`` attribute is actually ``image.url``, not ``image.src``.
|
||||
|
||||
|
||||
The ``attrs`` shortcut
|
||||
-----------------------
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
You can also use the ``attrs`` property as a shorthand to output the attributes ``src``, ``width``, ``height`` and ``alt`` in one go:
|
||||
|
||||
.. code-block:: django
|
||||
|
||||
<img {{ tmp_photo.attrs }} class="my-custom-class" />
|
||||
See :ref:`image_tag` for full documentation.
|
||||
|
||||
|
||||
.. _rich-text-filter:
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
<div class="well">
|
||||
<h3>Editors picks</h3>
|
||||
<ul>
|
||||
{% for editors_pick in editors_picks %}
|
||||
<li>
|
||||
<h4>
|
||||
<a href="{% pageurl editors_pick.page %}">
|
||||
{{ editors_pick.page.title }}
|
||||
</a>
|
||||
</h4>
|
||||
<p>{{ editors_pick.description|safe }}</p>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endwith %}
|
||||
|
|
@ -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.
|
||||
|
||||
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`
|
||||
|
|
|
|||
|
|
@ -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 that a user's 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. There are 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")
|
||||
[<EventPage: Event 1>, <EventPage: Event 2>]
|
||||
|
||||
Signal handlers
|
||||
---------------
|
||||
|
||||
Wagtailsearch provides some signal handlers which bind to the save/delete signals of all indexed models. This would automatically add and delete them from all backends you have registered in ``WAGTAILSEARCH_BACKENDS``.
|
||||
|
||||
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 will 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
|
||||
========================
|
||||
|
||||
|
|
@ -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")
|
||||
[<EventPage: Event 1>, <EventPage: Event 2>]
|
||||
|
||||
|
||||
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)
|
||||
[<Image: Hello>, <Image: Hello world!>]
|
||||
|
||||
|
||||
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))
|
||||
[<Image: Hello>]
|
||||
|
||||
|
||||
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.
|
||||
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 %}
|
||||
<div class="well">
|
||||
<h3>Editors picks</h3>
|
||||
<ul>
|
||||
{% for editors_pick in editors_picks %}
|
||||
<li>
|
||||
<h4>
|
||||
<a href="{% pageurl editors_pick.page %}">
|
||||
{{ editors_pick.page.title }}
|
||||
</a>
|
||||
</h4>
|
||||
<p>{{ editors_pick.description|safe }}</p>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endwith %}
|
||||
|
|
@ -180,7 +180,7 @@ The old names will continue to work, but output a ``DeprecationWarning`` - you a
|
|||
New search field configuration format
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``indexed_fields`` is now deprecated and has been replaced by a new search field configuration format called ``search_fields``. See :ref:`wagtailsearch_for_python_developers` for how to define a ``search_fields`` property on your models.
|
||||
``indexed_fields`` is now deprecated and has been replaced by a new search field configuration format called ``search_fields``. See :ref:`wagtailsearch_indexing` for how to define a ``search_fields`` property on your models.
|
||||
|
||||
|
||||
``Page.route`` method should now return a ``RouteResult``
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ to the ``INSTALLED_APPS`` list in your project's settings file.
|
|||
Title boost on search reduced to 2
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Wagtail's search interface applies a 'boost' value to give extra weighting to matches on the title field. The original boost value of 100 was found to be excessive, and in Wagtail 0.7 this has been reduced to 2. If you have used comparable boost values on other fields, to give them similar weighting to title, you may now wish to reduce these accordingly. See :ref:`wagtailsearch_for_python_developers`.
|
||||
Wagtail's search interface applies a 'boost' value to give extra weighting to matches on the title field. The original boost value of 100 was found to be excessive, and in Wagtail 0.7 this has been reduced to 2. If you have used comparable boost values on other fields, to give them similar weighting to title, you may now wish to reduce these accordingly. See :ref:`wagtailsearch_indexing`.
|
||||
|
||||
|
||||
Deprecated features
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue