Module reahl.web.bootstrap.forms

Added in version 3.2.

Bootstrap-styled versions of Forms, Inputs and related Layouts.

Forms and their layout

Form

class reahl.web.bootstrap.forms.Form(view, unique_name, rendered_form=None)

Bases: Form

A Form is a container for Inputs. Any Input has to belong to a Form. When a user clicks on a Button associated with a Form, the Event to which the Button is linked occurs at the server. The value of every Input that is associated with the Form is sent along with the Event to the server.

Parameters:

  • view – (See reahl.web.fw.Widget)

  • unique_name – A name for this form, unique in the UserInterface where it is used.

NestedForm

class reahl.web.bootstrap.forms.NestedForm(view, unique_name)

Bases: NestedForm

A NestedForm can create the appearance of one Form being visually contained in another. Forms are not allowed to be children of other Forms but this restriction does not apply to NestedForms.

Parameters:

FormLayout

class reahl.web.bootstrap.forms.FormLayout

Bases: Layout

A FormLayout is used to create Forms that have a consistent look by arranging all its Inputs, their Labels and possible validation error messages in a certain way.

This basic FormLayout positions Labels above added Inputs and allow for an optional helpful text message with each input. Validation error messages are displayed underneath invalid Inputs.

Different kinds of FormLayouts allow different kinds of arrangements.

A FormLayout need not be applied directly to a Form itself. It can also be applied to, say, a Div (or FieldSet) which is a child of a Form. This makes the arrangement quite flexible, since you could have different parts of a Form that are laid out using different FormLayouts or even by different types of FormLayout.

add_input(html_input, hide_label=False, help_text=None)

Adds an input to the Form.

Parameters:

  • html_input – The Input to add.

  • hide_label – If True, makes the label invisible yet available to screenreaders.

  • help_text – Helpful text to display with each Input field.

add_alert_for_domain_exception(exception, form=None, unique_name='', severity='danger')

Adds a formatted error message to the Form.

Parameters:

  • exception – The Exception that should be displayed.

  • form – The Form to which this exception relates (default is this Layout’s .widget).

  • unique_name – If more than one alert is added to the same Form, unique_name distinguishes between them.

  • severity – (See Alert).

Added in version 5.0.

InlineFormLayout

class reahl.web.bootstrap.forms.InlineFormLayout

Bases: FormLayout

A FormLayout which positions all its Inputs and Labels on one line. The browser flows this like any paragraph of text. Each Label precedes its associated Input.

customise_widget()

Override this method in subclasses to allow your Layout to change its Widget upon construction. There is no need to call super(), as the superclass implementation does nothing.

add_input(html_input, hide_label=False, help_text=None, space_before=False, space_after=False)

Adds an input to the Form.

Parameters:

  • html_input – (See add_input()).

  • hide_label – (See add_input()).

  • help_text – (See add_input()).

  • space_before – If True, render with a margin before the input.

  • space_after – If True, render with a margin after the input.

Changed in version 6.1: Added space_before and space_after kwargs.

GridFormLayout

class reahl.web.bootstrap.forms.GridFormLayout(label_column_size, input_column_size)

Bases: FormLayout

A GridFormLayout arranges its Labels and Inputs in a grid with two columns. Labels go into the left column and Inputs into the right column. The programmer specifies how wide each column should be.

Parameters:

  • label_column_size – A ResponsiveSize for the width of the Label column.

  • input_column_size – A ResponsiveSize for the width of the Input column.

FieldSet

class reahl.web.bootstrap.forms.FieldSet(view, legend_text=None, css_id=None)

Bases: HTMLElement

A visual grouping of HTMLElements inside a Form.

Styling

Rendered as an HTML <fieldset> element.

Parameters:

Changed in version 3.2: Deprecated label_text and instead added legend_text: FieldSets should have Legends, not Labels.

Changed in version 4.0: Removed label_text that was deprecated.

Inputs

TextArea

class reahl.web.bootstrap.forms.TextArea(form, bound_field, rows=None, columns=None, refresh_widget=None, ignore_concurrent_change=False)

Bases: TextArea

A muli-line Input for plain text.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

  • rows – The number of rows that this Input should have.

  • columns – The number of columns that this Input should have.

  • refresh_widget – (See PrimitiveInput)

  • ignore_concurrent_change – (See PrimitiveInput)

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

SelectInput

class reahl.web.bootstrap.forms.SelectInput(form, bound_field, size=None, refresh_widget=None, ignore_concurrent_change=False)

Bases: SelectInput

An Input that lets the user select an reahl.component.modelinterface.Choice from a dropdown list of valid ones.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

  • size – Number of rows in the list that should be visible at one time, if the associated field allows multiple selections.

  • refresh_widget – (See PrimitiveInput)

  • ignore_concurrent_change – (See PrimitiveInput)

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

RadioButtonSelectInput

class reahl.web.bootstrap.forms.RadioButtonSelectInput(form, bound_field, contents_layout=None, refresh_widget=None, ignore_concurrent_change=False)

Bases: RadioButtonSelectInput

An Input that lets the user select a reahl.component.modelinterface.Choice from a list of valid ones shown as radio buttons of which only one can be selected at a time.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

  • contents_layout – An optional ChoicesLayout used to lay out the many choices in this input.

  • refresh_widget – (See PrimitiveInput)

  • ignore_concurrent_change – (See PrimitiveInput)

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

TextInput

class reahl.web.bootstrap.forms.TextInput(form, bound_field, fuzzy=False, placeholder=False, refresh_widget=None, ignore_concurrent_change=False)

