Configuration

Configuration of your forms is done in XML files. These files configure

  1. Which fields are available. Further you can configure various aspects of the fields.
  2. The layout of the form.

Important

When rendering SQLAlchemy mapped instances the configuration is optional. For basic form rendering you will not need any configuration at all. In this case the rendering will fall back in the default mode provided my the underlying form library. See Examples for more information.

The configuration is divided into three parts:

<configuration>
  <source>
    ...
  </source>
  <form>
    ...
  </form>
  <snippets>
    ...
  </snippets>
</configuration>

We will now discuss the different parts of the form.

Source and Entities

The source directive defines which entities are available in your forms. A entity is a field definition. You can define various attributes for each entity. The entities are later referenced in the form layouting and the entities attributes are used for rendering and validating the form data.

So the entities are the source fields and the base for which is called Schema in frameworks like colander, formencode etc. However the schema is actually defined within the form configuration.

Entity

Here is an example of an entity definition:

<entity id="f1" name="age" label="Age" type="integer" css="field">
    <renderer type="text"/>
    <help>This is a help text</help>
    <rule expr="$age >= 21" msg="Age must be greater than 21"/>
</entity>

For a complete list of supported attributes please refer to the FieldConfig documentation. As you can the entity definition embeds three further elements which are all optional:

Renderer

The renderer directive is used to configure an alternative renderer for the field. If no renderer is defined. Than the default renderer depending on the entity data type will be chosen.

Help

A entity can have a help directive. The content of the help directive can be a normal string and will be placed below the rendered field element.

Rule

The rule directive is used to define (additional) checks on the submitted values. Additional means that there are already some basic checks based on the datatype of the entity. So you will not need to define an additional check for an integer field to check if the submitted value is actually a integer. This check is automatically added. See Rules for more informations.

Form

The form configuration is used to define a form. The form definition will

  1. Define the layout of the form, and
  2. Configure which Entities will be included in the form.

A typical form configuration might look like this:

<form id="myform" autocomplete="off" enctype="multipart/form-data">
    <snippet ref="s1"/>
    <snippet ref="s2"/>
</form>

The form directive can have some attributes which are all optional beside the id attribute. See Form API for a full description of available attributes.

Within the form directive the layout of the form will be defined. In this case we reference two Snippet directives which will hold the layout. This way we can define some common used layout only once and refer to them in different forms.

We will describe the layouting possibilities in detail in the Snippets chapter.

Snippets

Snippets are containers for you layout. As you see in the Form chapter the can be referenced in multiple forms. Further a snippet include and refer to another snippets. This way you can build quite complex layouts without repeating yourself.

This is what a typical snippet might look like:

<snippet id="s1">
    <page label="Page 1">
        <row>
            <col><field ref="f1"></col>
            <col><field ref="f2"></col>
        </row>
    </page>
    <page label="Page 2">
        <row>
            <col><field ref="f3"></col>
        </row>
        <snippet ref="s2"/>
    </page>
</snippet>

Page

Use pages if you want to divide your form into multiple pages. Pages are rendered as tabs in the form.

Row

A form or pages can be divided in rows. Each row can have 1,2,3,4,6 or 12 cols elements.

Col

A row can be divided into columns. Each column can have either a field or another row.

Field

The field is the field which will be rendered. It refers to an entity.

Api

class formbar.config.Config(tree)[source]

Class for accessing the form configuration file. It provides methods to get certain elements from the configuration.

get_element(name, id)[source]

Returns an Element from the configuration. If the element can not be found it returns None. If there are more than one element of this name and the id, than raise an KeyException.

If the intitail found element refers to another element by the ‘ref’ attribute the function is recalled as long as it can find the element. :name: Name of the element (e.g entity) :id: ID of the element :returns: Element or None.

get_elements(name)[source]

Returns a list of all elements found in the tree with the given name. If no elements can be found. Return an empty list.

Name :name of the elements to be found
Returns:list of elements
get_form(id)[source]

Returns a FormConfig instance with the configuration for a form with id in the configuration file. If the form can not be found a KeyError is raised.

Id :ID of the form in the configuration file
Returns:FormConfig instance
class formbar.config.Field(entity)[source]

Configuration of a Field

autocomplete = None

Flag to enable or disable the automcomplete feature for this field. Defaults to enabled autocompletion

css = None

A string which will be added to the class tag of the form

id = None

Id of the field. Usally only used to refer to the field. Example labels.

label = None

Label of the field. If no label is provied the a capitalized form of the name is used

name = None

Name of the field. values will be submitted using this name

number = None

A ordering number for the field. In some form it is helpfull to be able to refer to a specific field by its number. The number will be rendered next to the label of the field.

readonly = None

Flag to set the field as a readonly field. If set the field will be rendered as a simple textfield which does not allow to change or enter any data. Defaults to False

required = None

Flag to mark the field as a required field. If this tag is set an additional rule will be added to the field and an astrix is rendered at the label of the field. Note that this option might not be needed to be set if the form is used to render a SQLAlchemy mapped item as this. In this case the required flag is already set by the underlying FormAlchemy library by checking if the database field is ‘NOT NULL’. Defaults to False

type = None

The datatype for this field. The data type is important for converting the submitted data into a python value. Note that this option is ignored if the form is used to render an SQLAlchemy mapped item.

class formbar.config.Form(tree, parent)[source]

Class for accessing the configuration of a specific form. The form configuration only provides a subset of available attributes for forms.

action = None

action. URL where to send the data. Defaults to an empty string which means send data to the current url again.

autocomplete = None

autocomplete. Configure the form to autocomplete (prefill) the fields in the form. Defaults to ‘on’

css = None

css. CSS class(es) to be added to the form

enctype = None

enctype. Encoding type of the subbmitted values. Use ‘multipart/form-data’ if you want to upload files. Defaults to an empty string.

get_field(name)[source]

Returns the field with the name from the form. If the field can not be found a KeyError is raised.

Name :name of the field to get
Returns:Field
get_fields(root=None)[source]

Returns a dictionary of included fields in the form. Fields fetched by searching all field elements in the form or snippets and “subsnippets” in the forms.

Returns:A dictionary with the configured fields in the form. The name

of the field is the key of the dictionary.

id = None

id. ID of the form

method = None

method. HTTP method used for sending the data. Defaults to ‘POST’ Valid values are GET and POST.

readonly = None

Flag to set the form as a readonly form. If set all fields in the form. will be rendered as a simple textfield which does not allow to change or enter any data. Defaults to False

formbar.config.load(path)[source]

Return the parsed XML form the given file. The function will load the file located in path and than returns the parsed content.

formbar.config.parse(xml)[source]

Returns the parsed XML. This is a helper function to be used in connection with loading the configuration files. :xml: XML string to be parsed :returns: DOM of the parsed XML

Table Of Contents

Previous topic

Getting Started

Next topic

Rules

This Page