From Introduction to Form API:
Forms are defined by implementing the
\Drupal\Core\Form\FormInterface. Form classes handle creation, submission, and validation of a form so that all form related logic is grouped together. Drupal 8 provides base classes that you can extend for easy form creation.There are a few different base classes to choose from depending on the type of form you are creating. In most cases you'll likely start by extending one of these when creating your own forms.
- ConfigFormBase - For creating system configuration forms like the one found at admin/config/system/site-information.
- ConfirmFormBase - For providing users with a form to confirm an action such as deleting a piece of content.
- FormBase - The most generic base class for generating forms.
actions- Provides a wrapper element to group one or more buttons in a form.ajax- Provides a render element for adding Ajax to a render element.button- Provides an action button form element.checkbox- Provides a form element for a single checkbox.checkboxes- Provides a form element for a set of checkboxes.color- Provides a form element for choosing a color.container- Provides a render element that wraps child elements in a container.contextual_links- Provides a contextual_links element.contextual_links_placeholder- Provides a contextual_links_placeholder element.date- Provides a form element for date selection.datelist- Provides a datelist element.datetime- Provides a datetime element.details- Provides a render element for a details element, similar to a fieldset.dropbutton- Provides a render element for a set of links rendered as a drop-down button.email- Provides a form input element for entering an email address.entity_autocomplete- Provides an entity autocomplete form element.field_ui_table- Provides a field_ui table element.fieldgroup- Provides a render element for a group of form elements.fieldset- Provides a render element for a group of form elements.file- Provides a form element for uploading a file.form- Provides a render element for a form.hidden- Provides a form element for an HTML 'hidden' input element.html- Provides a render element for an entire HTML page: plus its children.html_tag- Provides a render element for any HTML tag, with properties and value.image_button- Provides a form element for a submit button with an image.inline_template- Provides a render element where the user supplies an in-line Twig template.item- Provides a display-only form element with an optional title and description.label- Provides a render element for displaying the label for a form element.language_configuration- Provides language element configuration.language_select- Provides a form element for selecting a language.link- Provides a link render element.machine_name- Provides a machine name render element.managed_file- Provides an AJAX/progress aware widget for uploading and saving a file.more_link- Provides a link render element for a "more" link, like those used in blocks.number- Provides a form element for numeric input, with special numeric validation.operations- Provides a render element for a set of operations links.page- Provides a render element for the content of an HTML page.page_title- Provides a render element for the title of an HTML page.pager- Provides a render element for a pager.password- Provides a form element for entering a password, with hidden text.password_confirm- Provides a form element for double-input of passwords.path- Provides a matched path render element.processed_text- Provides a processed text render element.radio- Provides a form element for a single radio button.radios- Provides a form element for a set of radio buttons.range- Provides a slider for input of a number within a specific range.responsive_image- Provides a responsive image element.search- Provides an HTML5 input element with type of "search".select- Provides a form element for a drop-down menu or scrolling selection box.status_messages- Provides a messages element.submit- Provides a form submit button.system_compact_link- Provides a link to show or hide help text on administration pages.table- Provides a render element for a table.tableselect- Provides a form element for a table with radios or checkboxes in left column.tel- Provides a form element for entering a telephone number.text_format- Provides a text format render element.textarea- Provides a form element for input of multiple-line text.textfield- Provides a one-line text field form element.token- Stores token data in a hidden form field.toolbar- Provides a render element for the default Drupal toolbar.toolbar_item- Provides a toolbar item that is wrapped in markup for common styling.url- Provides a form element for input of a URL.value- Provides a form element for storage of internal information.vertical_tabs- Provides a render element for vertical tabs in a form.view- Provides a render element to display a view.weight- Provides a form element for input of a weight.
Returns a unique id for the form.
Example:
<?php
// ...
public function getFormId() {
return 'mycustom_form';
}
// ...
?>Assembles a form based on a form array.
<?php
// ...
public function buildForm(array $form, FormStateInterface $form_state) {
$form['phone_number'] = array(
'#type' => 'tel',
'#title' => 'Example phone',
);
return $form;
}
// ...
?>Validates a form's input.
<?php
// ...
/**
* {@inheritdoc}
*/
public function validateForm(array &$form, FormStateInterface $form_state) {
if ($form_state->getValue('age') < 13) {
$form_state->setErrorByName('age', $this->t('You must be 13 or older to use this site.'));
}
}
// ...
?>Processes a form's input.
<?php
// ...
/**
* {@inheritdoc}
*/
public function submitForm(array &$form, FormStateInterface $form_state) {
drupal_set_message($this->t('You are @age years old.', array('@age' => $form_state->getValue('age'))));
}
// ...
?>Make sure you understand the Routing System before continuing.
example.form:
path: '/example-form'
defaults:
_title: 'Example form'
_form: '\Drupal\example\Form\ExampleForm'
requirements:
_permission: 'access content'
You can also retrieve the form programmatically, and also supply additional parameters as needed:
<?php
$form = \Drupal::formBuilder()->getForm('Drupal\mymodule\Form\ExampleForm', '555-123-4567');
?>To retrieve that phone number above, you would just modify your buildForm() method:
<?php
public function buildForm(array $form, FormStateInterface $form_state, $phone_number = NULL)
$form['phone_number'] = array(
'#type' => 'tel',
'#title' => $this->t('Phone'),
'#value' => $phone_number,
);
return $form;
}
?>Drupal 8 uses the hook method similar to Drupal 7 to alter an existing form.
For example, if your form has the ID some_form_id and your module is named mymodule,
you could add a fax number to the form:
<?php
function mymodule_form_some_form_id_alter(&$form, &$form_state) {
$form['fax_number'] = array(
'#type' => 'tel',
'#title' => $this->t('Fax Number'),
);
}
?>