Difference between revisions of "User:OliverCharles/ServerManual/Forms"

From MusicBrainz Wiki
(Document with_mod_fields)
(Document compound fields)
Line 40: Line 40:
 
=Advanced=
 
=Advanced=
  
==Composite Fields==
+
==Compound Fields==
  
Composite fields are fields that require multiple inputs to create a value. Examples of these are the date input fields (which split into YYYY-MM-DD), and track fields. For the most part, you can create your own composite fields
+
Compound fields are fields that require multiple inputs to create a value. Examples of these are the date input fields (which split into YYYY-MM-DD), and track fields. For the most part, you can create your own composite fields by inheriting from <tt>MusicBrainz::Server::Form::Field::Compound</tt>, and then writing the rest of your module like a normal form module.
 +
 
 +
Saddly, compound fields do not behave ''exactly'' like a form, so you may well need to use other compound fields as references.
 +
 
 +
You will also need to write a template to render the compound field. This template should be placed in the ''root/forms/widgets'' directory.
  
 
=Reference=
 
=Reference=

Revision as of 11:35, 15 April 2009

Forms are created in 3 separate parts - designing the form at the data level, designing a view to the form, and adding controller logic to work with the form.

Writing Form Modules

Form modules are handled by writing Form::Processor modules, in the MusicBrainz::Server::Form namespace. You should add a new level of hierarchy to match the name of your controller (for example, MusicBrainz::Server::Form::Annotation::Edit).

Rather than inheriting directly from Form::Processor, it is best to inherit from MusicBrainz::Server::Form - this module exports some small helper methods to create common fields such as edit notes, and may do more in the future.

The single most important method in a form module is profile. This is the skeleton for a template, and will create all relevant fields. Your profile method should return a hash reference, with fields under the required and optional keys.

sub profile
{
    return {
        required => {
            <name> => <type>,
        },
        optional => {
            <name> => <type>,
        },
    }
}

Rather than documenting the details of how profile work here, you should read the official documentation.

For Forms That Enter Edits

If your form creates an edit, you should wrap the result of profile with a call to with_mod_fields. This will create fields for an edit note, and a toggle to change auto-editor status.

sub profile
{
    return shift->with_mod_fields({
        …
    })
}

Advanced

Compound Fields

Compound fields are fields that require multiple inputs to create a value. Examples of these are the date input fields (which split into YYYY-MM-DD), and track fields. For the most part, you can create your own composite fields by inheriting from MusicBrainz::Server::Form::Field::Compound, and then writing the rest of your module like a normal form module.

Saddly, compound fields do not behave exactly like a form, so you may well need to use other compound fields as references.

You will also need to write a template to render the compound field. This template should be placed in the root/forms/widgets directory.

Reference

Field Types

MusicBrainz::Server::Form

with_mod_fields

Add fields for an edit note, and the ability to toggle auto-editor status.