Xataface Depselect Module 0.1
Dependent Select List Widget for Xataface Forms
The Xataface depselect module adds a "dependent select" widget for use in forms. A dependent select is one whose options are dependent on the state of other widgets in the form. It listens for changes to other selects and updates its own options accordingly.
A common example is a form with select lists for country, province, and city. The options in the "province" select list will depend on which option is selected in the "country" select list. Similarly the options in the "city" widget depend on the "province" selection. The depselect widget is ideal of this scenario as it will live update the options according to the selections in the dependency fields.
- Live updating of menu options when other widgets are updated. - "Add" button to add options to a menu (opens internal dialog with new record form). - Integrated with Xataface's permissions system (options will only be loaded if user is granted view permission on target table). - Option to override permissions. - Doesn't require a valuelist. (May be more efficient for providing options on subsets of very large tables as valuelists are loaded in their entirety every request).
- Xataface 1.4 or higher
To configure a field to use the depselect widget, just set its fields.ini file widget:type directive to "depselect". You should also set the following directives:
|widget:table||The name of the table from which the options should be pulled|
|widget:filters:xyz||Filters to apply to queries to load the options. This can be any valid Xataface GET parameter in accordance with the Xataface URL conventions.|
|widget:keycol||(Optional) The name of the column to treat as the id or key column.|
|widget:labelcol||(Optional) The name of the column to pull labels from.|
|widget:ignore_permissions||(Optional) The user needs 'view' permissions for the records from which the options are populated, unless this directive is set.|
In the following example we have a city field that is dependent on the province field that is dependent on the country field:
The key to the depselect widget lies in the widget:filters directive which specifies either a static or a dynamic filter that can be used to filter the options in the depselect widget. A static filter is just any string that will be used to filter the particular field of the table specified by the widget:table directive. With a static filter (or no filter), the depselect will behave essentially the same as a standard select widget. You can make the widget dependent upon the selected value of another field in the form by using a dynamic filter. A dynamic filter specifies the name of another field in the form whose value should be used to filter the options in this depselect widget. It is signified by a "$" prefix followed by the name of the field whose value we wish to filter on.
In the previous examples, the province_id field uses a dynamic filter on the country_id field. It indicates that it will only include options from the provinces table whose country_id field matches the selection of the country_id field on this form.
In cases where you have specified a dynamic filter on the depselect, you may want to specify an alternate filter to use in the case where the field upon which the depselect depends has not been selected or is left blank. You can signify this default filter by piping it to the dynamic filter. I.e. Using the "|" notation. E.g.
In this example the province field will be filtered on the value of the country_id field if it has a value selected. Otherwise it will just show the provinces with country_id=0.
You can also use Xataface URL conventions for this default filter. E.g.
This says that the default search is an "empty" search. Which will return all of the provinces. You could also search for all provinces with nonempty country_id values:
Note: Default filters were added version 0.2