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 | |||||||||||||||
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:
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"
}
Antes de MediaWiki 1.35, los mensajes de i18n para mostrar como cabecera de sección o de subsección debían empezar por '-' si no había prefijo de mensaje. |
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.