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.

255 lines
8.1 KiB

9 years ago
  1. .. image:: https://img.shields.io/badge/licence-LGPL--3-blue.svg
  2. :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
  3. :alt: License: LGPL-3
  4. ================
  5. Base Custom Info
  6. ================
  7. This module allows you to attach custom information to records without the need
  8. to alter the database structure too much.
  9. Definitions
  10. ===========
  11. This module defines several concepts that you have to understand.
  12. Templates
  13. ---------
  14. A *template* is a collection of *properties* that a record should have.
  15. *Templates* always apply to a given model, and then you can choose among the
  16. current templates for the model you are using when you edit a record of that
  17. model.
  18. I.e., This addon includes a demo template called "Smart partners", that applies
  19. to the model ``res.partner``, so if you edit any partner, you can choose that
  20. template and get its properties autofilled.
  21. Properties
  22. ----------
  23. A *property* is the "name" of the field. *Templates* can have any amount of
  24. *properties*, and when you apply a *template* to a record, it automatically
  25. gets all of its *properties* filled, empty (unless they have a *Default
  26. value*), ready to assign *values*.
  27. You can set a property to as *required* to force it have a value, although you
  28. should keep in mind that for yes/no properties, this would mean that only *yes*
  29. can be selected, and for numeric properties, zero would be forbidden.
  30. Also you can set *Minimum* and *Maximum* limits for every *property*, but those
  31. limits are only used when the data type is text (to constrain its length) or
  32. number. To skip this constraint, just set a maximum smaller than the minimum.
  33. *Properties* always belong to a template, and as such, to a model.
  34. *Properties* define the data type (text, number, yes/no...), and when the type
  35. is "Selection", then you can define what *options* are available.
  36. I.e., the "Smart partners" *template* has the following *properties*:
  37. - Name of his/her teacher
  38. - Amount of people that hates him/her for being so smart
  39. - Average note on all subjects
  40. - Does he/she believe he/she is the smartest person on earth?
  41. - What weaknesses does he/she have?
  42. When you set that template to any partner, you will then be able to fill these
  43. *properties* with *values*.
  44. Categories
  45. ----------
  46. *Properties* can also belong to a *category*, which allows you to sort them in
  47. a logical way, and makes further development easier.
  48. For example, the ``website_sale_custom_info`` addon uses these to display a
  49. technical datasheet per product in your online shop, sorted and separated by
  50. category.
  51. You are not required to give a *category* to every *property*.
  52. Options
  53. -------
  54. When a *property*'s type is "Selection", then you define the *options*
  55. available, so the *value* must be one of these *options*.
  56. I.e., the "What weaknesses does he/she have?" *property* has some options:
  57. - Loves junk food
  58. - Needs videogames
  59. - Huge glasses
  60. The *value* will always be one of these.
  61. Recursive templates using options
  62. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63. Oh dear customization lovers! Options can be used to customize the custom
  64. information template!
  65. .. figure:: /base_custom_info/static/description/customizations-everywhere.jpg
  66. :alt: Customizations Everywhere
  67. If you assign an *additional template* to an option, and while using the owner
  68. form you choose that option, you can then press *reload custom information
  69. templates* to make the owner update itself to include all the properties in all
  70. the involved templates. If you do not press the button, anyway the reloading
  71. will be performed when saving the owner record.
  72. .. figure:: /base_custom_info/static/description/templateception.jpg
  73. :alt: Templateception
  74. I.e., if you select the option "Needs videogames" for the property "What
  75. weaknesses does he/she have?" of a smart partner and press *reload custom
  76. information templates*, you will get 2 new properties to fill: "Favourite
  77. videogames genre" and "Favourite videogame".
  78. Value
  79. -----
  80. When you assign a *template* to a partner, and then you get the *properties* it
  81. should have, you still have to set a *value* for each property.
  82. *Values* can be of different types (whole numbers, constrained selection,
  83. booleans...), depending on how the *property* was defined. However, there is
  84. always the ``value`` field, that is a text string, and converts automatically
  85. to/from the correct type.
  86. Why would I need this?
  87. ~~~~~~~~~~~~~~~~~~~~~~
  88. Imagine you have some partners that are foreign, and that for those partners
  89. you need some extra information that is not needed for others, and you do not
  90. want to fill the partners model with a lot of fields that will be empty most of
  91. the time.
  92. In this case, you could define a *template* called "Foreign partners", which
  93. will be applied to ``res.partner`` objects, and defines some *properties* that
  94. these are expected to have.
  95. Then you could assign that *template* to a partner, and automatically you will
  96. get a subtable of all the properties it should have, with tools to fill their
  97. *values* correctly.
  98. Does this work with any model?
  99. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  100. Yes and no.
  101. Yes, because this is a base module that provides the tools to make this work
  102. with any model.
  103. No, because, although the tools are provided, they are only applied to the
  104. ``res.partner`` model. This is by design, because different models can have
  105. different needs, and we don't want to depend on every possible model.
  106. So, if you want to apply this to other models, you will have to develop a
  107. little additional addon that depends on this one. If you are a developer, refer
  108. to the *Development* section below.
  109. Installation
  110. ============
  111. This module serves as a base for other modules that implement this behavior in
  112. concrete models.
  113. This module is a technical dependency and is to be installed in parallel to
  114. other modules.
  115. Configuration
  116. =============
  117. To enable the main *Custom Info* menu:
  118. #. Enable *Settings > General Settings > Manage custom information*.
  119. To enable partner's custom info tab:
  120. #. Enable *Settings > General Settings > Edit custom information in partners*.
  121. Usage
  122. =====
  123. This module defines *Custom Info Templates* that define what properties are
  124. expected for a given record.
  125. To define a template, you need to:
  126. * Go to *Custom Info > Templates*.
  127. * Create one.
  128. * Add some *Properties* to it.
  129. All database records with that template enabled will automatically fill those
  130. properties.
  131. To manage the properties, you need to:
  132. * Go to *Custom Info > Properties*.
  133. To manage the property categories, you need to:
  134. * Go to *Custom Info > Categories*.
  135. Some properties can have a number of options to choose, to manage them:
  136. * Go to *Custom Info > Options*.
  137. To manage their values, you need to:
  138. * Go to *Custom Info > Values*.
  139. .. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
  140. :alt: Try me on Runbot
  141. :target: https://runbot.odoo-community.org/runbot/135/9.0
  142. Development
  143. ===========
  144. To create a module that supports custom information, just depend on this module
  145. and inherit from the ``custom.info`` model.
  146. See an example in the ``product_custom_info`` addon.
  147. Known issues / Roadmap
  148. ======================
  149. * Custom properties cannot be shared among templates.
  150. * Required attributes are for now only set in the UI, not in the ORM itself.
  151. Bug Tracker
  152. ===========
  153. Bugs are tracked on `GitHub Issues
  154. <https://github.com/OCA/product-attribute/issues>`_. In case of trouble, please
  155. check there if your issue has already been reported. If you spotted it first,
  156. help us smashing it by providing a detailed and welcomed feedback.
  157. Credits
  158. =======
  159. Contributors
  160. ------------
  161. * Rafael Blasco <rafael.blasco@tecnativa.com>
  162. * Carlos Dauden <carlos.dauden@tecnativa.com>
  163. * Sergio Teruel <sergio.teruel@tecnativa.com>
  164. * Jairo Llopis <jairo.llopis@tecnativa.com>
  165. * Pedro M. Baeza <pedro.baeza@tecnativa.com>
  166. Maintainer
  167. ----------
  168. .. image:: https://odoo-community.org/logo.png
  169. :alt: Odoo Community Association
  170. :target: https://odoo-community.org
  171. This module is maintained by the OCA.
  172. OCA, or the Odoo Community Association, is a nonprofit organization whose
  173. mission is to support the collaborative development of Odoo features and
  174. promote its widespread use.
  175. To contribute to this module, please visit https://odoo-community.org.