Bases: TextInput

A single line Input for typing plain text.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

  • fuzzy – If True, the typed input will be dealt with as “fuzzy input”. Fuzzy input is when a user is allowed to type almost free-form input for structured types of input, such as a date. The assumption is that the bound_field used should be able to parse such “fuzzy input”. If fuzzy=True, the typed value will be changed on the fly to the system’s interpretation of what the user originally typed as soon as the TextInput looses focus.

  • placeholder – (See TextInput)

  • refresh_widget – (See PrimitiveInput)

  • ignore_concurrent_change – (See PrimitiveInput)

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

Changed in version 6.1: Changed placeholder to display the default of the field under certain conditions

PasswordInput

class reahl.web.bootstrap.forms.PasswordInput(form, bound_field, refresh_widget=None, ignore_concurrent_change=False)

Bases: PasswordInput

A PasswordInput is a single line text input, but it does not show what the user is typing.

Parameters:

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

PrimitiveCheckboxInput

reahl.web.bootstrap.forms.PrimitiveCheckboxInput

alias of CheckboxInput

CheckboxInput

class reahl.web.bootstrap.forms.CheckboxInput(form, bound_field, contents_layout=None, refresh_widget=None, ignore_concurrent_change=False)

Bases: CheckboxSelectInput

An Input that presents either a single checkbox or a list of them, depending on what Field it is used with.

If used with a MultiChoiceField, the checkboxes represent which Choices are chosen; a single checkbox represents a BooleanField.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

  • contents_layout – An optional ChoicesLayout used to lay out the checkboxes in this input.

  • refresh_widget – (See PrimitiveInput)

  • ignore_concurrent_change – (See PrimitiveInput)

Changed in version 5.0: Added refresh_widget

Changed in version 5.0: Added ignore_concurrent_change

create_html_widget()

Override this in subclasses to create the HTMLElement that represents this Input in HTML to the user.

Added in version 3.2.

property includes_label

If True, the Label of this Input forms part of the input itself.

Button

reahl.web.bootstrap.forms.Button

alias of ButtonInput

ButtonInput

class reahl.web.bootstrap.forms.ButtonInput(form, event, ignore_concurrent_change=False, style='secondary', outline=False, size=None, active=False, wide=False, text_wrap=True)

Bases: ButtonInput

A button.

Parameters:

Changed in version 5.0: Added ignore_concurrent_change

Changed in version 5.0: Changed to always get a ButtonLayout upon creation.

ButtonLayout

class reahl.web.bootstrap.forms.ButtonLayout(style='secondary', outline=False, size=None, active=False, wide=False, text_wrap=True)

Bases: Layout

A ButtonLayout can be used to make something (like an A) look like a Button. It has a few options controlling specifics of that look, and can be used to change the default look of a Button as well.

Parameters:

  • style – The general style of the button (one of: ‘primary’, ‘secondary’, ‘success’, ‘info’, ‘warning’, ‘danger’, ‘link’, ‘light’, ‘dark’)

  • outline – If True, show an outline around the button.

  • size – The size of the button (one of: ‘xs’, ‘sm’, ‘lg’)

  • active – If True, the button is visually altered to indicate it is active (buttons can be said to be active in the same sense that a menu item can be the currently active menu item).

  • wide – If True, the button stretches to the entire width of its parent.

  • text_wrap – If False, text on the Button does not wrap.

Changed in version 5.0: Change style to allow ‘secondary’ (Bootstrap 4) instead of ‘default’ (Bootstrap 3). Default style is not ‘secondary’.

customise_widget()

Override this method in subclasses to allow your Layout to change its Widget upon construction. There is no need to call super(), as the superclass implementation does nothing.

Label

class reahl.web.bootstrap.forms.Label(view, text=None, for_input=None, css_id=None)

Bases: HTMLElement

A label for an Input.

If for_input is given, the Label will only be visible if for_input is visible.

Styling

Rendered as an HTML <label> element.

Parameters:

Changed in version 3.2: Added the for_input keyword argument.

property visible

Answers whether this Widget should be rendered to the current user at all.

property attributes

Override this method if you want to change the attributes of this HTMLElement on the fly, based on the state of the HTMLElement at the point in time when it is rendered.

StaticData

class reahl.web.bootstrap.forms.StaticData(form, bound_field)

Bases: Input

A fake input which just displays the value of the Field to which the StaticData is attached, but does not include a way to change the value.

This is useful in cases where you want to display some data that is exposed via a Field in a Form amongst normal Inputs.

Parameters:

  • form – (See Input)

  • bound_field – (See Input)

CueInput

class reahl.web.bootstrap.forms.CueInput(html_input, cue_widget)

Bases: WrappedInput

A Widget that wraps around a given Input to augment it with a “cue” - a hint that appears only when the Input has focus. The intention of the cue is to give the user a hint as to what to input into the Input.

Parameters:

  • html_input – The Input to be augmented.

  • cue_widget – An Widget that serves as the cue.

get_js(context=None)

Override this method if your Widget needs JavaScript to be activated on the browser side.

property includes_label

If True, the Label of this Input forms part of the input itself.

InputGroup

class reahl.web.bootstrap.forms.InputGroup(prepend, input_widget, append)

Bases: WrappedInput

A composition of an Input with something preceding and/or following it.

Parameters:

  • prepend – A Widget or text to prepend to the Input.

  • input_widget – The Input to use.

  • append – A Widget or text to append to the Input.