.. _ref-highlighting: ============ Highlighting ============ Haystack supports two different methods of highlighting. You can either use ``SearchQuerySet.highlight`` or the built-in ``{% highlight %}`` template tag, which uses the ``Highlighter`` class. Each approach has advantages and disadvantages you need to weigh when deciding which to use. If you want portable, flexible, decently fast code, the ``{% highlight %}`` template tag (or manually using the underlying ``Highlighter`` class) is the way to go. On the other hand, if you care more about speed and will only ever be using one backend, ``SearchQuerySet.highlight`` may suit your needs better. Use of ``SearchQuerySet.highlight`` is documented in the :doc:`searchqueryset_api` documentation and the ``{% highlight %}`` tag is covered in the :doc:`templatetags` documentation, so the rest of this material will cover the ``Highlighter`` implementation. ``Highlighter`` --------------- The ``Highlighter`` class is a pure-Python implementation included with Haystack that's designed for flexibility. If you use the ``{% highlight %}`` template tag, you'll be automatically using this class. You can also use it manually in your code. For example:: >>> from haystack.utils import Highlighter >>> my_text = 'This is a sample block that would be more meaningful in real life.' >>> my_query = 'block meaningful' >>> highlight = Highlighter(my_query) >>> highlight.highlight(my_text) u'...block that would be more meaningful in real life.' The default implementation takes three optional kwargs: ``html_tag``, ``css_class`` and ``max_length``. These allow for basic customizations to the output, like so:: >>> from haystack.utils import Highlighter >>> my_text = 'This is a sample block that would be more meaningful in real life.' >>> my_query = 'block meaningful' >>> highlight = Highlighter(my_query, html_tag='div', css_class='found', max_length=35) >>> highlight.highlight(my_text) u'...