HTMLForm

HTMLForm es una clase para gestionar cualquier cosa relacionada con formularios de la interfaz de usuario. MediaWiki 1.16 y posterior incluye HTMLForm en HTMLForm.php.

El tutorial de HTMLForm enseña los fundamentos de HTMLForm.

Parámetros

Especificaciones precisas para:

• Parámetros genéricos en la segunda parte del tutorial de HTMLForm
• Parámetros relacionados con tipos y clases en la tercera parte del tutorial de HTMLForm

Parámetro	Tipo	Descripción
type	string	Tipo de contenido del formulario que se desea crear. Por ejemplo, text, radio o multiselect. Estos tipos se corresponden a subclases específicas en HTMLForm. Esto se traduce a grandes rasgos en el atributo de tipo ‎<select>. Si no se especifica class, se utiliza como un mapa a través de HTMLForm::$typeMappings para obtener el nombre de la clase.
class	string	Subclase de PHP que se utilizará para este contenido de formulario. Esto consigue lo mismo que el parámetro de tipo, pero más directamente. ¡NO se trata de la clase CSS!
size	integer	Establece la longitud de los campos de texto
maxlength	integer	Establece la longitud máxima de los campos de texto
min	integer	Valor mínimo
max	integer	Valor máximo
invert	boolean	Establece las entradas de tipo 'toggle' (interruptor) como activadas por defecto
options	array	Las opciones mostradas en un elemento de formulario de tipo 'multiselect', 'radio' o 'select'. Hace corresponder las etiquetas de texto con los valores. Algunos tipos de campos admiten vectores multidimensionales. Overwrites 'options-message'.
rows	array	Número de filas que presentar en un elemento de formulario de tipo 'checkmatrix' o 'textarea'
columns	array	Número de columnas que presentar en un elemento de formulario de tipo 'checkmatrix'
force-options-off	array	Opciones para establecer casillas desmarcadas y deshabilitadas en un elemento de formulario de tipo 'checkmatrix'
force-options-on	array	Opciones para establecer casillas marcadas y habilitadas en un elemento de formulario de tipo 'checkmatrix'
section	string	Clave para que un mensaje i18n se muestre como cabecera de sección o de subsección. Las subsecciones deberían utilizar el carácter '/'; por ejemplo, foo/bar/baz crea una preferencia 'baz' dentro de la sección 'bar' que está dentro de la sección 'foo'
label-message, buttonlabel-message	string	Clave para que un mensaje i18n se muestre como etiqueta para una entrada o un botón de formulario. Clave de mensaje u objeto para que un mensaje utilice como etiqueta. Puede ser un vector de claves de mensajes y luego parámetros para el mensaje.
label, label-raw, buttonlabel	string	Etiqueta para una entrada o un botón de formulario. Redefinido por 'label-message'.
vertical-label	boolean	Inicialízalo a 'true' si deseas que la etiqueta aparezca encima de las opciones en lugar de a su izquierda.
id	string	Identificador del atributo que asignar a la entrada
cssclass	string	Atributo de clase que asignar a la entrada
csshelpclass	string	Clase CSS utilizada para dar estilo al texto de ayuda
validation-callback	array	Clase y función que utilizar para la validación de la entrada. Véase HTMLFormField::validate()
filter-callback	array	Clase y función que utilizar para filtrar la entrada. Te da la oportunidad de ajustar el valor introducido antes de que sea procesado. Véase HTMLFormField::filter()
help-message	string	Clave para que un mensaje i18n se muestre directamente debajo del elemento del formulario. Sobreescribe 'help-messages' y 'help'. Puede ser un vector de claves de mensajes y luego parámetros para el mensaje.
help	string	Mensaje que mostrar directamente debajo del elemento de formulario para utilizar como texto de ayuda.
tooltip	string	Sufijo de clave para que los mensajes i18n utilicen como título y/o atributos 'accesskey' (tooltip-TUVALOR and accesskey-TUVALOR)
placeholder	string	Valor que utilizar como atributo de marcador de posición (placeholder) HTML5
placeholder-message	string	Clave para que un mensaje i18n se muestre como marcador de posición
disabled	boolean	Deshabilita la edición y el envío de la entrada del formulario
readonly	boolean	Deshabilita la edición de la entrada del formulario
required	boolean	Si su valor es 'true', la entrada no se puede dejar en blanco. Se pasa al objeto indicando que es un campo obligatorio.
name	string	Reemplaza el nombre de la entrada (el valor predeterminado es wp{$fieldname}). Si deseas utilizar otro nombre (por ejemplo, uno que no tenga el prefijo «wp»), especifícalo aquí y se utilizará sin modificación.
dir	string	Dirección del elemento.
'options-messages'	array	associative array mapping message keys to values. Some field types support multi-level arrays. Overwrites 'options' and 'options-message'.
'options-message'	array	Clave de mensaje u objeto que analizar para extraer la lista de opciones (como 'ipbreason-dropdown').
'help-messages'	array	Vector de claves de mensajes u objetos. Como antes, cada elemento puede ser un vector de claves de mensajes y luego parámetros. Sobreescribe 'help'.
'help-inline'	array	Whether help text (defined using options above) will be shown inline after the input field, rather than in a popup. Defaults to true. Only used by OOUI form fields.
'hide-if'	array	Expression given as an array stating when the field should be hidden. The first array value has to be the expression's logic operator. Supported expressions: Expression Syntax Description 'NOT' [ 'NOT', array $expression ] Para ocultar un campo si una expresión dada no es verdadera. '===' [ '===', string $fieldName, string $value ] To hide a field if another field identified by $field has the value $value. '!==' [ '!==', string $fieldName, string $value ] Same as [ 'NOT', [ '===', $fieldName, $value ] 'OR', 'AND', 'NOR', 'NAND' [ 'XXX', array $expression1, ..., array $expressionN ] To hide a field if one or more (OR), all (AND), neither (NOR) or not all (NAND) given expressions are evaluated as true. Las expresiones se pasarán a un módulo JavaScript del lado del cliente que actualizará continuamente la visibilidad del campo.
'disable-if'	array	Expression given as an array stating when the field should be disabled, using the same syntax of the hide-if conditions discussed above.
nodata	boolean	if set (to any value, which casts to true), the data for this field will not be loaded from the actual request. Instead, always the default data is set as the value of this field.
default	string (or array)	Valor(es) por defecto para el campo (no confundir con $wgDefaultUserOptions ). Note extensions/skins adding preferences via hook must make use of UserGetDefaultOptions to set default value.

