Location

appy/model/fields/boolean.py

Description

The boolean field allows to represent and store a boolean value.

Consequently, legal values that can be stored are the Python boolean True and False values.

Note that no value at all may be stored: dict o.values, storing all field values on some object o, may not have any entry at the key named after the field in question.

The Boolean field offers various widgets to visualize or edit a boolean value. Consult the constructor below for more details.

Render mode	Description
checkbox	(the default) Renders the field as a checkbox on the edit layout and as a translated term on any non-technical, view-like layout (ie, Yes, No, Oui, Non).
radios	Renders the field, on the edit layout, as 2 radio buttons, with 2 specific translated texts chosen by the developer: one representing the True value, one representing the False value. The stored value is still a boolean value, but it allows to show to the end user a precise text that may have more sense than Yes or No.
switch	Renders the field as a checkbox on the edit layout, but as a switch on any view-like layout, provided the user has write permission on the field. For a user having no such permission, a translated term (Yes, No) appears instead of a switch.

Constructor

    def __init__(self, validator=None, multiplicity=(0,1), default=None,
      defaultOnEdit=None, show=True, renderable=None, page='main', group=None,
      layouts=None, move=0, indexed=False, mustIndex=True, indexValue=None,
      searchable=False, filterField=None, readPermission='read',
      writePermission='write', width=None, height=None, maxChars=None,
      colspan=1, master=None, masterValue=None, focus=False, historized=False,
      mapping=None, generateLabel=None, label=None, sdefault=False, scolspan=1,
      swidth=None, sheight=None, persist=True, render='checkbox',
      falseFirst=True, inlineEdit=False, view=None, cell=None, buttons=None,
      edit=None, custom=None, xml=None, translations=None,
      falseMeansEmpty=False, disabled=False, confirm=False):

        # The following render modes are available.
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # "checkbox" | (the default) The boolean field is render as a checkbox
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # "radios"   | The field is rendered via 2 radio buttons, with custom
        #            | labels corresponding to the 2 truth values.
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # "switch"   | The field is rendered as a checkbox on the edit layout,
        #            | but as a clickable, button-like "on/off" switch on the
        #            | view/cell layout (for those having write permission).
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        self.render = render
        self.asRadios = render == 'radios'

        # When render is "radios", in what order should the buttons appear ?
        self.falseFirst = falseFirst

        # When render is "switch", the field may be rendered on button layouts
        if renderable is None and render == 'switch':
            renderable = Layouts.onButtons

        # When render is "switch", and self.confirm is True, when clicking on
        # the switch, a confirmation popup will appear first. In that case, 2
        # i18n labels will be generated: one as confirmation text before
        # switching to False, another as confirmation text for switching to
        # True. Setting self.confirm to True for a Boolean field whose render
        # mode is not "switch" has no effect.
        self.confirm = confirm

        # Call the base constructor
        super().__init__(validator, multiplicity, default, defaultOnEdit, show,
          renderable, page, group, layouts, move, indexed, mustIndex,
          indexValue, None, searchable, filterField, readPermission,
          writePermission, width, height, None, colspan, master, masterValue,
          focus, historized, mapping, generateLabel, label, sdefault, scolspan,
          swidth, sheight, persist, inlineEdit, view, cell, buttons, edit,
          custom, xml, translations)
        self.pythonType = bool

        # Must value False be interpreted as an empty value or not ?
        self.nullValues = Boolean.nullValuesVariants[falseMeansEmpty]

        # Must the edit widget, for self, be rendered as a disabled widget ?
        # It it only applicable:
        # - when render mode is "radios", on the "edit" layout,
        # - when render mode is "switch", when the switch is actually rendered.
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # When render | disabled must be ...
        # mode is ... |
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # "radios"    | a boolean value or a method computing it ;
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        # "switch"    | a method returning False or None if the widget must be
        #             | enabled, or returning a translated text if the widget
        #             | must be enabled. This text will appear as a tooltip on
        #             | on the switch.
        #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        self.disabled = disabled

Examples

A boolean field rendered as a switch

Here is an example of a Boolean field having the switch render mode.

    def showMustClose(self):
        '''Show the "must close" boolean if the meeting is decided'''
        if self.state == 'decided':
            return Show.BE
 
    mustClose = Boolean(render='switch', show=showMustClose, confirm=True,
                        layouts=Boolean.Layouts.gdl, group=meGroupD,
                        buttons=Px(utils.switchOnButtons))

meGroupD refers to a Group object having style grid: on the edit layout, the field is rendered like this (provided the showMustClose condition allows it of course).

On the buttons layout, the field is rendered like in the following capture (field value is True and the user is allowed to modify it).

Because the confirm attribute is set to True, when turning the switch on or off, a confirmation popup is shown.

Restrictions

Attribute multiplicity can only be (0,1) or (1,1). That being said, specifying a multiplicity or (1,1) has sense only when the render mode is radios.
When rendered as a switch, updating the switch is done via an Ajax request: the switch itself is the only part of the page being refreshed. If other visible elements on the shown page, like fields or workflow actions, depend on the switched value, they will not be refreshed. For that purpose, adding a new attribute to the Boolean field, that could be named ajaxRefreshSwitch, being True or False, should probably be added in the future.

🢪🢩