Albatross Forms Reference

Inheritance diagram of albatross.ext.form

class albatross.ext.form.Button(value, name, html_attrs=None)

Bases: albatross.ext.form.HTMLTag

An HTML submit button. All buttons in a Form should be collected in a single Buttons instance which is passed to the constructor of the Form.

  • value is written on the face of the button when displayed.
  • name is returned from the browser and can be tested in the application using ctx.req_equals(‘name’).
class albatross.ext.form.Buttons(buttons, html_attrs=None)

Bases: albatross.ext.form.HTMLTag

A collection of Button instances.

class albatross.ext.form.Checkbox(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.InputField

An HTML <input type=”checkbox”> control. self.value is always valid and the merged value is boolean.

class albatross.ext.form.Col(children, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag

HTML TD tag.

class albatross.ext.form.DataHTMLTag(attr=None, value=None, html_attrs=None)

Bases: albatross.ext.form.HTMLTag

Output HTML for a value which which can be loaded from another object.

  • attr is the name of the attribute in the model manipulated by load() and merge().
get_display_value(ctx, form)

Override this method to provide any required formatting or modification of the displayed value.


This should return the correctly typed object to update the field in the original object. Override this if you are using a non-string value.


Return the converted value in this field

class albatross.ext.form.DefaultCSSStyles

Bases: albatross.ext.form.CSSStyles

A collection of named CSS styles used in the HTML output of HTMLTag instances.

Each Form has a reference to a single instances of this class - field.styles.

Additional styles can be added to the default instance after the Form is created or an existing instance can be specified when the Form is created using the styles argument.

The default style names are:

  • buttons
  • legend
  • label
  • field
  • field-error
  • field-invalid,
  • value
  • value-static
class albatross.ext.form.Field(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.DataHTMLTag

Base class for input fields.

  • name is the display name tyically shown to the left of the input control in the generated HTML.
  • Specify merge_obj if this Field is loaded/merged from a model object other than the one used for the form (this should usually be left as None).
  • Set required to True if a value must be entered for this Field (a FieldValidationError will be raised on a call to validate() if the Field is empty).
  • If static is True the Field is always displayed in static report style preventing user input.

Creating your own Field-subclasses

Several methods may be provided by custom subclasses as needed:

  • get_display_value(self, ctx, form)

    should return the value stored in self.value to how you want it displayed in the browser. This is typically called during to_html and the value of self.value will be replaced with this after that point.

  • get_merge_value(self, s)

    Should convert the string version of the value passed in and return a value of the appropriate type.

  • validate(self, form)

    Validate the string version of the value stored in the field. The method should just return if it validates correctly; if not, raise FormValidationError with an appropriate error message.

    Field‘s that are static or are members of a static form are not validated.

  • to_html(self, ctx, form)

    Generate custom HTML for this tag. Use:

    form.write_content(ctx, ‘<your html here>’)

    to write your HTML to the output stream.


Override get_merge_value() where the value received from Albatross on a form submission should be checked or modified before being stored.


Create a unique string representation of the field to be used as an Albatross input name.


Load self.value from a named attribute in the model.


Merge value back into the model.

to_html(ctx, form)

Field subclasses must provide different output for static, enabled and disabled states and may output validation error messages.

The default implementation of write_static_html() and write_errors_html() should suffice for most cases. A typical subclass will override write_form_html() to provide the HTML ouput for the input controls required (text input, checkbox, etc.)

validate(form, s)

Subclasses should use this method to validate s after form submission. The method should raise a FieldValidationError for invalid values.

write_errors_html(ctx, form)

Write the HTML representation of the FieldValidationError for this Field. Called during HTML generation if this Field raised an exception during Form validation.

write_form_html(ctx, form)

Write the interactive form control HTML representation of the field.

write_static_html(ctx, form)

Write a static HTML representation of the field. This method is called by to_html() if self.static is True of if the whole Form is being statically rendered.

exception albatross.ext.form.FieldValidationError

Bases: albatross.ext.form.FormError

Raised by Field subclasses if validate() fails.

class albatross.ext.form.Fieldset(children, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag

Container for a collection of Field instances.

Writes a table of fields. Note that the <fieldset> HTML tags are intentionally provided by the FieldsetForm and not this class.

class albatross.ext.form.FieldsetForm(legend, children, buttons=None, styles=None, html_attrs=None)

Bases: albatross.ext.form.Form

A Form subclass which wraps the HTML output in a <FIELDSET> tag.

class albatross.ext.form.FloatField(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.InputField

A TextField which validates and merges float values.

class albatross.ext.form.Form(legend, children, buttons=None, styles=None, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag

Encapsulates an HTML form and its input fields.

  • legend is displayed as the title of the form.
  • children is a list of HTMLTag subclasses including all the Form fields and markup fields for layout.
  • buttons is an optional Buttons instance.
  • styles is an optional CSSStyles instance. If not specified a DefaultCSSStyles instance is created.

Clear all field values, set form and all fields to valid state, clear disabled and set edit mode to FORM_CREATE.


Clear errors and set all fields to valid.


Load field values from load_obj.


Merge all field values to merge_obj.

run(ctx, name, opts)

Called by alx-form tag handler to render the form. This method sets the correct internal state for rendering, resets indentation and registers input fields before calling to_html().


Disable or enable data entry on all fields on this form.


Render all fields and buttons as HTML. This is an internal method. To render the form use run().


Call validate() on each field. Sets self.valid to False and raises FormValidationError if any fields are invalid. Validation exceptions are stored in self.validation_errors and are cleared by calling clear(), clear_errors() or on the next call to validate().

Static fields or fields of a static form are not validated.

write_content(ctx, content, indent=None)

A wrapper for ctx.write_content() which provides indentation to assist in generating human readable HTML output.

Valid values for indent are:


All other values are ignored.

exception albatross.ext.form.FormError

Bases: exceptions.Exception

Base class for all exceptions raised by the albatross.ext.form module.

class albatross.ext.form.FormModel(**kwargs)

Convenience class for simple form/model manipulation.

class albatross.ext.form.FormOptions(show_errors=False, static=False, pagesize=None)

Collect the attributes we’re interested in from the alx-form tag.

exception albatross.ext.form.FormValidationError(errors)

Bases: albatross.ext.form.FormError

Raised by Form subclasses validation fails for one or more fields.

class albatross.ext.form.HTMLTag(html_attrs=None)

Base class for any class which provides HTML output. Arbitrary HTML attributes can be specified as html_attrs.

class albatross.ext.form.HTMLTreeTag(children, html_attrs=None)

Bases: albatross.ext.form.HTMLTag

An HTMLTag with children.

class albatross.ext.form.HeaderCol(children, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag

HTML TH tag.

class albatross.ext.form.InputField(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.Field

Base class for generating an HTML <input> tag. Requires that the instance has a self.type which is the type of the HTML input, ie, it will generate <input type=”(self.type)” ...>.

Subclasses are expected to maintain self.value as the correct type (eg, string (for text), int, datetime, etc) and to do validation of the input as required. Self.value can also contain invalid strings if the user has partly edited a field. Calling merge or get_value before validate has succeeded may raise an exception.

The conversion of the internal value to the display value is complicated because Albatross sets the value of an empty field to None so that needs to be handled or all empty text fields in a form are converted to “None”.

class albatross.ext.form.IntegerField(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.InputField

A InputField which validates and merges integer values.

class albatross.ext.form.IteratorTable(table_attr, header_row, pager, html_attrs=None, page_selection_display=<albatross.ext.form.PrevNextPageSelectionDisplay instance at 0xb0dcfec>)

Bases: albatross.ext.form.Field

Create an HTML table from a list of objects.

  • table_attr is the name of the instance var in the class which creates this object. This is used when directing Albatross to update the form values.

  • header_row is a Row of HeaderCol instances (usually) which are used to put a header on the table. An empty list or None will suppress any headers.

  • row_class is a subclass of IteratorTableRow. It is used to render each row in the table. It will be used to contruct each row by being instantiated with each element of content_list in turn.

    If you need pass the row class constructor some extra arguments from the table constructor, assign them to instance variables and make the row_class a bound method to a method that marshalls the arguments before calling the row constructor.

  • pager is the PagedListBase subclass which provides paginated

    data to display in the table.


Append a new item of data to the table


Jump to specified page. If page == -1, go to last page.


Remove an item of data from the table

update(item, *attrs)

Update an item of data in the table

class albatross.ext.form.IteratorTableRow(cols)

Bases: albatross.ext.form.Form

When using an IteratorTable, the class that’s used to display each row must be a subclass of IteratorTableRow so that the rendering and validation is performed correctly. This is checked for in the IteratorTable constructor.

Each row in a table is actually treated as a separate sub-Form. This allows Albatross to traverse the table hierarchy when it’s updating the field values.


generates the row’s content bracketed by <tr>/</tr>

class albatross.ext.form.Label(value, html_attrs=None)

Bases: albatross.ext.form.HTMLTag

Simple displayed string value with no label.

class albatross.ext.form.LabelFieldRow(field, label=None)

Bases: albatross.ext.form.Row

Build a two column Row instance with a name Label and a Field.

class albatross.ext.form.OptionsField(name, options, attr, merge_obj=None, value=0, html_attrs=None, static=False)

Bases: albatross.ext.form.Field

Base class to handle selection of a single value from a list of options, ie, for a select or radio list.


change the options displayed by the select field.

class albatross.ext.form.PageSelectionDisplayBase

Base class for displaying page selection

class albatross.ext.form.PagedList(items, row_class=None, pagesize=None)

Bases: albatross.ext.form.PagedListBase

Simple pager which stores all items and returns the items for a given page in a @row_class instance on demand.

class albatross.ext.form.PagedListBase(pagesize=None)

An IteratorTable item list which supports pagination. Subclasses should implement page_count() and items_on_page() to create @row_class instances of the items for a given page on demand.

class albatross.ext.form.PasswordField(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.TextField

A TextField with text input hidden by ‘*’

class albatross.ext.form.RadioField(name, options, attr, merge_obj=None, value=0, html_attrs=None, static=False)

Bases: albatross.ext.form.OptionsField

Manage a radio list.

  • options is a list of tuples of (value, display value)

When the field or the enclosing form is static, we just emit the selected option. (XXX I hope that’s the right thing to do)

class albatross.ext.form.Row(children, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag

HTML TR tag.

class albatross.ext.form.SelectField(name, options, attr, merge_obj=None, value=0, html_attrs=None, static=False)

Bases: albatross.ext.form.OptionsField

Manage a drop down list of options.

  • options is a list of tuples of (value, display value)
class albatross.ext.form.StaticField(name, value, html_attrs=None)

Bases: albatross.ext.form.Field

String Field which never accepts user input.

class albatross.ext.form.Table(header_row, children, html_attrs=None)

Bases: albatross.ext.form.HTMLTreeTag


class albatross.ext.form.TextField(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.InputField

HTML <input type=”text”> tag. Merged data is a string. If self.required is True validate() will raise a FieldValidationError if the input field is empty. No other validation or conversion is performed.


Empty input field is submitted as None - convert to empty string.

class albatross.ext.form.Textarea(name, attr, merge_obj=None, value=None, html_attrs=None, required=False, static=False)

Bases: albatross.ext.form.TextField

An HTML TEXTAREA tag. Validate and merge rules are the same as TextField.

Previous topic

Albatross Forms Guide

Next topic

Templates Reference

This Page