You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

212 lines
13 KiB

  1. ============
  2. Web timeline
  3. ============
  4. .. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  5. !! This file is generated by oca-gen-addon-readme !!
  6. !! changes will be overwritten. !!
  7. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  8. .. |badge1| image:: https://img.shields.io/badge/maturity-Production%2FStable-green.png
  9. :target: https://odoo-community.org/page/development-status
  10. :alt: Production/Stable
  11. .. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
  12. :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
  13. :alt: License: AGPL-3
  14. .. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fweb-lightgray.png?logo=github
  15. :target: https://github.com/OCA/web/tree/12.0/web_timeline
  16. :alt: OCA/web
  17. .. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
  18. :target: https://translation.odoo-community.org/projects/web-12-0/web-12-0-web_timeline
  19. :alt: Translate me on Weblate
  20. .. |badge5| image:: https://img.shields.io/badge/runbot-Try%20me-875A7B.png
  21. :target: https://runbot.odoo-community.org/runbot/162/12.0
  22. :alt: Try me on Runbot
  23. |badge1| |badge2| |badge3| |badge4| |badge5|
  24. Define a new view displaying events in an interactive visualization chart.
  25. The widget is based on the external library
  26. http://visjs.org/timeline_examples.html
  27. **Table of contents**
  28. .. contents::
  29. :local:
  30. Configuration
  31. =============
  32. You need to define a view with the tag <timeline> as base element. These are
  33. the possible attributes for the tag:
  34. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  35. | Attribute | Required? | Description |
  36. +====================+===========+===========================================================================================================================================================================================================================================================================+
  37. | date_start | **Yes** | Defines the name of the field of type date that contains the start of the event. |
  38. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  39. | date_stop | No | Defines the name of the field of type date that contains the end of the event. The date_stop can be equal to the attribute date_start to display events has 'point' on the Timeline (instantaneous event). |
  40. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  41. | date_delay | No | Defines the name of the field of type float/integer that contain the duration in hours of the event, default = 1. |
  42. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  43. | default_group_by | **Yes** | Defines the name of the field that will be taken as default group by when accessing the view or when no other group by is selected. |
  44. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  45. | zoomKey | No | Specifies whether the Timeline is only zoomed when an additional key is down. Available values are '' (does not apply), 'altKey', 'ctrlKey', or 'metaKey'. Set this option if you want to be able to use the scroll to navigate vertically on views with a lot of events. |
  46. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  47. | mode | No | Specifies the initial visible window. Available values are: 'day' to display the current day, 'week', 'month' and 'fit'. Default value is 'fit' to adjust the visible window such that it fits all items. |
  48. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  49. | event_open_popup | No | When set to true, it allows to edit the events in a popup. If not (default value), the record is edited changing to form view. |
  50. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  51. | colors | No | Allows to set certain specific colors if the expressed condition (JS syntax) is met. |
  52. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  53. | dependency_arrow | No | Set this attribute to a x2many field to draw arrows between the records referenced in the x2many field. |
  54. +--------------------+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  55. Optionally you can declare a custom template, which will be used to render the
  56. timeline items. You have to name the template 'timeline-item'.
  57. These are the variables available in template rendering:
  58. * ``record``: to access the fields values selected in the timeline definition.
  59. * ``field_utils``: used to format and parse values (see available functions in ``web.field_utils``).
  60. You also need to declare the view in an action window of the involved model.
  61. Example:
  62. .. code-block:: xml
  63. <?xml version="1.0" encoding="utf-8"?>
  64. <odoo>
  65. <record id="view_task_timeline" model="ir.ui.view">
  66. <field name="model">project.task</field>
  67. <field name="type">timeline</field>
  68. <field name="arch" type="xml">
  69. <timeline date_start="date_start"
  70. date_stop="date_end"
  71. string="Tasks"
  72. default_group_by="user_id"
  73. event_open_popup="true"
  74. zoomKey="ctrlKey"
  75. colors="#ec7063:user_id == false;#2ecb71:kanban_state=='done';"
  76. dependency_arrow="task_dependency_ids">
  77. <field name="user_id"/>
  78. <templates>
  79. <div t-name="timeline-item">
  80. <div t-esc="record.display_name"/>
  81. Assigned to:
  82. <span t-esc="record.user_id[1]"/>
  83. </div>
  84. </templates>
  85. </timeline>
  86. </field>
  87. </record>
  88. <record id="project.action_view_task" model="ir.actions.act_window">
  89. <field name="view_mode">kanban,tree,form,calendar,gantt,timeline,graph</field>
  90. </record>
  91. </odoo>
  92. Usage
  93. =====
  94. For accessing the timeline view, you have to click on the button with the clock
  95. icon in the view switcher. The first time you access to it, the timeline window
  96. is zoomed to fit all the current elements, the same as when you perform a
  97. search, filter or group by operation.
  98. You can use the mouse scroll to zoom in or out in the timeline, and click on
  99. any free area and drag for panning the view in that direction.
  100. The records of your model will be shown as rectangles whose widths are the
  101. duration of the event according our definition. You can select them clicking
  102. on this rectangle. You can also use Ctrl or Shift keys for adding discrete
  103. or range selections. Selected records are hightlighted with a different color
  104. (but the difference will be more noticeable depending on the background color).
  105. Once selected, you can drag and move the selected records across the timeline.
  106. When a record is selected, a red cross button appears on the upper left corner
  107. that allows to remove that record. This doesn't work for multiple records
  108. although they were selected.
  109. Records are grouped in different blocks depending on the group by criteria
  110. selected (if none is specified, then the default group by is applied).
  111. Dragging a record from one block to another change the corresponding field to
  112. the value that represents the block. You can also click on the group name to
  113. edit the involved record directly.
  114. Double-click on the record to edit it. Double-click in open area to create a
  115. new record with the group and start date linked to the area you clicked in.
  116. By holding the Ctrl key and dragging left to right, you can create a new record
  117. with the dragged start and end date.
  118. Known issues / Roadmap
  119. ======================
  120. * Implement a more efficient way of refreshing timeline after a record update;
  121. * Make `attrs` attribute work;
  122. * Make action attributes work (create, edit, delete) like in form and tree views.
  123. Bug Tracker
  124. ===========
  125. Bugs are tracked on `GitHub Issues <https://github.com/OCA/web/issues>`_.
  126. In case of trouble, please check there if your issue has already been reported.
  127. If you spotted it first, help us smashing it by providing a detailed and welcomed
  128. `feedback <https://github.com/OCA/web/issues/new?body=module:%20web_timeline%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
  129. Do not contact contributors directly about support or help with technical issues.
  130. Credits
  131. =======
  132. Authors
  133. ~~~~~~~
  134. * ACSONE SA/NV
  135. * Tecnativa
  136. * Monk Software
  137. * Onestein
  138. Contributors
  139. ~~~~~~~~~~~~
  140. * Laurent Mignon <laurent.mignon@acsone.eu>
  141. * Adrien Peiffer <adrien.peiffer@acsone.eu>
  142. * Pedro M. Baeza <pedro.baeza@tecnativa.com>
  143. * Leonardo Donelli <donelli@webmonks.it>
  144. * Adrien Didenot <adrien.didenot@horanet.com>
  145. * Dennis Sluijk <d.sluijk@onestein.nl>
  146. Other credits
  147. ~~~~~~~~~~~~~
  148. Images
  149. ------
  150. * Odoo Community Association: `Icon <https://github.com/OCA/maintainer-tools/blob/master/template/module/static/description/icon.svg>`_.
  151. Maintainers
  152. ~~~~~~~~~~~
  153. This module is maintained by the OCA.
  154. .. image:: https://odoo-community.org/logo.png
  155. :alt: Odoo Community Association
  156. :target: https://odoo-community.org
  157. OCA, or the Odoo Community Association, is a nonprofit organization whose
  158. mission is to support the collaborative development of Odoo features and
  159. promote its widespread use.
  160. .. |maintainer-tarteo| image:: https://github.com/tarteo.png?size=40px
  161. :target: https://github.com/tarteo
  162. :alt: tarteo
  163. Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
  164. |maintainer-tarteo|
  165. This module is part of the `OCA/web <https://github.com/OCA/web/tree/12.0/web_timeline>`_ project on GitHub.
  166. You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.