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.

218 lines
7.5 KiB

10 years ago
10 years ago
  1. ===========================
  2. 2D matrix for x2many fields
  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-Beta-yellow.png
  9. :target: https://odoo-community.org/page/development-status
  10. :alt: Beta
  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_widget_x2many_2d_matrix
  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_widget_x2many_2d_matrix
  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. This module allows to show an x2many field with 3-tuples
  25. ($x_value, $y_value, $value) in a table
  26. +-----------+-------------+-------------+
  27. | | $x_value1 | $x_value2 |
  28. +===========+=============+=============+
  29. | $y_value1 | $value(1/1) | $value(2/1) |
  30. +-----------+-------------+-------------+
  31. | $y_value2 | $value(1/2) | $value(2/2) |
  32. +-----------+-------------+-------------+
  33. where `value(n/n)` is editable.
  34. An example use case would be: Select some projects and some employees so that
  35. a manager can easily fill in the planned_hours for one task per employee. The
  36. result could look like this:
  37. .. image:: https://raw.githubusercontent.com/web_widget_x2many_2d_matrix/static/description/screenshot.png
  38. :alt: Screenshot
  39. The beauty of this is that you have an arbitrary amount of columns with this
  40. widget, trying to get this in standard x2many lists involves some quite ugly
  41. hacks.
  42. **Table of contents**
  43. .. contents::
  44. :local:
  45. Usage
  46. =====
  47. Use this widget by saying::
  48. <field name="my_field" widget="x2many_2d_matrix" />
  49. This assumes that my_field refers to a model with the fields `x`, `y` and
  50. `value`. If your fields are named differently, pass the correct names as
  51. attributes:
  52. .. code-block:: xml
  53. <field name="my_field" widget="x2many_2d_matrix" field_x_axis="my_field1" field_y_axis="my_field2" field_value="my_field3">
  54. <tree>
  55. <field name="my_field"/>
  56. <field name="my_field1"/>
  57. <field name="my_field2"/>
  58. <field name="my_field3"/>
  59. </tree>
  60. </field>
  61. You can pass the following parameters:
  62. field_x_axis
  63. The field that indicates the x value of a point
  64. field_y_axis
  65. The field that indicates the y value of a point
  66. field_label_x_axis
  67. Use another field to display in the table header
  68. field_label_y_axis
  69. Use another field to display in the table header
  70. field_value
  71. Show this field as value
  72. show_row_totals
  73. If field_value is a numeric field, it indicates if you want to calculate
  74. row totals. True by default
  75. show_column_totals
  76. If field_value is a numeric field, it indicates if you want to calculate
  77. column totals. True by default
  78. Example
  79. ~~~~~~~
  80. You need a data structure already filled with values. Let's assume we want to
  81. use this widget in a wizard that lets the user fill in planned hours for one
  82. task per project per user. In this case, we can use ``project.task`` as our
  83. data model and point to it from our wizard. The crucial part is that we fill
  84. the field in the default function:
  85. .. code-block:: python
  86. from odoo import fields, models
  87. class MyWizard(models.TransientModel):
  88. _name = 'my.wizard'
  89. def _default_task_ids(self):
  90. # your list of project should come from the context, some selection
  91. # in a previous wizard or wherever else
  92. projects = self.env['project.project'].browse([1, 2, 3])
  93. # same with users
  94. users = self.env['res.users'].browse([1, 2, 3])
  95. return [
  96. (0, 0, {
  97. 'name': 'Sample task name',
  98. 'project_id': p.id,
  99. 'user_id': u.id,
  100. 'planned_hours': 0,
  101. 'message_needaction': False,
  102. 'date_deadline': fields.Date.today(),
  103. })
  104. # if the project doesn't have a task for the user,
  105. # create a new one
  106. if not p.task_ids.filtered(lambda x: x.user_id == u) else
  107. # otherwise, return the task
  108. (4, p.task_ids.filtered(lambda x: x.user_id == u)[0].id)
  109. for p in projects
  110. for u in users
  111. ]
  112. task_ids = fields.Many2many('project.task', default=_default_task_ids)
  113. Now in our wizard, we can use:
  114. .. code-block:: xml
  115. <field name="task_ids" widget="x2many_2d_matrix" field_x_axis="project_id" field_y_axis="user_id" field_value="planned_hours">
  116. <tree>
  117. <field name="task_ids"/>
  118. <field name="project_id"/>
  119. <field name="user_id"/>
  120. <field name="planned_hours"/>
  121. </tree>
  122. </field>
  123. Known issues / Roadmap
  124. ======================
  125. * Support extra attributes on each field cell via `field_extra_attrs` param.
  126. We could set a cell as not editable, required or readonly for instance.
  127. The `readonly` case will also give the ability
  128. to click on m2o to open related records.
  129. * Support limit total records in the matrix. Ref: https://github.com/OCA/web/issues/901
  130. * Support cell traversal through keyboard arrows.
  131. * Entering the widget from behind by pressing ``Shift+TAB`` in your keyboard
  132. will enter into the 1st cell until https://github.com/odoo/odoo/pull/26490
  133. is merged.
  134. * Support extra invisible fields inside each cell.
  135. Bug Tracker
  136. ===========
  137. Bugs are tracked on `GitHub Issues <https://github.com/OCA/web/issues>`_.
  138. In case of trouble, please check there if your issue has already been reported.
  139. If you spotted it first, help us smashing it by providing a detailed and welcomed
  140. `feedback <https://github.com/OCA/web/issues/new?body=module:%20web_widget_x2many_2d_matrix%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
  141. Do not contact contributors directly about support or help with technical issues.
  142. Credits
  143. =======
  144. Authors
  145. ~~~~~~~
  146. * Therp BV
  147. * Tecnativa
  148. * Camptocamp
  149. Contributors
  150. ~~~~~~~~~~~~
  151. * Holger Brunn <hbrunn@therp.nl>
  152. * Pedro M. Baeza <pedro.baeza@tecnativa.com>
  153. * Artem Kostyuk <a.kostyuk@mobilunity.com>
  154. * Simone Orsi <simone.orsi@camptocamp.com>
  155. * Timon Tschanz <timon.tschanz@camptocamp.com>
  156. * Jairo Llopis <jairo.llopis@tecnativa.com>
  157. * Dennis Sluijk <d.sluijk@onestein.nl>
  158. * Alexey Pelykh <alexey.pelykh@brainbeanapps.com>
  159. Maintainers
  160. ~~~~~~~~~~~
  161. This module is maintained by the OCA.
  162. .. image:: https://odoo-community.org/logo.png
  163. :alt: Odoo Community Association
  164. :target: https://odoo-community.org
  165. OCA, or the Odoo Community Association, is a nonprofit organization whose
  166. mission is to support the collaborative development of Odoo features and
  167. promote its widespread use.
  168. This module is part of the `OCA/web <https://github.com/OCA/web/tree/12.0/web_widget_x2many_2d_matrix>`_ project on GitHub.
  169. You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.