4.2. Widgets Reference
This page is a syntax reference and general guide for defining and using Widgets.
Widget Attribute Topics | ||
|---|---|---|
Common Widget Attributes
The table below describes attributes common to nearly all widgets. Illustrations and special attributes listings for each of the standard widgets follows.
| Name | Description | Possible Values |
|---|---|---|
| condition | A string containing a TALES expression to determine whether or not a field/widget is
included on a view or edit page.
This does not distinguish between view and edit mode. | Your TALES expression may referenc the current context as 'object' and the Plone site root as 'portal' |
| description | Help or explanatory text for the field. Usually shown on the edit form under the label and above the input field. | |
| description_msgid | The i18n identifier for the description message. Used to translate the message. Should be unique within your product's i18n domain. | 'help_type_field' |
| label | The label that will appear in the field. | Any string, for example, Start Date for a field start_date. Also label_msgid (takes string message ids for i18n.) |
| label_msgid | The i18n identifier for the label message. Should be unique within your product's i18n domain. | 'label_type_field' |
| i18n_domain | The i18n domain specifier for your product. This should be unique for your product, and will be used to find the translation catalogs for your product. | 'productname' |
| modes | The modes that this widget will be shown in; by default there are two modes: view and edit. | A list of modes as strings; by default ("view", "edit"). |
| populate | If this is enabled, the view and edit fields will be populated. Usually this is enabled, but for fields such as a password field, this shouldn't be the case. Usually this is true by default. | True or False |
| postback | If this is enabled, then when an error is raised, the field is repopulated; for fields such as a password field, this shouldn't be the case. Usually this is True by default. | True or False |
| visible | Determines whether or not the field is visible view and edit mode. This is a dictionary mapping the view mode to a string describing the visibility. Choices are visible, hidden (rendered in an HTML hidden form value), invisible (not rendered at all). | For example, {'view': 'visible', 'edit': 'hidden' } means that the view will show, but the edit page will hide the value. |
Standard Widgets
BooleanWidget
Renders an HTML checkbox, from which users can choose between two values such as on/off, true/false, yes/no.
CalendarWidget
Renders a HTML input box with a helper popup box for choosing dates.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| format | string | Defines the date/time format using strftime, e.g. '%d.%m.%Y', for the view.
(See the strftime section of the Python time documentation.
If this is not specified, the long form of the portal's local time format is used. | |
| future_years | integer | 5 | Specifies the number of future years offered by the year drop-down portion of the date widget. Do not use both future_year and end_year. (Plone 2.5+) |
| starting_year | integer | 1999 | The first year offered by the year drop-down. (Plone 2.5+) |
| ending_year | integer | None | The final year offered by the year drop-down. Do not use both future_years and end_year. (Plone 2.5+) |
| show_hm | boolean | True | Should the widget ask for a time as well as a date? (Plone 2.5+) |
ComputedWidget
Generally used for ComputedField field type, it renders the computed value. Note that if your field has a vocabulary, and the field value is a key in that vocabulary, the widget will lookup the key in the vocabulary and show the result.
Standard Properties
| Name | Type | Default | Description |
|---|---|---|---|
| modes | tuple | ('view', 'edit') | As ComputedField is a read-only field, this property can be used to prevent the widget from appearing in edit templates, by setting it to just ('view',). |
DecimalWidget
In edit mode, renders an HTML text input box which accepts a fixed point value.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| thousands_commas | boolean | False | In view mode, formats the value to shows commas for thousands. For example, when thousands_commas is True, "7632654849635.02" is displayed as "7,632,654,849,635.02". (Note: this feature is not localized; it uses commas independent of locale. |
| whole_dollars | boolean | False | Shows whole dollars in view, leaving out the cents. Enter "1.123", and "$1" is shown. (Note: this feature is not localized; it uses the dollar sign independent of locale.) |
| maxlength | 255 | Maximum input size; sets the HTML input tag's maxlength attribute. | |
| dollars_and_cents | boolean | False | In view mode, shows dollars and cents. Enter "123.123" and "$123.12" is shown. (Note: this feature is not localized; it always uses the dollar sign, period, and two digits precision.) |
| size | 5 | Size of the input field; sets the HTML input tag's size attribute. |
FileWidget
Renders an HTML widget so a user can upload a file.
ImageWidget
Renders an HTML widget that can be used to upload, display, delete, and replace images. You can provide a display_threshold that allows you to set the size of an image; if it's below this size, the image will display in the Web page.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| display_threshold | integer | 102400 | Only display the image inline if img.getSize() <= display_threshold |
InAndOutWidget
In edit mode, renders a widget for moving items from one list to another. Items are removed from the source list. This can be used to choose multiple values from a list. This provides a good alternative to the MultiSelectionWidget when the vocabulary is too long for checkboxes.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| size | 6 | Size of the select widget; sets the HTML select tag's size attribute. |
| Name | Type | Default | Description |
|---|---|---|---|
| maxlength | 255 | Maximum input size; sets the HTML input tag's maxlength attribute | |
| size | 5 | Size of the input field; sets the HTML input tag's size attribute. |
KeywordWidget
This widget allows the user to select keywords or categories from a list. It is
used for the Categories field in the Categorization Schema (Plone 3+)
or the equivalent Keywords field on the Properties Tab (Plone < 3)
of a content object.
Keywords are drawn from the field vocabulary and/or the unique values for the
field in a specified catalog.
Additional keywords may be added unless the enforceVocabulary property of the
field is True.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| vocab_source | portal_catalog | Sets the catalog to search for additional vocabulary to be combined with the vocabulary defined for the field. Additional keywords from existing content are found using catalog.uniqueValuesFor(fieldName). | |
| roleBasedAdd | True | Only shows the "New keywords" input for adding keywords if the current user has one of the roles stored in the allowRolesToAddKeywords property in the site_properties property sheet in portal_properties |
LabelWidget
Used to display labels on forms -- without values or form input elements.
LinesWidget
Displays a text area so that users can enter a list of values, one per line.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| rows | integer | 5 | Rows of the lines widget; sets the HTML textarea tag's rows attribute. |
| cols | integer | 40 | Columns of the lines widget; sets the HTML textarea tag's cols attribute. |
MultiSelectionWidget
A selection widget; by default it's an HTML select widget which can be used to choose multiple values. As a checkbox users can choose one or more values from a list (useful if the list is short).
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| format | string | select | Possible values: 'select' or 'checkbox'. Uses a either a series of checkboxes or a multi-selection list. Note that checkboxes have much better usability for short vocabularies. Consider using the InAndOutWidget for longer vocabularies. |
| size | 5 | Defines the size of the multi-select list. Does not apply for checkboxes. |
PasswordWidget
Renders an HTML password input.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| maxlength | 255 | Maximum input size; sets the HTML input tag's maxlength attribute. | |
| size | 20 | Size of the input field; sets the HTML input tag's size attribute. |
Standard Properties
| Name | Type | Default |
|---|---|---|
| populate | boolean | False |
| postback | boolean | False |
| modes | ('edit',) |
PicklistWidget
Similar to the InAndOutWidget, but the values stay in the source list after selection.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| size | integer | 6 | Size of the selection box; sets the HTML select tag's size attribute. |
ReferenceWidget
Renders an HTML text input box which accepts a list of possible reference
values. Used in combination with the Reference Field.
Note: In Plone 2.5 and above, the ReferenceBrowserWidget is
a usually a better choice for a reference widget due to its ability to browse for content
referenceable objects.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| checkbox_bound | 5 | When the number of items exceeds this value, multi-selection lists are used. Otherwise, radio buttons or checkboxes are used. | |
| destination | None | May be:
| |
| addable | False | Create createObject link for every addable type | |
| destination_types | None | Either a single type given as a string, or a list of types given as a string, defining what types we allow adding to. Only applies when addable is set on the widget. |
ReferenceBrowserWidget
A sophisticated widget for browsing, adding and deleting references.
Standard in Plone 2.5+, available for earlier versions as an add-on product.
Import from Products.ATReferenceBrowserWidget.ATReferenceBrowserWidget.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| size | integer | Size of the field if not multiValued; sets the HTML input tag's size attribute. | |
| default_search_index | string | SearchableText | when a user searches in the popup, this index is used by default |
| show_indexes | boolean | False | If True, a drop-down list is shown in the popup to select the index used for searching. If set to False, default_search_index will be used. |
| available_indexes | dict | {} |
Optional dictionary containing all the indexes that
can be used for searching along with their friendly names.
Format: {'catalogindex':'Friendly Name of Index', ... }
The friendly names are shown in the widget. Caution: If you set show_indexes True, but do not use this property to specify indexes, then all the indexes will be shown. |
| allow_search | boolean | True | If True, a search form is included in the popup. |
| allow_browse | True | Allows the user to browse content to find referenceable content. | |
| startup_directory | string | '' | Directory shown when the popup opens. Optional. When empty, the current folder is used. See the ATReferenceBrowser readme.txt for advanced usage. |
| base_query | dict or name of method | Defines query terms that will apply to all searches, mainly useful to create specific restrictions when allow_browse=0. Can be either a dictonary with query parameters, or the name of a method or callable available in cotext that will return such a dictionary. | |
| force_close_on_insert | boolean | False | If true, closes the popup when the user choses insert. This overrides the default behavior in multiselect mode. |
| search_catalog | string | 'portal_catalog' | Specifies the catalog used for searches |
| allow_sorting | boolean | False | Allows changing the order of referenced objects (requires multiValued). |
| show_review_state | boolean | False | If True, popup will display the workflow state for objects. |
| show_path | boolean | False | If True, display the relative path (relative to the portal object) of referenced objects. |
| only_for_review_states | None | If set, content items are only referenceable if their workflow state matches one of the specified states. If None there will be no filtering by workflow state. | |
| image_portal_types | sequence | () | Use to specify a list of image portal_types. Instances of these portal types are previewed within the popup widget |
| image_method | string | None | Specifies the name of a method that is added to the image URL to preview the image in a particular resolution (e.g. 'mini' for thumbnails). |
| history_length | integer | 0 | If not zero, enables a history feature that show the paths of the last N visited folders. |
| restrict_browsing_to_startup_directory | boolean | False | If True, the user will not be able to browse above the starting directory. |
RichWidget
Allows the input of text, or upload of a file, in multiple formats that are then transformed as necessary for display. For example, allows you to type some content, choose formatting and/or upload a file. If available, the visual editor set in personal preferences is used for editing and formatting.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| rows | integer | 5 | Number of rows. (Since the visual mode of the RichWidget is controlled by JavaScript, this is not very useful.) |
| cols | integer | 40 | Number of columns. (Since the visual mode of the RichWidget is controlled by JavaScript, this is not very useful.) |
| allow_file_upload | boolean | True | If True, a file upload option is included with the field. |
SelectionWidget
Renders an HTML selection widget, which can be represented as a dropdown, or as a group of radio buttons.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| format | string | 'flex' | Possible values: 'flex', 'select', 'radio'. Uses radio buttons when set to radio, and a single-selection list when set to select. Using flex will automatically use single-selection lists for more than three settings at a time, and a single-select list for up to three settings. |
StringWidget
Renders an HTML text input box which accepts a single line of text. For simple text lines such as author.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| maxlength | integer | 255 | Maximum input length in characters; sets the HTML input tag's maxlength attribute. |
| size | 30 | Size of the input widget; sets the HTML input tag's size attribute. |
TextAreaWidget
Renders an HTML text area for typing a few lines of text. Also provides for the entry of the content in multiple formats when allowed_content_types in the enclosing TextField allows it.
Special Properties
| Name | Type | Default | Description |
|---|---|---|---|
| rows | integer | 5 | Number of rows for the edit widget; sets the HTML textarea tag's rows attribute. |
| cols | integer | 40 | Column width of the edit widget; sets the HTML textarea tag's cols attribute. |
| append_only | boolean | False | Set this attribute to True to make an append-only TextArea widget. New text gets added to the top of the existing text, dividing the new text from the existing text using the divider property. The existing text is shown below the TextArea, and is not editable. This currently works with TextArea widgets and using plain text format. |
| divider | string | ======================== | Divider text marker to use for append only text areas. Only used then the append_only property is True. |
| maxlength | integer | False | If non-zero, sets a maximum input length in characters. Since the HTML textarea tag has no maxlength property, this is enforced via a JavaScript snippet. So, it is is not applicable when JavaScript is unavailable. |
Add-on Widgets
To find all available add-on widgets contributed by the community, follow this link.
Visit our