NAME

SYNOPSIS

  package Person;

  use base 'Rose::Object';

  use Rose::Object::MakeMethods::Generic
  (
    scalar => [ 'name', 'age' ],
    array  => 'emails',
  );

  ...  

  package Email;

  use base 'Rose::Object';

  use Rose::Object::MakeMethods::Generic
  (
    scalar => 
    [
      'address',
      'type' => { check_in => [ 'home', 'work' ] },
    ],
  );

  ...

  package EmailForm;

  use base 'Rose::HTML::Form';

  sub build_form 
  {
    my($self) = shift;

    $self->add_fields
    (
      address     => { type => 'email', size => 50, required => 1 },
      type        => { type => 'pop-up menu', choices => [ 'home', 'work' ],
                       required => 1, default => 'home' },
      save_button => { type => 'submit', value => 'Save Email' },
    );
  }

  sub email_from_form { shift->object_from_form('Email') }
  sub init_with_email { shift->init_with_object(@_) }

  ...

  package PersonEmailsForm;

  use base 'Rose::HTML::Form';

  sub build_form 
  {
    my($self) = shift;

    $self->add_fields
    (
      name        => { type => 'text',  size => 25, required => 1 },
      age         => { type => 'integer', min => 0 },
      save_button => { type => 'submit', value => 'Save Person' },
    );

    ##
    ## The important part happens here: add a repeatable form
    ##

    # A person can have zero or more emails
    $self->add_repeatable_form(emails => EmailForm->new);

    # Alternate ways to add the same repeatable form:
    #
    # Name/hashref pair:
    # $self->add_repeatable_form(emails => { form_class => 'EmailForm' });
    #
    # Using the generic add_form() method:
    # $self->add_form
    # (
    #   emails => 
    #   {
    #     form_class    => 'EmailForm',
    #     default_count => 0,
    #     repeatable    => 1,
    #   }
    # );
    #
    # See the documentation for Rose::HTML::Form's add_forms() and 
    # add_repeatable_forms() methods for more information.
  }

  sub init_with_person
  {
    my($self, $person) = @_;

    $self->init_with_object($person);

    # Delete any existing email forms and create 
    # the appropriate number for this $person

    my $email_form = $self->form('emails');
    $email_form->delete_forms;

    my $i = 1;

    foreach my $email ($person->emails)
    {
      $email_form->make_form($i++)->init_with_email($email);
    }
  }

  sub person_from_form
  {
    my($self) = shift;

    my $person = $self->object_from_form(class => 'Person');

    my @emails;

    foreach my $form ($self->form('emails')->forms)
    {
      push(@emails, $form->email_from_form);
    }

    $person->emails(@emails);

    return $person;
  }

DESCRIPTION

Rose::HTML::Form::Repeatable works like a wrapper for an additional level of sub-forms. The Rose::HTML::Form::Repeatable object itself has no fields. Instead, it has a list of zero or more sub-forms, each of which is named with a positive integer greater than zero.

The synopsis above contains a full example. In it, the "PersonEmailsForm" contains zero or more EmailForm sub-forms under the name "emails". The "emails" name identifies the Rose::HTML::Form::Repeatable object, while "emails.N" identifies each EmailForm object contained within it (e.g., "emails.1", "emails.2", etc.).

Each repeated form must be of the same class. A repeated form can be generated by cloning a prototype form or by instantiating a specified prototype form class.

A repeatable form decides how many of each repeated sub-form it should contain based on the contents of the query parameters (contained in the params attribute for the parent form). If there are no params, then the default_count determines the number of repeated forms.

Repeated forms are created in response to the init_fields or prepare methods being called. In the synopsis example, the "person_from_form" method does not need to create, delete, or otherwise set up the repeated email sub-forms because it can sensibly assume that the init_fields and/or prepare methods have been called already. On the other hand, the "init_with_person" method must configure the repeated email forms based on the number of email addresses contained in the "Person" object that it was passed.

On the client side, the usual way to handle repeated sub-forms is to make an AJAX request for new content to add to an existing form. The make_form method is designed to do exactly that, returning a correctly namespaced Rose::HTML::Form-derived object ready to have its fields serialized (usually through a template) into HTML which is then inserted into the existing form on a web page.

This class inherits from and follows the conventions of Rose::HTML::Form. Inherited methods that are not overridden will not be documented a second time here. See the Rose::HTML::Form documentation for more information.

CONSTRUCTOR

new PARAMS

Constructs a new Rose::HTML::Form::Repeatable object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

CLASS METHODS

default_form_class [CLASS]

Get or set the name of the default Rose::HTML::Form-derived class of the repeated form. The default value is Rose::HTML::Form.

OBJECT METHODS

default_count [INT]

Get or set the default number of repeated forms to create in the absence of any parameters. The default value is zero.

empty_is_ok [BOOL]

Get or set a boolean value that indicates whether or not it's OK for a repeated form to be empty. (That is, validation should not fail if the entire sub-form is empty, even if the sub-form has required fields.) Defaults to false.

init_fields

In addition to doing all the usual things that the base class implementation does, this method creates or deletes repeated sub-forms as necessary to make sure they match the query parameters, if present, or the default_count if there are no parameters that apply to any of the sub-forms.

init_with_objects [ OBJECTS | PARAMS ]

Given a list of OBJECTS or name/value pairs PARAMS, initialize each sub-form, taking one object from the list and passing it to a method called on each sub-form. The first object is passed to the first form, the second object to the second form, and so on. (Form order is determined by the the order forms are returned from the forms method.)

Valid parameters are:

make_form INT

Given an integer argument greater than zero, create, add to the form, and return a new numbered prototype form clone object.

make_next_form

Create, add to the form, and return a new numbered prototype form clone object whose rank is one greater than the the highest-ranking existing sub-form.

objects_from_form [PARAMS]

Return a list (in list context) or reference to an array (in scalar context) of objects corresponding to the list of repeated sub-forms. This is done by calling a method on each sub-form and collecting the return values. Name/value parameters may be passed. Valid parameters are:

prepare

This method does the same thing as the init_fields method, but calls through to the base class prepare method rather than the base class init_fields method.

prototype_form [FORM]

Get or set the Rose::HTML::Form-derived object used as the prototype for each repeated form.

prototype_form_class [CLASS]

Get or set the name of the Rose::HTML::Form-derived class used by the prototype_form_clone method to create each repeated sub-form. The default value is determined by the default_form_class class method.

prototype_form_spec [SPEC]

Get or set the specification for the Rose::HTML::Form-derived object used as the prototype for each repeated form. The SPEC can be a reference to an array, a reference to a hash, or a list that will be coerced into a reference to an array. In the absence of a prototype_form, the SPEC is dereferenced and passed to the "new()" method called on the prototype_form_class in order to create each prototype_form_clone.

prototype_form_clone

Returns a clone of the prototype_form, if one was set. Otherwise, creates and returns a new prototype_form_class object, passing the prototype_form_spec to the constructor.

AUTHOR

LICENSE