plone.formwidget.masterselect 3.0.0

A z3c.form widget that controls the vocabulary or display of other fields on an edit page

MasterSelectWidget

This is a z3cform widget based on the orginal Archetypes widget which controls the vocabulary or display of other fields on an edit page. It needs to be given information about which fields to control and how to control them.

Feel free to help edit this document to help explain things better!

Example

For more complex examples see demo.py in pacakge directory.:

from zope import schema
from plone.supermodel import model
from plone.formwidget.masterselect import _
from plone.formwidget.masterselect import MasterSelectBoolField
from plone.formwidget.masterselect import MasterSelectField


class IMasterSelectDemo(model.Schema):
    """ MasterSelect Demo to demonstrate all options available to
        use and to allow the test modules a content type to work
        with.
    """

    masterField = MasterSelectField(
        title=_(u"MasterField"),
        description=_(u"This field controls the vocabulary of slaveField1,"
                      "the available values in slaveField1 will be equal "
                      "to the numbers between the selected number and 10. "
        values=(1, 2, 3, 4, 5, 6),
        slave_fields=(
            # Controls the vocab of slaveField1
            {'name': 'slaveField1',
             'action': 'vocabulary',
             'vocab_method': getSlaveVocab,
             'control_param': 'master',
            },
            # Controls the visibility of slaveField1 also
            {'name': 'slaveField1',
             'action': 'hide',
             'hide_values': ('6',),
             'siblings': True,
            },
        ),
        required=True,
    )

    slaveField1 = schema.Set(
        title=_(u"SlaveField1"),
        description=_(u"This field's vocabulary is controlled by the value "
                      "selected in masterField. The values available here "
                      "will be the numbers between the number selected in "
                      "masterField and 10. The field will be hidden when 6 "
                      "is selected in the masterField."),
        value_type=schema.Choice(values=(1, 2, 3, 4, 5, 6)),
        required=False,
    )

Parameters

All the magic happens in the slave_fields parameter which should be a sequence of mappings. Each mapping is a description of a field controlled by this master field:

name

The name of the field to control on when the selection changes. The controlled field/widget may be of any type unless the ‘vocabulary’ or ‘value’ action is used. When the action is ‘vocabulary’, the field must use either a MultiSelectionWidget, a SelectionWidget, or a MasterSelectWidget any of which must have the ‘format’ parameter set to ‘select’ (this is the default only for MasterSelectWidget). For ‘value’, the widget must be simple enough to change the current value using element.value or elem.selectedIndex (StringWidget, SelectionWidget, AutoCompleteWidget, maybe others).

masterID

This is optional and will automatically be calculated if omited. It can be used to specify the exact master field is that is rendered in the html document. Normally you will only need to set this for checkbox masters since their id has a -0 added like this: #form-widgets-checkboxfield-0. Note that this is a jQuery ID selector.

masterSelector

This is optional and will default to master ID if not defined. It has the same usage as masterID but allows to specify any JQuery selector (not just an ID).

You will use this with radio button masters, to select all inputs with something like:

‘masterSelector’: ‘input[name=”form.widgets.my_master_field”]’,

slaveID

This is optional and will automatically be calculated if omited. It can be used to specify the exact slave field name to control in the html form. Note that this is a jQuery ID selector, so use something like this: #form-widgets-field

action

The type of action to perform on the slave field. This can be:

vocabulary

which alters the vocabulary of the slave field using an XMLHttpRequest call. To use the vocabulary action, the slave field must meet the widget requirements stated above.

enable or disable

toggle which marks the target widget as enabled or disabled; To use the enable / disable actions, the field must use a HTML widget that can be enabled/disabled.

show or hide

toggle which marks the target widget as show or hide.

value

which alters the value of another simple widget (StringWidget) on selection change using an XMLHttpRequest call.

attr

which alters the value of a DOM element, specified by slaveID

jquery

NOT YET IMPLEMENTED a complete jquery statement that will be sent back to the DOM to be executed.

vocab_method

The name of a method to call to retrieve the dynamic vocabulary for the slave field, or the value for the slave field when ‘value’ is used. For ‘vocabulary’, this must return a DisplayList. For ‘value, it must return a string or msg_id. The method must accept a parameter which will be used to pass the new value selected in the master widget. The name of this parameter defaults to ‘master_value’, but any name may be used as long as it is specified using the control_param element. Used only with ‘action’:’vocabulary’ or ‘action’:’value’.

control_param

As described above, this is the name of the paramter used when calling the vocab_method. Used only with ‘action’:’vocabulary’, ‘action’:’value’, ‘action’:’attr’ and ‘action’:’jquery’.

hide_values

A sequence of values which when selected in the master widget cause the slave field/widget to be hidden, shown or disabled. The method used is determined by the ‘action’ element. Used only with ‘action’:’hide’, ‘action’:’enable’, ‘action’:’disable’ or ‘action’:’show’. The value ‘()’ (dont use quotes) will trigger on anything.

siblings

Boolean value to indictate the siblings of the slave field should be selected as well as the slave field itself. This field can only be used with ‘action’:’hide’ or ‘action’:’show’ and is useful for hidng the label as well the slave field.

empty_length

The position in the slave slave field to start deleting entries from the selection box when the selection box gets refreshed with new data. The selection box options are deleted before the Ajax call so it can not be used until the call is complete. This can be useful to prevent a small select box from appearing is the first option is ‘————-’. This field is optional and can only be used with ‘action’:’vocabulary’. This value is also crecked before initating an ajax request. The ajax request will not be executed if the master select length is equal to or less than this number to help prevent slave widgets executing out of order. Default value is 0.

prevent_ajax_values

A sequence of values which when selected in the master widget prevent the widget from iniating an ajax request. Use (‘’) as the value to prevent an ajax call if the select option value is ‘’. The default is ().

initial_trigger

Boolean indicated if the master widget should initally be triggered on load. Default is true for everything except vocabulary in which case it is false to prevent an initial ajax call which usually will not be needed.

A single MasterSelectWidget may control any number of slave fields, new fields are controlled by adding new mappings to the slave_fields list/tuple. A field which is the target of a MasterSelectWidget action may itself use a MasterSelectWidget to control other fields.

The MasterSelectDemo type includes a number of master and slave widgets in different configurations. It is disabled by default, but you may import it through portal_setup tool and test it by checking the “implicitly addable” checkbox for it in the MasterSelectDemo entry in the portal_types tool.

Enjoy!

Special case with ContactChoice

Since collective.contact.widget 1.8, you can use the ContactChoice field as a master field, but it requires a special configuration for masterID and masterType properties. Here is an example:

organization = ContactChoice(
    title=_(u"Organization"),
    required=True,
    source=ContactSourceBinder(obj_types=('organization',)),
    slave_fields=(
        {'name': 'department',
         'masterID': 'form-widgets-organization-input-fields',
         'masterType': 'ContactChoice',
         'slaveID': '#form-widgets-department',
         'action': 'vocabulary',
         'vocab_method': get_organization_directions_vocabulary,
         'control_param': 'selected_organism',
         'initial_trigger': True
         },
    )
)

Author

• Jason Mehring: [e-mail]

Orginal Author of Archetypes Widget

• Alec Mitchell: [e-mail]

Contributors

• Dorneles Tremea: [e-mail]

• Cédric Messiant, Ecreall: [e-mail]

• Vincent Fretin, Ecreall: [e-mail]

• Daniel Widerin, [e-mail]

• Wesley Barroso Lopes, [e-mail]

Changelog

3.0.0 (2024-06-05)

• Fix JSON call URL in non-rooted virtual host environments. Fixes #37 [erral]

• Drop support to Python 3.7. [wesleybl]

2.0.1 (2021-09-16)

• Hides default tab in edit form in Firefox when we click on another tab. Fix #32 [wesleybl]

• Fix interfaces implemented by fields. [wesleybl]

• Use compile False in bundle. [wesleybl]

• Fix resource css not found. Fix #23 [wesleybl]

• Remove old upgrade step. [wesleybl]

2.0.0 (2021-05-27)

• Add support for Python 3 (Plone 5.2.2). Drop support for Python 2.7 & 3.6. [wkbkhard, laulaz]

• Fix loading the compiled js resource [alessandro.ceglie]

• Fix error during translation [pbauer]

• Fix buildout / Travis [tisto, wkbkhard]

1.7 (2019-11-13)

• Removed deprecated simplejson dependency [keul]

• Removed plone.app.jquerytools from generic setup dependencies. [keul]

• Fixed JavaScript: old value in slave field was not re-selected on page reload [keul]

1.6 (2016-10-11)

• Add optional support for ContactChoice from collective.contact.widget >= 1.8 as master field. [vincentfretin]

• Trigger liszt:updated event in updateSelect to force update of select chosen slave field from collective.z3cform.chosen. [vincentfretin]

• Fixed visual issue: in an overlay, i toggle was done one time for each checkbox or radio option. [thomasdesvenain]

• Fix package metadata and trove classifiers. [hvelarde]

1.5.2 (2016-08-08)

• Use zope2.View instead of cmf.AddPortalContent for masterselect-jsonvalue view. In an edit form, the user doesn’t necessary have the Add portal content permission. [vincentfretin]

1.5.1 (2016-01-08)

• Fix side-effect when updating field.vocabulary. Do now a copy of the field before changing the vocabulary. [vincentfretin]

1.5 (2015-11-24)

• Translate the “vocabulary” slave field terms (like “No value”) when entire vocabulary is replaced. [sgeulette]

1.4.1 (2014-10-30)

• jQuery 1.9 compatible. [vincentfretin]

1.4 (2014-10-09)

• masterselect.js is now cacheable. [vincentfretin]

• Move to plone.app.testing. Migrate selenium tests from windmill to robotframework. [saily]

• Add travis and coveralls integration. [saily]

• Documentation updates. Fix rst error in CHANGES.rst. Add an example to README.rst. [saily]

• Add egg-contained buildout. [saily]

1.3 (2014-06-16)

• Do not use fast transition on initial trigger. [thomasdesvenain]

• Master select features work when form is loaded in an overlay. [thomasdesvenain]

• Fix bug when masterselect is in a fieldset that is not visible. [cedricmessiant]

• Add master select radio widget and ability to specify a master Selector instead of masterID [ebrehault]

1.2 (2013-11-04)

• Added a (‘fast’) jQuery transition on show/hide function. [thomasdesvenain]

1.1 (2013-08-26)

• Made compatible with z3c.form 3.0 and jQuery 1.6+. Note: this version drops compatibility with jQuery 1.4. Please use plone.formwidget.masterselect 1.0 for plone versions < 4.3

1.0 (2013-06-10)

• Replaced jq by jQuery in generated scripts. [vincentfretin]

• Removed plone.directives.form dependency Removed plone.app.jquerytools dependency Fixed demo profile Made some cleanup [cedricmessiant]

• Initial checkin, ready for testing. [JMehring]