Skip to content

Commit

Permalink
link to the official docs in the README instead of reproducing it (in…
Browse files Browse the repository at this point in the history
…completely)
  • Loading branch information
beniwohli committed Apr 18, 2011
1 parent 427daf3 commit 77ed9de
Showing 1 changed file with 2 additions and 62 deletions.
64 changes: 2 additions & 62 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,65 +12,5 @@ After installing django-cms-search through your package manager of choice, add `

For setting up Haystack, please refer to their `documentation <http://docs.haystacksearch.org/dev/>`_.

Customizing the Index
---------------------

You can customize what parts of a ``CMSPlugin`` end up in the index with two class attributes on ``CMSPlugin``
subclasses:

* ``search_fields``: a list of field names to index.
* ``search_fulltext``: if ``True``, the index renders the plugin and adds the result (sans HTML tags) to the index.

Helpers
=======

django-cms-search provides a couple of useful helpers to deal with multilingual content.

``cms_search.helpers.indexes.MultiLanguageIndex``
-------------------------------------------------

A ``SearchIndex`` that dynamically adds translated fields to the search index. An example for when this is useful is the
app hook infrastructure from django CMS. When a model's ``get_absolute_url`` uses a url pattern that is attached to an
app hook, the URL varies depending on the language. A usage example::

from haystack import indexes
from cms_search.helpers.indexes import MultiLanguageIndex

class NewsIndex(MultiLanguageIndex):
text = indexes.CharField(document=True, use_template=True)
title = indexes.CharField(model_attr='title')
url = indexes.CharField(stored=True)

def prepare_url(self, obj):
return obj.get_absolute_url()

class HaystackTrans:
fields = ('url', 'title')

A few things to note:

* ``MultiLanguageIndex`` dynamically creates translated fields. The name of the dynamic fields is a concatenation of the
original field name, an underscore and the language code.
* If you define a ``prepare`` method for a translated field, that method will be called multiple times, with changing
active language.
* In the above example, you might want to catch ``NoReverseMatch`` exceptions if you don't have activated the app hook
for all languages defined in ``settings.LANGUAGES``.
* The ``model_attr`` attribute is handled somewhat specially. The index tries to find a field on the model called
``model_attr + '_' + language_code``. If it exists, it is used as the translated value. But it isn't possible to supply
the name of a model method and let the index call it with varying activated languages. Use ``prepare_myfieldname`` for
that case.

``{% get_translated_value %}`` template tag
-------------------------------------------

This template tag is most useful in combination with the ``MultiLanguageIndex``. You can use it while looping through
search results, and it will automatically pick up the translated field for the current language or fall back to another
available language (in the order defined in ``settings.LANGUAGES``). Example::

{% load cms_search %}

<ul class="search-results">
{% for result in page.object_list %}
<li><a href="{% get_translated_value result "url" %}">{% get_translated_value result "title" %}</a></li>
{% endfor %}
</ul>
For more docs, see the ``docs`` folder or the
`online documentation <http://django-cms-search.readthedocs.org/en/latest/>`_.

0 comments on commit 77ed9de

Please sign in to comment.