Changes between Version 19 and Version 20 of S3/S3ReusableField

Timestamp:

06/12/14 11:37:28 (11 years ago)

Author:

Dominic König

Comment:

--

S3/S3ReusableField

@@ -68 +68 @@
 }}}
 
+== Multiple Widgets ==
+
+It is possible to specify multiple possible widget alternatives in the S3ReusableField, and then apply them by name.
+
+Example:
+
+{{{#!python
+organisation_id = S3ReusableField("organisation_id", "reference org_organisation",
+                                  requires = IS_EMPTY_OR(IS_ONE_OF(db, "org_organisation.id",
+                                                                   org_organisation_represent)),
+                                  represent = org_organisation_represent,
+                                  label = T("Organisation"),
+                                  widgets = {"default": S3OrganisationAutocompleteWidget(default_from_profile=True),
+                                             "hierarchical": S3HierarchyWidget(lookup = "org_organisation",
+                                                                               represent = org_organisation_represent,
+                                                                               multiple = False,
+                                                                               leafonly = False,
+                                                                               ),
+                                             },
+                                  )
+}}}
+
+Without override or explicit choice, the "default" widget would be used in Field instances.
+
+To choose a widget by name:
+
+{{{
+tablename = "my_table"
+table = db.define_table(tablename,
+                        ...,
+                        # Choose the "hierarchical" widget for this instance:
+                        organisation_id(widget="hierarchical"),
+                        ...
+                        )
+}}}
+
+This is especially useful if the choice of the widget depends on a deployment setting.
+
+However, every instance can still override all possible alternatives:
+
+{{{
+tablename = "my_table"
+table = db.define_table(tablename,
+                        ...,
+                        # Specify the widget explicitly:
+                        organisation_id(widget=MyCustomWidget()),
+                        ...
+                        )
+}}}
+
+...or enforce the web2py standard widget for the field type:
+
+{{{
+tablename = "my_table"
+table = db.define_table(tablename,
+                        ...,
+                        # Enforce web2py standard widget for the field type:
+                        organisation_id(widget=None),
+                        ...
+                        )
+}}}
+
 ----
 DeveloperGuidelines