Changes between Version 3 and Version 4 of S3/S3SQLForm


Ignore:
Timestamp:
08/29/12 10:08:38 (9 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3SQLForm

    v3 v4  
    11= S3SQLForm =
     2[[TOC]]
    23
    3   - ''coming soon...''
     4By default, S3CRUD generates create/update forms based on introspection of the table: all fields which are set to either readable or writable will be included in the form, in the order in which they are defined in the table.
     5
     6This default form can be replaced by setting the "crud_form" hook to an instance of S3SQLCustomForm (e.g. in the controller), which allows you to explicitly select the fields and the order in which they appear in the form, and even to include fields from components.
     7
     8S3CRUD will then use this form definition instead of the default form.
     9
     10Example:
     11{{{
     12def inline():
     13
     14    from s3.s3forms import S3SQLCustomForm, S3SQLInlineComponent
     15
     16    crud_form = S3SQLCustomForm(
     17                    "first_name",
     18                    "last_name",
     19                    S3SQLInlineComponent(
     20                        "contact",
     21                        name="test",
     22                        label=T("Contact Information"),
     23                        fields=["contact_method", "value"]
     24                    ),
     25                    "age_group",
     26                    "date_of_birth",
     27                    S3SQLInlineComponent(
     28                        "note",
     29                        label=T("Notes"),
     30                        fields=["timestmp", "note_text"]
     31                    ),
     32                    "identification.status"
     33                    )
     34
     35    s3db.configure("pr_person", crud_form=crud_form)
     36
     37    return s3_rest_controller("pr", "person")
     38}}}
     39
     40== Syntax ==
     41
     42S3SQLCustomForm takes instances of subclasses of S3SQLFormElement as parameters. Currently implemented S3SQLFormElement subclasses are:
     43
     44||'''Class'''||'''Form Element'''||
     45||S3SQLField||Regular form widget for fields in either the main table or in a subtable (single-record component)||
     46||S3SQLInlineComponent||A subform for multi-record components||
     47
     48Strings in the parameter list will be interpreted as field selectors, and used to instantiate S3SQLFields for the fields they address. Note that only fields in the main table or single-record components can be specified this way - everything else will raise a SyntaxError.
     49
     50The order in which the form elements appear in the parameter list determines the order in which they appear in the form.
     51
     52Form elements or actions which the user is not permitted to access will be rendered either read-only or not at all (according to the actual permission). The same applies for elements (e.g. components) which are deactivated in the deployment.
     53
     54== Regular Fields ==
     55
     56Regular fields in the main table can be specified simply by their field name.
     57
     58{{{
     59    crud_form = S3SQLCustomForm(
     60                    "first_name",
     61                    "last_name",
     62                    "age_group",
     63                    "date_of_birth",
     64                    )
     65}}}
     66
     67Fields can be specified in arbitrary order, but must not be repeated within the list.
     68
     69== Fields in Subtables ==
     70
     71Fields in components which are set to multiple=False (single-record components = sub-tables) can also be specified as field selector strings using the "."-notation:
     72
     73{{{
     74    crud_form = S3SQLCustomForm(
     75                    "identification.status"
     76                    )
     77}}}
     78
     79Fields from single-record components can be specified anywhere in the form elements list, they do not need to stand together or at a particular place in the field order. However - the same field must not be repeated.
     80
     81The form element will use the default widget for the respective field in the subtable.
     82
     83If the user is not permitted to access this component, then the widget will not be rendered at all. If the user has only read access, it will be rendered read-only.
     84
     85== Inline Components ==
     86
     87Components with multiple=True (multi-record components) can be specified as instances of S3SQLInlineComponent:
     88
     89{{{
     90    crud_form = S3SQLCustomForm(
     91                    S3SQLInlineComponent(
     92                        "contact",
     93                        name="test",
     94                        label=T("Contact Information"),
     95                        fields=["contact_method", "value"]
     96                    ),
     97                    S3SQLInlineComponent(
     98                        "note",
     99                        label=T("Notes"),
     100                        fields=["timestmp", "note_text"]
     101                    ),
     102                    )
     103}}}
     104
     105These form elements will be rendered as embedded tables of the existing records in the component with the option to add, update and delete rows (depending on permissions for this components).
     106
     107The first argument of S3SQLInlineComponent is the resource alias name (usually the tablename without module prefix).
     108
     109Where multiple sub-forms for the same component (e.g. with different filters) shall be embedded, they must each have a distinct "name" argument. (Filtering is not implemented yet - but will come soon). Otherwise this argument is optional.
     110
     111You can also specify a label (title) for the subform using the "label" argument (optional)
     112
     113The "fields" argument specifies the fields to display in the subform, and the order in which they shall appear. This argument is required.
     114
     115== Current Status ==
     116
     117S3SQLForm has currently alpha-status, the implementation is still incomplete.
     118
     119Remaining work items for a beta-version:
     120
     121- some form widgets may not yet be supported in inline-components (e.g. Autocompletes), or show unexpected behavior.
     122- there is no specific CSS formatting for inline-components yet
     123- Authorization of inline-components is incomplete
     124- Filtering of inline-components is not implemented yet
     125- Link-table components are not properly supported in inline-components yet
    4126
    5127----