Skip to content

Commit

Permalink
fix(docs): Update documentation regarding inheritance (#665)
Browse files Browse the repository at this point in the history
Closes #663
  • Loading branch information
Hafnernuss committed Nov 28, 2022
1 parent bd18fa4 commit ca31a21
Showing 1 changed file with 26 additions and 4 deletions.
30 changes: 26 additions & 4 deletions docs/modeltranslation/registration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,29 +77,51 @@ explains how things are working under the hood.
.. versionadded:: 0.5

A subclass of any ``TranslationOptions`` will inherit fields from its bases
(similar to the way Django models inherit fields, but with a different syntax). ::
(similar to the way Django models inherit fields, but with a different syntax).
When dealing with abstract base classes, this can be handy::

from modeltranslation.translator import translator, TranslationOptions
from news.models import News, NewsWithImage

class NewsTranslationOptions(TranslationOptions):
class AbstractNewsTranslationOptions(TranslationOptions):
fields = ('title', 'text',)

class NewsWithImageTranslationOptions(NewsTranslationOptions):
class NewsWithImageTranslationOptions(AbstractNewsTranslationOptions):
fields = ('image',)

translator.register(News, NewsTranslationOptions)
translator.register(NewsWithImage, NewsWithImageTranslationOptions)

The above example adds the fields ``title`` and ``text`` from the
``NewsTranslationOptions`` class to ``NewsWithImageTranslationOptions``, or to
``AbstractNewsTranslationOptions`` class to ``NewsWithImageTranslationOptions``, or to
say it in code::

assert NewsWithImageTranslationOptions.fields == ('title', 'text', 'image')

Of course multiple inheritance and inheritance chains (A > B > C) also work as
expected.

However, if the base class is not abstract, inheriting the ``TranslationOptions`` will
cause errors, because the base ``TranslationOptions`` already took care of adding
fields to the model. The example below illustrates how to add translation fields to a
child model with a non-abstract base::

from modeltranslation.translator import translator, TranslationOptions
from news.models import News, NewsWithImage

class NewsTranslationOptions(TranslationOptions):
fields = ('title', 'text',)

class NewsWithImageTranslationOptions(TranslationOptions):
fields = ('image',)

translator.register(News, NewsTranslationOptions)
translator.register(NewsWithImage, NewsWithImageTranslationOptions)


This will add the translated fields ``title`` and ``text`` to the ``News`` model and further add
the translated field ``image`` to the ``NewsWithImage`` model.

.. note:: When upgrading from a previous modeltranslation version (<0.5), please
review your ``TranslationOptions`` classes and see if introducing `fields
inheritance` broke the project (if you had always subclassed
Expand Down

0 comments on commit ca31a21

Please sign in to comment.