Ejemplo de uso

clase SpecialTestForm

<?php

class SpecialTestForm extends SpecialPage {
	public function __construct() {
		parent::__construct( 'TestForm' );
	}

	public function execute( $par ) {
		$this->getOutput()->setPageTitle( 'Test form' );

		$formDescriptor = [
			'myfield1' => [
				'section' => 'section1/subsection',
				'label-message' => 'testform-myfield1',
				'type' => 'text',
				'default' => 'Meep',
			],
			'myfield2' => [
				'section' => 'section1',
				'class' => 'HTMLTextField', // HTMLTextField same as type 'text'
				'label-message' => 'testform-myfield2',
			],
			'myfield3' => [
				'class' => 'HTMLTextField',
				'label' => 'Foo bar baz',
			],
			'myfield4' => [
				'class' => 'HTMLCheckField',
				'label' => 'This be a pirate checkbox',
				'default' => true,
			],
			'omgaselectbox' => [
				'class' => 'HTMLSelectField',
				'label' => 'Select an oooption',
				'options' => [
					'Pirates' => 'pirate',
					'Ninjas' => 'ninja',
					'Back to the NINJAR!' => 'ninjars',
				],
			],
			'omgmultiselect' => [
				'class' => 'HTMLMultiSelectField',
				'label' => 'Weapons to use',
				'options' => [
					'Cannons' => 'cannon',
					'Swords' => 'sword',
				],
				'default' => [ 'sword' ],
			],
			'radiolol' => [
				'class' => 'HTMLRadioField',
				'label' => 'Who do you like?',
				'options' => [
					'Pirates' => 'pirates',
					'Ninjas' => 'ninjas',
					'Both' => 'both',
				],
				'default' => 'pirates',
			],
		];

		$htmlForm = new HTMLForm( $formDescriptor, $this->getContext() );
		$htmlForm
			->setSubmitText( 'Foo submit' )
			->setSubmitCallback( [ $this, 'trySubmit' ] )
			->show();
	}

	public function trySubmit( $formData ) {
		if ( $formData[ 'myfield1' ] === 'Fleep' ) {
			return true;
		}

		return 'Fail';
	}
}

$wgSpecialPages['TestForm'] = 'SpecialTestForm';

i18n/en.json

{
	"@metadata": {
		"authors": [
			"MW_Kappa"
		]
	},
	"testform-desc": "some informative text for page Special:Version",
	"section1": "display text for section1",
	"subsection": "display text for subsection"
}

Formatos de visualización

El formato de visualización por defecto de HTMLForm es de tipo table, con las etiquetas en la columna izquierda y las entradas en la columna derecha. Es posible seleccionar otros formatos, por ejemplo, $htmlForm->setDisplayFormat( 'div' ); utilizará un diseño basado en elementos div; los otros, más raros, son raw e inline.

Versión de MediaWiki:

≥ 1.26

Para cambiar el formulario para que utilice el kit de herramientas OOUI para elementos HTMLForm, a partir de MediaWiki 1.26, tendrás que utilizar 'ooui' como formato de visualización en HTMLForm::factory:

$htmlForm = HTMLForm::factory( 'ooui', $formDescriptor, $this->getContext() );

Notas históricas

HTMLForm fue introducido por Werdna en r48740 como parte de su reescritura del sistema de preferencias. Históricamente, las versiones 1.4.0 a 1.11.0 de MediaWiki incluían una clase HTMLForm diferente escrita por Hashar y JeLuF. Esta clase HTMLForm fue retirada en r29245.