You can pass in either the primary key or a row object to the form.
If a primary key (item_id) is passed in,
you must also provide the schema.
The model will use the item_class (DBIC source name) to fetch the row from the database.
If you pass in a row object (item),
the schema,
item_class,
and item_id will be set from the row.

A select field will automatically retrieve a select list from the database,
if the proper column names are provided.
Single selects handle 'belongs_to' relationships,
where the related table is used to construct a selection list from the database.

A multiple select is either a 'Select' with multiple => 1 set,
or a field of the 'Multiple' type.
The name of a Multiple select which pulls options from the database automatically should be the name of the 'many_to_many' relationship.
The 'value' of the field is derived from the 'has_many' part of the relationship.

The primary key is used for the 'id' of the select.
The 'label' column of the select is assumed to be 'name'.
If the label column has a different name,
it must be specified with 'label_column'.

A compound field represents a single relationship to another table. Although most compound relations can be handled without providing a primary key, in some circumstances you may need to provide a PrimaryKey field, or add extra values in update_model.

The default for compound fields is that if all subfields are empty, the value of the compound field is set to undef (null). For some types of relations, you may want to set the 'not_nullable' flag to force the field to contain all subfields anyway, such as when the related rows are not deleted when empty. See test t/compound/empty.t for a demonstration of the difference in output.

There are some complications with creating Repeatable elements (with the PrimaryKey field set to undef) in a database and re-presenting the form. See HTML::FormHandler::Field::Repeatable for more info.