Basics: Widgets

ArchGenXML will pick a default widget for your fields and fill in default labels and descriptions. For example, a 'string' field gets a 'StringWidget' by default. You can override this in two ways.

First of all, you can set a tagged value 'widget' on your field and provide the code for the entire widget definition. This method is depreciated in favour of individual widget properties, which make it much easier to manage your widgets, however.

Widget options are specified with the prefix 'widget:'. As with normal field tagged values, unrecognised options will be passed straight through to the widget definition.

The most common widget options are:

widget:label -- sets the widget's label

widget:description -- sets the widget's description

widget:label_msgid -- overrides the default label message id (i18n)

widget:description_msgid -- overrides the default description message id (i18n)

widget:i18n_domain -- sets the i18n domain (defaults to the product name)

You may also use widget-specific options, such as 'widget:size' where they apply.

Changing the widget of a field

Let's assume you use a StringField for capturing the type of a fruit and you know that you'll just have 5 types of fruit to select from (apple, peach, pear, banana and cherry). It's probably the best to use a 'SelectionWidget', coupled with a vocabulary set on the field (by setting the tagged value 'vocabulary' to 'python:["apple", "peach", "pear", "banana"]') to restrict the user to these addable types.

The first way to achieve this may be to use the 'widget' tagged value to set the entire widget in one go. For example, you could write::

SelectionWidget(
label="""Fruit type""",
description="""Select one of the fruits""",
label_msgid='label_fruit_type',
description_msgid='help_fruit_type',
i18n_domain='fruit',
),

However, that method is depreciated in the latest version of ArchGenXML, where you can set the property 'widget:type' to be the name of your chosen widget type, such as 'StringWidget' or 'SelectionWidget'. In previous versions of ArchGenXML, you can accomplish the same thing by setting 'widget' to be the name of your widget only, and use the specific tagged values (such as 'widget:label') to set the fields of the widget explicitly.

Using custom widgets

You have two options to change the type of the widget to a custom type, a type outside Archetypes base framework:

To change the type for one field use 'widget:type' and set it to 'MyCustomWidget' if you want to use 'MyCustomWidget'

To change a the widget used for one field-type for the whole model, a product, a package or just for all fields in one class you can set on mode, product, package or class level the tagged value 'default:widget:FIELDNAMEABBREVIATION' to 'WIDGETNAME'. For example use the tagged value 'default:widget:Reference' and set it to 'ReferenceBrowserWidget' to use the ReferenceBrowserWidget instead of the ReferenceWidget. You might also want to use also the 'additional_imports' tagged value and set it to 'from ATReferenceBrowserWidget.ATReferenceBrowserWidget import ReferenceBrowserWidget' on your class to ensure that you get the widget definition imported into your class.