1 """The automatic entity form.

     1 # organization: Logilab

     2 

     2 # copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

     3 :organization: Logilab

     3 # contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

     4 :copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

     4 # license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

     5 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

     5 """

     6 :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

     6 The automatic entity form

     7 -------------------------

     8 

     9 .. autodocstring:: cubicweb.web.views.autoform::AutomaticEntityForm

    10 

    11 Configuration through uicfg

    12 ```````````````````````````

    13 

    14 It is possible to manage which and how an entity's attributes and relations

    15 will be edited in the various context where the automatic entity form is used

    16 by using proper uicfg tags.

    17 

    18 The details of the uicfg syntax can be found in the :ref:`uicfg` chapter.

    19 

    20 Possible relation tags that apply to entity forms are detailled below.

    21 They are all in the :mod:`cubicweb.web.uicfg` module.

    22 

    23 Attributes/relations display location

    24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    25 

    26 ``autoform_section`` specifies where to display a relation in form for a given

    27 form type.  :meth:`tag_attribute`, :meth:`tag_subject_of` and

    28 :meth:`tag_object_of` methods for this relation tag expect two arguments

    29 additionally to the relation key: a `formtype` and a `section`.

    30 

    31 `formtype` may be one of:

    32 

    33 * 'main', the main entity form (e.g. the one you get when creating or editing an

    34   entity)

    35 

    36 * 'inlined', the form for an entity inlined into another form

    37 

    38 * 'muledit', the table form when editing multiple entities of the same type

    39 

    40 

    41 section may be one of:

    42 

    43 * 'hidden', don't display (not even in an hidden input, right?)

    44 

    45 * 'attributes', display in the attributes section

    46 

    47 * 'relations', display in the relations section, using the generic relation

    48   selector combobox (available in main form only, and not usable for attributes)

    49 

    50 * 'inlined', display target entity of the relation into an inlined form

    51   (available in main form only, and not for attributes)

    52 

    53 By default, mandatory relations are displayed in the 'attributes' section,

    54 others in 'relations' section.

    55 

    56 

    57 Change default fields

    58 ^^^^^^^^^^^^^^^^^^^^^

    59 

    60 Use ``autoform_field`` to replace the default field class to use for a relation

    61 or attribute. You can put either a field class or instance as value (put a class

    62 whenether it's possible).

    63 

    64 .. Warning::

    65 

    66    `autoform_field_kwargs` should usually be used instead of

    67    `autoform_field`. If you put a field instance into `autoform_field`,

    68    `autoform_field_kwargs` values for this relation will be ignored.

    69 

    70 

    71 Customize field options

    72 ^^^^^^^^^^^^^^^^^^^^^^^

    73 

    74 In order to customize field options (see :class:`~cubicweb.web.formfields.Field`

    75 for a detailed list of options), use `autoform_field_kwargs`. This rtag takes

    76 a dictionary as arguments, that will be given to the field's contructor.

    77 

    78 You can then put in that dictionary any arguments supported by the field

    79 class. For instance:

    80 

    81 .. sourcecode:: python

    82 

    83    # Change the content of the combobox. Here `ticket_done_in_choices` is a

    84    # function which returns a list of elements to populate the combobox

    85    autoform_field_kwargs.tag_subject_of(('Ticket', 'done_in', '*'),

    86                                         {'sort': False,

    87                                          'choices': ticket_done_in_choices})

    88 

    89    # Force usage of a TextInput widget for the expression attribute of

    90    # RQLExpression entities

    91    autoform_field_kwargs.tag_attribute(('RQLExpression', 'expression'),

    92                                        {'widget': fw.TextInput})

    93 

    94 

    95 

    96 Overriding permissions

    97 ^^^^^^^^^^^^^^^^^^^^^^

    98 

    99 The `autoform_permissions_overrides` rtag provides a way to by-pass security

   100 checking for dark-corner case where it can't be verified properly.

   101 

   102 

   103 .. More about inlined forms

   104 .. Controlling the generic relation fields

   515     """base automatic form to edit any entity.

   613     """AutomaticEntityForm is an automagic form to edit any entity. It is

   516 

   614     designed to be fully generated from schema but highly configurable through

   517     Designed to be fully generated from schema but highly configurable through:

   615     :ref:`uicfg`.

   518 

   616 

   519     * uicfg (autoform_* relation tags)

   617     Of course, as for other forms, you can also customise it by specifying

   520     * various standard form parameters

   618     various standard form parameters on selection, overriding, or

   521     * overriding

   619     adding/removing fields in a selected instances.

   522 

   523     You can also easily customise it by adding/removing fields in

   524     AutomaticEntityForm instances or by inheriting from it.