Merge pull request django-cms#2249 from yakky/feature/ph_docs

Fix PlaceholderField documentation

Author: yakky

docs/extending_cms/placeholders.rst

@@ -4,16 +4,21 @@ Placeholders outside the CMS
 
 Placeholders are special model fields that django CMS uses to render
 user-editable content (plugins) in templates. That is, it's the place where a
-user can add text, video or any other plugin to a webpage, using either the
-normal Django admin interface or the so called `frontend editing`.
+user can add text, video or any other plugin to a webpage, using the same
+`frontend editing` as the CMS pages.
 
 Placeholders can be viewed as containers for :class:`CMSPlugin` instances, and
 can be used outside the CMS in custom applications using the
 :class:`~cms.models.fields.PlaceholderField`.
 
-By defining one (or several) :class:`~cms.models.fields.PlaceholderField` on a custom model you can take
-advantage of the full power of :class:`CMSPlugin`, including frontend editing.
+By defining one (or several) :class:`~cms.models.fields.PlaceholderField` on a
+custom model you can take advantage of the full power of :class:`CMSPlugin`.
 
+.. warning::
+
+    Screenshots are not in sync with the 3.0 UI at the moment, they will be
+    updated once the new UI will be finalized; for the same reason, you'll find
+    minor difference in the UI description.
 
 **********
 Quickstart
@@ -57,6 +62,8 @@ placeholder (configuration is the same as for placeholders in the CMS) or you ca
 Admin Integration
 =================
 
+.. versionchanged:: 3.0
+
 If you install this model in the admin application, you have to use
 :class:`~cms.admin.placeholderadmin.PlaceholderAdmin` instead of
 :class:`~django.contrib.admin.ModelAdmin` so the interface renders
@@ -69,6 +76,14 @@ correctly::
     admin.site.register(MyModel, PlaceholderAdmin)
 
 
+.. warning::
+
+    Since 3.0 placeholder content can only be modified from the
+    frontend, and thus placeholderfields **must** not be present in any
+    ``fieldsets``, ``fields``, ``form`` or other modeladmin fields definition
+    attribute.
+
+
 I18N Placeholders
 =================
 
@@ -115,10 +130,15 @@ Now to render the placeholder in a template you use the
 
     {% render_placeholder mymodel_instance.my_placeholder "640" %}
 
-The :ttag:`render_placeholder` tag takes a
-:class:`~cms.models.fields.PlaceholderField` instance as its first argument and
-optionally accepts a width parameter as its second argument for context sensitive
-plugins. The view in which you render your placeholder field must return the
+The :ttag:`render_placeholder` tag takes the following parameters:
+
+* :class:`~cms.models.fields.PlaceholderField` instance
+* ``width`` parameter for context sensitive plugins (optional)
+* ``language`` keyword plus ``language-code`` string to render content in the
+  specified language (optional)
+
+
+The view in which you render your placeholder field must return the
 :attr:`request <django.http.HttpRequest>` object in the context. This is
 typically achieved in Django applications by using :class:`RequestContext`::
 
@@ -145,36 +165,34 @@ like this:
 Adding content to a placeholder
 *******************************
 
-There are two ways to add or edit content to a placeholder, the front-end admin
-view and the back-end view.
+.. versionchanged:: 3.0
 
-Using the front-end editor
-==========================
-
-Probably the simplest way to add content to a placeholder, simply visit the
+Placeholders can be edited from the frontend by visiting the
 page displaying your model (where you put the :ttag:`render_placeholder` tag),
-then append ``?edit`` to the page's URL. This will make a top banner appear,
-and after switching the "Edit mode" button to "on", the banner will prompt you
-for your username and password (the user should be allowed to edit the page,
-obviously).
+then append ``?edit`` to the page's URL.
+This will make the frontend editor top banner appear, and will eventually
+require you to login.
 
-You are now using the so-called *front-end edit mode*:
+You are now using the so-called *frontend edit mode*:
 
 |edit-banner|
 
 .. |edit-banner| image:: ../images/edit-banner.png
 
-Once in Front-end editing mode, your placeholders should display a menu,
-allowing you to add plugins to them. The following screen shot shows a
-default selection of plugins in an empty placeholder.
+Once in Front-end editing mode, switch to **Structure mode**, and you should be
+able to see an outline of the placeholder, and a menu, allowing you to add
+plugins to them. The following screenshot shows a default selection of plugins
+in an empty placeholder.
 
 |frontend-placeholder-add-plugin|
 
 .. |frontend-placeholder-add-plugin| image:: ../images/frontend-placeholder-add-plugin.png
 
-Plugins are rendered at once, so you can get an idea how it will look
-`in fine`. However, to view the final look of a plugin simply leave edit mode by
-clicking the "Edit mode" button in the banner again.
+Adding the plugins automatically update the model content and they are rendered
+in realtime.
+
+There is no automatic draft / live version of general Django models, so plugins
+content is updated instantly whenever you add / edit them.
 
 .. _placeholder_object_permissions:
 
@@ -202,18 +220,4 @@ to current user only on his ``UserProfile`` object::
         return False
 
 
-*********
-Fieldsets
-*********
-
-There are some hard restrictions if you want to add custom fieldsets to an
-admin page with at least one :class:`~cms.models.fields.PlaceholderField`:
-
-1. Every :class:`~cms.models.fields.PlaceholderField` **must** be in its own
-   :attr:`fieldset <django.contrib.admin.ModelAdmin.fieldsets>`, one
-   :class:`~cms.models.fields.PlaceholderField` per fieldset.
-2. You **must** include the following two classes: ``'plugin-holder'`` and
-   ``'plugin-holder-nopage'``
-
-
 .. _django-hvad: https://github.com/kristianoellegaard/django-hvad