From a3a274ae622c141469ad3f88d8129f4c068e35b1 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek.tomek@gmail.com>
Date: Sat, 9 Nov 2013 14:28:38 +0100
Subject: [PATCH] Add docs about empty_values (close #211).

---
 docs/modeltranslation/admin.rst | 14 +++++
 docs/modeltranslation/forms.rst | 91 +++++++++++++++++++++++++++++++++
 docs/modeltranslation/index.rst |  1 +
 modeltranslation/fields.py      |  2 +-
 4 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 docs/modeltranslation/forms.rst

diff --git a/docs/modeltranslation/admin.rst b/docs/modeltranslation/admin.rst
index 0cd6942..b7f6c4b 100644
--- a/docs/modeltranslation/admin.rst
+++ b/docs/modeltranslation/admin.rst
@@ -319,3 +319,17 @@ A few simple policies are applied:
 
     class NewsAdmin(TranslationAdmin):
         group_fieldsets = True
+
+
+.. _admin-formfield:
+
+Formfields with None-checkbox
+*****************************
+
+There is the special widget which allow to choose whether empty field value should be stores as
+empty string or ``None`` (see :ref:`forms-formfield-both`).
+In ``TranslationAdmin`` some fields can use this widget regardless of their ``empty_values``
+setting::
+
+    class NewsAdmin(TranslationAdmin):
+        both_empty_values_fields = ('title', 'text')
diff --git a/docs/modeltranslation/forms.rst b/docs/modeltranslation/forms.rst
new file mode 100644
index 0000000..b9568a8
--- /dev/null
+++ b/docs/modeltranslation/forms.rst
@@ -0,0 +1,91 @@
+.. _forms:
+
+ModelForms
+==========
+
+Editing multilanguage models with all translation fields in the admin backend is quite sensible.
+However, presenting all model fields to the user on the frontend may be not the right way.
+Here comes the ``TranslationModelForm`` which strip out all translation fields::
+
+    from news.models import News
+    from modeltranslation.forms import TranslationModelForm
+
+    class MyForm(TranslationModelForm):
+        class Meta:
+            model = News
+
+Such a form will contain only original fields (title, text - see :ref:`example <registration>`).
+Of course, upon saving, provided values would be set on proper attributes, depending on the user
+current language.
+
+
+Formfields and nullability
+--------------------------
+
+.. versionadded:: 0.7.1
+
+.. note::
+    Please remember that all translation fields added to model definition are nullable
+    (``null=True``), regardless of the original field nullability.
+
+In most cases formfields for translation fields behave as expected. However, there is one annoying
+problem with ``models.CharField`` - probably the most commonly translated field type.
+
+The problem is that default formfield for ``CharField`` stores empty values as empty strings
+(``''``), even if field is nullable
+(see django `ticket #9590 <http://code.djangoproject.com/ticket/9590>`_).
+
+Thus formfields for translation fields are patched by `MT`. Following rules apply:
+
+.. _formfield_rules:
+
+- If original field is not nullable, empty value would be saved as ``''``;
+- If original field is nullable, empty value would be saved as ``None``.
+
+To deal with complex cases, these rules can be overridden per model or even per field
+(using ``TranslationOptions``)::
+
+    class NewsTranslationOptions(TranslationOptions):
+        fields = ('title', 'text',)
+        empty_values = None
+
+    class ProjectTranslationOptions(TranslationOptions):
+        fields = ('name', 'slug', 'description',)
+        empty_values = {'name': '', 'slug': None}
+
+If a field is not mentioned while using dict syntax, the :ref:`default rules <formfield_rules>`
+apply.
+
+This configuration is especially useful for fields with unique constraints::
+
+    class Category(models.Model):
+        name = models.CharField(max_length=40)
+        slug = models.SlugField(max_length=30, unique=True)
+
+Because the ``slug`` field is not nullable, its translation fields would store empty values as
+``''`` and that would result in error when 2 or more ``Categories`` are saved with
+``slug_en`` empty - unique constraints wouldn't be satisfied. Instead, ``None`` should be stored,
+as several ``None`` values in database don't violate uniqueness::
+
+    class CategoryTranslationOptions(TranslationOptions):
+        fields = ('name', 'slug')
+        empty_values = {'slug': None}
+
+
+.. _forms-formfield-both:
+
+None-checkbox widget
+********************
+
+Maybe there is a situation when somebody want to store in a field both empty strings and ``None``
+values. For such a scenario there is third configuration value: ``'both'``::
+
+    class NewsTranslationOptions(TranslationOptions):
+        fields = ('title', 'text',)
+        empty_values = {'title': None, 'text': 'both'}
+
+It results in special widget with a None-checkbox to null a field. It's not recommended in frontend
+as users may be confused what this `None` is. Probably only useful place for this widget is admin
+backend; see :ref:`admin-formfield`.
+
+To sum up, only valid ``empty_values`` values are: ``None``, ``''`` and ``'both'``.
diff --git a/docs/modeltranslation/index.rst b/docs/modeltranslation/index.rst
index bc01ec0..ec459d7 100644
--- a/docs/modeltranslation/index.rst
+++ b/docs/modeltranslation/index.rst
@@ -14,6 +14,7 @@ Table of Contents
    installation
    registration
    usage
+   forms
    admin
    commands
    caveats
diff --git a/modeltranslation/fields.py b/modeltranslation/fields.py
index f3ae8fb..7ef596c 100644
--- a/modeltranslation/fields.py
+++ b/modeltranslation/fields.py
@@ -177,7 +177,7 @@ class TranslationField(object):
         There are 3 different formfields:
         - CharField that stores all empty values as empty strings;
         - NullCharField that stores all empty values as None (Null);
-        - NullableField that can store both None and empty_string.
+        - NullableField that can store both None and empty string.
 
         By default, if no empty_values was specified in model's translation options,
         NullCharField would be used if the original field is nullable, CharField otherwise.