lithium\template\helper\Form::field()

public method

Generates a form field with a label, input, and error message (if applicable), all contained within a wrapping element.

 echo $this->form->field('name');
 echo $this->form->field('present', ['type' => 'checkbox']);
 echo $this->form->field(['email' => 'Enter a valid email']);
 echo $this->form->field(['name','email','phone'], ['div' => false]);

Parameters

  • mixed $name

    The name of the field to render. If the form was bound to an object passed in create(), $name should be the name of a field in that object. Otherwise, can be any arbitrary field name, as it will appear in POST data. Alternatively supply an array of fields that will use the same options [$field1 => $label1, $field2, $field3 => $label3]

  • array $options

    Rendering options for the form field. The available options are as follows:

    • 'label' mixed: A string or array defining the label text and / or parameters. By default, the label text is a human-friendly version of $name. However, you can specify the label manually as a string, or both the label text and options as an array, i.e.: ['Your Label Title' => ['class' => 'foo', 'other' => 'options']].
    • 'type' string: The type of form field to render. Available default options are: 'text', 'textarea', 'select', 'checkbox', 'password' or 'hidden', as well as any arbitrary type (i.e. HTML5 form fields).
    • 'template' string: Defaults to 'template', but can be set to any named template string, or an arbitrary HTML fragment. For example, to change the default wrapper tag from <div /> to <li />, you can pass the following: '<li{:wrap}>{:label}{:input}{:error}</li>'.
    • 'wrap' array: An array of HTML attributes which will be embedded in the wrapper tag.
    • list array|string: If 'type' is set to 'select', 'list' is an array of key/value pairs representing the $list parameter of the select() method. If 'type' is set to 'text', 'list' is used to render/reference a corresponding <datalist> element. It then can either be an array of option values or a string to reference an existing <datalist>.
    • error array|string|boolean: Allows to control rendering of error messages. By setting this option to false any messages are disabled. When an array mapping failed rule names to messages, will use these alternative message instead of the ones provided when the validation was originally defined (i.e inside the model). The array may contain a 'default' key which value will be used as a fallback message. In absence of a default message, the original messages get rendered instead. When providing a string it will be used for any error messages.

Returns

string

Returns a form input (the input type is based on the 'type' option), with label and error message, wrapped in a <div /> element.

Source

	public function field($name, array $options = []) {
		if (is_array($name)) {
			return $this->_fields($name, $options);
		}
		$method = __FUNCTION__;
		if (isset($options['type']) && !empty($this->_config['field-' . $options['type']])) {
			$method = 'field-' . $options['type'];
		}
		list(, $options, $template) = $this->_defaults($method, $name, $options);
		$defaults = [
			'label' => null,
			'type' => isset($options['list']) ? 'select' : 'text',
			'template' => $template,
			'wrap' => [],
			'list' => null,
			'error' => []
		];
		list($options, $field) = $this->_options($defaults, $options);

		$label = $input = null;
		$wrap = $options['wrap'];
		$type = $options['type'];
		$list = $options['list'];
		$error = $options['error'];
		$template = $options['template'];
		$notText = $template === 'field' && $type !== 'text';

		if ($notText && $this->_context->strings('field-' . $type)) {
			$template = 'field-' . $type;
		}
		if (($options['label'] === null || $options['label']) && $options['type'] !== 'hidden') {
			if (!$options['label']) {
				$options['label'] = Inflector::humanize(preg_replace('/[\[\]\.]/', '_', $name));
			}
			$label = $this->label(isset($options['id']) ? $options['id'] : '', $options['label']);
		}

		$datalist = null;
		if ($type === 'text' && $list) {
			if (is_array($list)) {
				list($list, $datalist) = $this->_datalist($list, $options);
			}
			$field['list'] = $list;
		}

		$call = ($type === 'select') ? [$name, $list, $field] : [$name, $field];
		$input = call_user_func_array([$this, $type], $call);

		if ($error !== false && $this->_binding) {
			$error = $this->error($name, null, ['messages' => $error]);
		} else {
			$error = null;
		}
		return $this->_render(__METHOD__, $template, compact(
			'wrap', 'label', 'input', 'datalist', 'error'
		));
	}