[DOC] web: add documentation to use calendar

The calendar view was changed with the new view, but the documentation
was not updated.

1 files changed, 45 insertions, 21 deletions

diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index 853104bfaa6..e5b5d8044f8 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -953,24 +953,20 @@ calendar view are:
     directly in the calendar
 ``date_delay``
     alternative to ``date_stop``, provides the duration of the event instead of
-    its end date
-
-    .. todo:: what's the unit? Does it allow moving the record?
-
+    its end date (unit: day)
 ``color``
     name of a record field to use for *color segmentation*. Records in the
     same color segment are allocated the same highlight color in the calendar,
     colors are allocated semi-randomly.
-``event_open_popup``
-    opens the event in a dialog instead of switching to the form view, disabled
-    by default
+    Displayed the display_name/avatar of the visible record in the sidebar
+``readonly_form_view_id``
+    view to open in readonly mode
+``form_view_id``
+    view to open when the user create or edit an event
 ``quick_add``
     enables quick-event creation on click: only asks the user for a ``name``
     and tries to create a new event with just that and the clicked event
     time. Falls back to a full form dialog if the quick creation fails
-``display``
-    format string for event display, field names should be within brackets
-    ``[`` and ``]``
 ``all_day``
     name of a boolean field on the record indicating whether the corresponding
     event is flagged as day-long (and duration is irrelevant)
@@ -978,21 +974,49 @@ calendar view are:
     Default display mode when loading the calendar.
     Possible attributes are: ``day``, ``week``, ``month``
 
+``<field>``
+  declares fields to aggregate or to use in kanban *logic*. If the field is
+  simply displayed in the calendar cards.
 
-.. todo::
-
-   what's the purpose of ``<field>`` inside a calendar view?
-
-.. todo::
+On each field can have additional attributes:
+  ``invisible``: use "True" to hide the value in the cards
+  ``avatar_field``: only for x2many field, to display the avatar instead the
+      display_name in the cards
+  ``write_model`` and ``write_field``: you can add a filter and save the result
+      in the defined model, the filter is added in the sidebar
 
-   calendar code is an unreadable mess, no idea what these things are:
+``templates``
+  defines the :ref:`reference/qweb` template ``calendar-box``. Cards definition
+  may be split into multiple templates for clarity which will be rendered once
+  for each record.
 
-   * ``attendee``
-   * ``avatar_model``
-   * ``use_contacts``
+  The kanban view uses mostly-standard :ref:`javascript qweb
+  <reference/qweb/javascript>` and provides the following context variables:
 
-   calendar code also seems to refer to multiple additional attributes of
-   unknown purpose
+  ``instance``
+    the current :ref:`reference/javascript/client` instance
+  ``widget``
+    the current :js:class:`KanbanRecord`, can be used to fetch some
+    meta-information. These methods are also available directly in the
+    template context and don't need to be accessed via ``widget``
+    ``getColor`` to convert in a color integer
+    ``getAvatars`` to convert in an avatar image
+    ``displayFields`` list of not invisible fields
+  ``record``
+    an object with all the requested fields as its attributes. Each field has
+    two attributes ``value`` and ``raw_value``
+  ``event``
+    the calendar event object
+  ``format``
+    format method to convert values into a readable string with the user
+    parameters
+  ``fields``
+    definition of all model fields
+    parameters
+  ``user_context``
+    self-explanatory
+  ``read_only_mode``
+    self-explanatory
 
 .. _reference/views/gantt: