Subform

This module provides a form element that allows embedding of a form as a subform into another form. You should only install it if another module is instructing you to do so or if you are an interested developer.

This module is the successor of fago's Subform Element module. Thank you, fago!

Related modules

• Relation edit widget

  Provides a widget for Relation dummy field, embedding related nodes' edit forms.

• User modal

  Allows opening the Register/ Login/ Reset password menu items
  as tabs in a modal overlay.

API

Properties for subform element

 $form['my_node_subform'] = array(
   '#type' => 'subform',
   '#subform_id' => 'node_form',
   '#subform_file' => array('module' => 'node', 'name' => 'node.pages'),
   '#subform_arguments' => array($node),
   '#subform_default_triggering_element' => array('actions', 'submit'),
);

All properties, except for #subform_id, are optional.

#subform_id

(Required) The unique string identifying the desired form to be used as subform.

#subform_file

A file that will be included before the subform is build. Either a string containing the filepath or an array matching the arguments of module_load_include().

#subform_arguments

An array of arguments to pass to the subform's constructor function.

#subform_default_triggering_element

An array containing the #parents of the submit button inside the subform to be used as the default triggering element for that subform. If not provided the first button inside the subform will be used.

#default_value

An array of default input for the subform.

#submit

An array of submit handlers that will be called if the form is being submitted using any button from the subform. Defaults to subform_element_submit() which will submit the subform only.

#required

If set to TRUE validation errors on the subform will prevent the parent form from submitting. If set to FALSE the parent form will be able to submit even if the subform contains errors. The subform can however only be submitted if it doesn't contain errors.

Properties for triggerable element

$form['preview_all'] = array(
  '#type' => 'submit',
  '#submit' => array('subform_submit_all'),
  '#subform_triggering_element' => array(
    'node_form' => array('actions', 'preview'),
  ),
);

#subform_triggering_element

An array containing the #parents of the submit buttons inside subforms to be used as the triggering element for those subform, grouped by their form_id.

Submit handlers

subform_element_submit

Executes the subform that is the triggering_element (which is the case if the form was submitted using any button of the subform).

subform_submit_all

Executes all valid subforms.

By default submitting the form using any button from a subform will only submit the subform (suppressing any validation errors of the wrapper form).

Also by default submitting the form using any button from the wrapper from will only submit the wrapper form.

To make the wrapper form submit its subforms add subform_submit_all() to wrapper form's (or just one specific button's) #submit handlers.

Alternatives

• Multiple forms

  An API module which lets you put several forms into one
  .