Abstract
Description of all the field classes provided with Atocha. This file is automatically generated from the docstrings of the fields. You can also try most or all of these fields at the online demo.
A single-line text field that accepts and parses a Python float.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minval --> int (Optional)
- Minimum value that is accepted.
- maxval --> int (Optional)
- Maximum value that is accepted.
- format --> str (Optional)
- Printf-like format for output display. If this is not set the default string conversion routines are used. Note that you should set an appropriate format for the relevant numerical type. Also, this does not affect the input parsing at all.
A single-line text field that accepts and parses a Python integer.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minval --> int (Optional)
- Minimum value that is accepted.
- maxval --> int (Optional)
- Maximum value that is accepted.
- format --> str (Optional)
- Printf-like format for output display. If this is not set the default string conversion routines are used. Note that you should set an appropriate format for the relevant numerical type. Also, this does not affect the input parsing at all.
A string field that accepts strings that represent dates, in some specific formats.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- encoding --> str (Optional)
- Encoding to convert the string into and to validate to. This determines which encoding is considered to be a valid parsed/data value for this field. If you leave this to None, the field produces Unicode values.
- size --> int (Optional)
- Suggested rendering size of the field.
A field that offers dates in close proximity, via a select menu.
Extra choices can be added to the menu, and in this case a string type is returned (therefore, when you accept the data, you will need to check the returned datatype for a str or a date object.)
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- allow_missing --> bool (Optional)
- If this is set, allow missing values, i.e. if the value is not sent by the browser, do not raise an error. This is useful if the widget may be hidden conditionally.
- onchange --> str (JavaScript) (Optional)
- JavaScript to run when the selector changes.
- nbdays --> int (Optional)
- The number of days to display from today.
A fancy Javascript-based date field.
This is an adaptation for this form handling library of a nice Javascript-based date input field found at http://www.jasonmoon.net/. The conditions of utilisation of that code is that a notice should be present and kept intact somewhere in the comments.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
A valid URL path.
This is mostly used to accept return addresses in handlers. This is always a hidden field.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- size --> int (Optional)
- Suggested rendering size of the field.
A valid URL path.
This is mostly used to accept return addresses in handlers. This is always a hidden field.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- size --> int (Optional)
- Suggested rendering size of the field.
Username field with a maximum length and which automatically lowercases the parsed value.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minlen --> int (Optional)
- Minimum length of the field, if it is not empty. You may be able to use the 'required' option if you would like not to allow empty values.
- maxlen --> int (Optional)
- Maximum length of the field.
- size --> int (Optional)
- Suggested rendering size of the field.
- autolower --> bool (Optional)
- Determines whether we automatically convert the given name to lowercase, or raise an error if some uppercase characters were found.
A field that can accept either a username or an email address.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- size --> int (Optional)
- Suggested rendering size of the field.
Checkbox that is required to be received, otherwise an error is given.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- disptrue --> str (Optional)
- String for display of True value.
- dispfalse --> str (Optional)
- String for display of False value.
- onchange --> str (JavaScript) (Optional)
- JavaScript to run when the field is changed. This should transparently render the more widely supported onclick callback.
A single boolean (checkbox) field.
Note: this field cannot be optionally required.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- disptrue --> str (Optional)
- String for display of True value.
- dispfalse --> str (Optional)
- String for display of False value.
- onchange --> str (JavaScript) (Optional)
- JavaScript to run when the field is changed. This should transparently render the more widely supported onclick callback.
Field for an email address. The user can also enter a full name with <> but the name is automatically thrown away. Encoding is fixed to 'ascii', data is stripped automatically.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- size --> int (Optional)
- Suggested rendering size of the field.
- accept_local --> bool (Optional)
- True if we accept local email addresses (i.e. without a @).
A single-line field for entering a password.
When rendering, optionally, we don't output the password back into HTML, to avoid disclosure over unencrypted communication channels.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minlen --> int (Optional)
- Minimum length of the field, if it is not empty. You may be able to use the 'required' option if you would like not to allow empty values.
- maxlen --> int (Optional)
- Maximum length of the field.
- encoding --> str (Optional)
- Encoding to convert the string into and to validate to. This determines which encoding is considered to be a valid parsed/data value for this field. If you leave this to None, the field produces Unicode values.
- size --> int (Optional)
- Suggested rendering size of the field.
- hidepw --> bool (Optional)
- Specifies whether the password should be state on rendering.
String input that must be on a single line.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minlen --> int (Optional)
- Minimum length of the field, if it is not empty. You may be able to use the 'required' option if you would like not to allow empty values.
- maxlen --> int (Optional)
- Maximum length of the field.
- encoding --> str (Optional)
- Encoding to convert the string into and to validate to. This determines which encoding is considered to be a valid parsed/data value for this field. If you leave this to None, the field produces Unicode values.
- size --> int (Optional)
- Suggested rendering size of the field.
- strip --> bool (Optional)
- Whether the string returned should be stripped of whitespace before rendering and during parsing.
A multi-line string.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- minlen --> int (Optional)
- Minimum length of the field, if it is not empty. You may be able to use the 'required' option if you would like not to allow empty values.
- maxlen --> int (Optional)
- Maximum length of the field.
- encoding --> str (Optional)
- Encoding to convert the string into and to validate to. This determines which encoding is considered to be a valid parsed/data value for this field. If you leave this to None, the field produces Unicode values.
- rows --> int (Optional)
- The number of rows to render the field with.
- cols --> int (Optional)
- The number of column to render the field with.
Field for an URL. We can parse some of the syntax for a valid URL. This field can also be used by the renderer to automatically add a link to the displayed value, if it is requested to render for display only. Encoding is fixed to 'ascii', data is stripped automatically.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- size --> int (Optional)
- Suggested rendering size of the field.
Zero, one or many checkbox choices. This field defines a row or column of checkboxes.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- choices --> Sequence of str or (str, unicode)
- Choice-label pairs: the ordered choices, to be rendered and checked against when parsing. This is not a mapping because order is important for rendering. If the elements of the list are pairs, the label is used for the user-visible strings to be used when rendering the widget. Note that we also accept integers for choices instead of ascii strings, but these will be automatically converted to strings.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- nocheck --> bool (Optional)
- Set this to True if you want to prevent the parser from cross-checking the values against the choices set in the instance of this field. When parsing, do not perform checks specific to the choices set on against the received values. This is useful if the set of choices for this field is generated dynamically and you will do your validation by hand. Another thing that can be done is to not use this but to call setchoices() before running the parser on the arguments, if in the handler you know which choices are possibly valid and would like to use the parsing code provided in this field.
- atleast --> int (Optional)
- Minimum number of entries selected (defaults to none).
- orient --> One of ORI_VERTICAL, ORI_HORIZONTAL (Optional)
- Orientation of the mini-table for layout of multiple inputs.
A listbox higher than one entry. Either ''zero or one'' choices, OR ''zero or many'' choices can be made, thus, a listbox can be in one of two modes:
If you want to provide a single mode where the listbox forces the user to provide at least one value, use the 'required' option.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- choices --> Sequence of str or (str, unicode)
- Choice-label pairs: the ordered choices, to be rendered and checked against when parsing. This is not a mapping because order is important for rendering. If the elements of the list are pairs, the label is used for the user-visible strings to be used when rendering the widget. Note that we also accept integers for choices instead of ascii strings, but these will be automatically converted to strings.
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- choices --> Sequence of str or (str, unicode)
- Choice-label pairs: the ordered choices, to be rendered and checked against when parsing. This is not a mapping because order is important for rendering. If the elements of the list are pairs, the label is used for the user-visible strings to be used when rendering the widget. Note that we also accept integers for choices instead of ascii strings, but these will be automatically converted to strings.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- nocheck --> bool (Optional)
- Set this to True if you want to prevent the parser from cross-checking the values against the choices set in the instance of this field. When parsing, do not perform checks specific to the choices set on against the received values. This is useful if the set of choices for this field is generated dynamically and you will do your validation by hand. Another thing that can be done is to not use this but to call setchoices() before running the parser on the arguments, if in the handler you know which choices are possibly valid and would like to use the parsing code provided in this field.
- atleast --> int (Optional)
- Minimum number of entries selected (defaults to none).
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- nocheck --> bool (Optional)
- Set this to True if you want to prevent the parser from cross-checking the values against the choices set in the instance of this field. When parsing, do not perform checks specific to the choices set on against the received values. This is useful if the set of choices for this field is generated dynamically and you will do your validation by hand. Another thing that can be done is to not use this but to call setchoices() before running the parser on the arguments, if in the handler you know which choices are possibly valid and would like to use the parsing code provided in this field.
- allow_missing --> bool (Optional)
- If this is set, allow missing values, i.e. if the value is not sent by the browser, do not raise an error. This is useful if the widget may be hidden conditionally.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- multiple --> bool (Optional)
- Set this to True if the field should allow more than one value maximum to be set.
- size --> int (Optional)
- The height/number of visible elements of the listbox. By default, if left unset, it will use a reasonable minimum or the number of choices if very small.
Field that renders an option menu, which allow the user to select a single choice among many.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- choices --> Sequence of str or (str, unicode)
- Choice-label pairs: the ordered choices, to be rendered and checked against when parsing. This is not a mapping because order is important for rendering. If the elements of the list are pairs, the label is used for the user-visible strings to be used when rendering the widget. Note that we also accept integers for choices instead of ascii strings, but these will be automatically converted to strings.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- nocheck --> bool (Optional)
- Set this to True if you want to prevent the parser from cross-checking the values against the choices set in the instance of this field. When parsing, do not perform checks specific to the choices set on against the received values. This is useful if the set of choices for this field is generated dynamically and you will do your validation by hand. Another thing that can be done is to not use this but to call setchoices() before running the parser on the arguments, if in the handler you know which choices are possibly valid and would like to use the parsing code provided in this field.
- allow_missing --> bool (Optional)
- If this is set, allow missing values, i.e. if the value is not sent by the browser, do not raise an error. This is useful if the widget may be hidden conditionally.
- onchange --> str (JavaScript) (Optional)
- JavaScript to run when the selector changes.
Field that renders radio buttons, which allow the user to select a single choice among many. This field is rendered in a specific orientation.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- choices --> Sequence of str or (str, unicode)
- Choice-label pairs: the ordered choices, to be rendered and checked against when parsing. This is not a mapping because order is important for rendering. If the elements of the list are pairs, the label is used for the user-visible strings to be used when rendering the widget. Note that we also accept integers for choices instead of ascii strings, but these will be automatically converted to strings.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- nocheck --> bool (Optional)
- Set this to True if you want to prevent the parser from cross-checking the values against the choices set in the instance of this field. When parsing, do not perform checks specific to the choices set on against the received values. This is useful if the set of choices for this field is generated dynamically and you will do your validation by hand. Another thing that can be done is to not use this but to call setchoices() before running the parser on the arguments, if in the handler you know which choices are possibly valid and would like to use the parsing code provided in this field.
- allow_missing --> bool (Optional)
- If this is set, allow missing values, i.e. if the value is not sent by the browser, do not raise an error. This is useful if the widget may be hidden conditionally.
- orient --> One of ORI_VERTICAL, ORI_HORIZONTAL (Optional)
- Orientation of the mini-table for layout of multiple inputs.
A file being sent by the client. The returned value is an instance of the FileUpload class.
There are lots of details about file upload mechanics at http://www.cs.tut.fi/~jkorpela/forms/file.html
To peruse the results of a file upload object, you will be given access to a FileUpload class, on which you will be able to read() the contents or access the .filename attribute, e.g.
binary_image = parser['photo'].read() client_filename = parser['photo'].filename
Depending on the web framework using this, it might not be possible to get access to the filename, this depends on your backend. In any case, the filename that comes from the client side is not very useful anyway, apart maybe to initialize a file upload field on query, and even then, most browsers do not allow this to happen (it could be a security problem).
Note that the parser's getvalue() method will cull the results from FileUpload fields, because of the way these values are usually meant to be used--that is, as form data to be pickled or passed around. You are supposed to handle file upload data manually.
Observer that this field type is treated a little bit specially in the re-render loop: its values are removed automatically from the form-data (see FormParser) and the display renderers ignore and do not render them.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- filtpat --> str (Optional)
- Filter string to initialize the browser dialog on the client-side with. This corresponds to the 'accept' attribute of the corresponding HTML input field.
A file being set or reset by the client. The returned value is an instance of the FileUpload class. This field provides a way that a client can submit a new file or remove an existing file from the server. If the client enters a value to be sent, the uploaded file is meant to replace the existing one, and if a special 'Remove' checkbox is checked, it sends a message to remove the file instead.
See FileUploadField for more details on the basic mechanisc of this field.
There are lots of details about file upload mechanics at http://www.cs.tut.fi/~jkorpela/forms/file.html
To peruse the results of this field, you need to observe the returned value, which can be one of:
Note: it would be nice to be able to disable the file widget when the reset button is enabled. We need to write a little bit of JavaScript to do that.
Valid Attributes
- name --> str
- Unique identifier name for the field, and name of the form variables as well.
- label --> str (Optional)
- The visible label used by the form rendering.
- state --> one of Field._states (Optional)
- Whether the field is to be rendered visible, readonly, disabled or hidden. This value represents the default state, and can be overridden when the field is rendered. You can use the values Field.NORMAL (default), Field.READONLY, Field.DISABLED, Field.HIDDEN.
- initial --> valid data type for Field (Optional)
- Default value that is used for rendering the field with known initial conditions if no value is given for it. Important note: this value is not used by the parsing at all. If an argument is missing during parsing, the value associated with the field will be set to None. This is NOT a default value to be provided by the parser if the field is not submitted.
- starred --> bool (Optional)
- Mark field label as being a required input field. Fields which are optionally required, i.e. those fields which accept the 'required' option, are automatically starred if they are required. This can be used in the case where many fields are used for entering one value, and for example, some are selectively hidden by JavaScript code, and even though the fields are not required by the automated parsing, you need to add a star marker to some of those fields, to let the user know he has to enter a value there.
- required --> bool (Optional)
- Indicates that if the value is missing from the arguments during parsing, and error will be signaled for that input. If 'required' is not set, a missing argument will produce a value of None in the parser for the corresponding field.
- filtpat --> str (Optional)
- Filter string to initialize the browser dialog on the client-side with. This corresponds to the 'accept' attribute of the corresponding HTML input field.
- remlabel --> str (Optional)
- String to be used as the label for the 'reset' checkbox. This should be a string that will only get translated at the moment of rendering.