PHPXRef 0.7.1 : MediaWiki-1.24.0 : Detail view of HTMLForm.php

Class: HTMLForm - X-Ref

Object handling generic submission, CSRF protection, layout and
other logic for UI forms. in a reusable manner.

In order to generate the form, the HTMLForm object takes an array
structure detailing the form fields available. Each element of the
array is a basic property-list, including the type of field, the
label it is to be given in the form, callbacks for validation and
'filtering', and other pertinent information.

Field types are implemented as subclasses of the generic HTMLFormField
object, and typically implement at least getInputHTML, which generates
the HTML for the input field to be placed in the table.

You can find extensive documentation on the www.mediawiki.org wiki:
- https://www.mediawiki.org/wiki/HTMLForm
- https://www.mediawiki.org/wiki/HTMLForm/tutorial

The constructor input is an associative array of $fieldname => $info,
where $info is an Associative Array with any of the following:

'class'               -- the subclass of HTMLFormField that will be used
to create the object.  *NOT* the CSS class!
'type'                -- roughly translates into the <select> type attribute.
if 'class' is not specified, this is used as a map
through HTMLForm::$typeMappings to get the class name.
'default'             -- default value when the form is displayed
'id'                  -- HTML id attribute
'cssclass'            -- CSS class
'csshelpclass'        -- CSS class used to style help text
'options'             -- associative array mapping labels to values.
Some field types support multi-level arrays.
'options-messages'    -- associative array mapping message keys to values.
Some field types support multi-level arrays.
'options-message'     -- message key to be parsed to extract the list of
options (like 'ipbreason-dropdown').
'label-message'       -- message key for a message to use as the label.
can be an array of msg key and then parameters to
the message.
'label'               -- alternatively, a raw text message. Overridden by
label-message
'help'                -- message text for a message to use as a help text.
'help-message'        -- message key for a message to use as a help text.
can be an array of msg key and then parameters to
the message.
Overwrites 'help-messages' and 'help'.
'help-messages'       -- array of message key. As above, each item can
be an array of msg key and then parameters.
Overwrites 'help'.
'required'            -- passed through to the object, indicating that it
is a required field.
'size'                -- the length of text fields
'filter-callback      -- a function name to give you the chance to
massage the inputted value before it's processed.

__construct( $descriptor, $context = null,$messagePrefix = '') X-Ref

Build a new HTMLForm from an array of field attributes

param: array $descriptor Array of Field constructs, as described above
param: IContextSource $context Available since 1.18, will become compulsory in 1.18.
param: string $messagePrefix A prefix to go in front of default messages

setDisplayFormat( $format ) X-Ref

Set format in which to display the form

param: string $format The name of the format to use, must be one of
return: HTMLForm $this for chaining calls (since 1.20)

getDisplayFormat() X-Ref

Getter for displayFormat

return: string

isVForm() X-Ref

Test if displayFormat is 'vform'

return: bool

getClassFromDescriptor( $fieldname, &$descriptor ) X-Ref

Get the HTMLFormField subclass for this descriptor.

The descriptor can be passed either 'class' which is the name of
a HTMLFormField subclass, or a shorter 'type' which is an alias.
This makes sure the 'class' is always set, and also is returned by
this function for ease.

param: string $fieldname Name of the field
param: array $descriptor Input Descriptor, as described above
return: string Name of a HTMLFormField subclass

loadInputFromParameters( $fieldname, $descriptor ) X-Ref

Initialise a new Object for the field

param: string $fieldname Name of the field
param: array $descriptor Input Descriptor, as described above
return: HTMLFormField Instance of a subclass of HTMLFormField

prepareForm() X-Ref

Prepare form for submission.

return: HTMLForm $this for chaining calls (since 1.20)

tryAuthorizedSubmit() X-Ref

Try submitting, with edit token check first

return: Status|bool

show() X-Ref

The here's-one-I-made-earlier option: do the submission if
posted, or display the form with or without funky validation
errors

return: bool|Status Whether submission was successful.

trySubmit() X-Ref

Validate all the fields, and call the submission callback
function if everything is kosher.

return: bool|string|array|Status

wasSubmitted() X-Ref

Test whether the form was considered to have been submitted or not, i.e.
whether the last call to tryAuthorizedSubmit or trySubmit returned
non-false.

This will return false until HTMLForm::tryAuthorizedSubmit or
HTMLForm::trySubmit is called.

return: bool

setSubmitCallback( $cb ) X-Ref

Set a callback to a function to do something with the form
once it's been successfully validated.

param: callable $cb The function will be passed the output from
return: HTMLForm $this for chaining calls (since 1.20)

setValidationErrorMessage( $msg ) X-Ref

Set a message to display on a validation error.

param: string|array $msg String or Array of valid inputs to wfMessage()
return: HTMLForm $this for chaining calls (since 1.20)

setIntro( $msg ) X-Ref

Set the introductory message, overwriting any existing message.

param: string $msg Complete text of message to display
return: HTMLForm $this for chaining calls (since 1.20)

setPreText( $msg ) X-Ref

Set the introductory message, overwriting any existing message.

param: string $msg Complete text of message to display
return: HTMLForm $this for chaining calls (since 1.20)

addPreText( $msg ) X-Ref

Add introductory text.

param: string $msg Complete text of message to display
return: HTMLForm $this for chaining calls (since 1.20)

addHeaderText( $msg, $section = null ) X-Ref

Add header text, inside the form.

param: string $msg Complete text of message to display
param: string|null $section The section to add the header to
return: HTMLForm $this for chaining calls (since 1.20)

setHeaderText( $msg, $section = null ) X-Ref

Set header text, inside the form.

param: string $msg Complete text of message to display
param: string|null $section The section to add the header to
return: HTMLForm $this for chaining calls (since 1.20)

addFooterText( $msg, $section = null ) X-Ref

Add footer text, inside the form.

param: string $msg Complete text of message to display
param: string|null $section The section to add the footer text to
return: HTMLForm $this for chaining calls (since 1.20)

setFooterText( $msg, $section = null ) X-Ref

Set footer text, inside the form.

param: string $msg Complete text of message to display
param: string|null $section The section to add the footer text to
return: HTMLForm $this for chaining calls (since 1.20)

addPostText( $msg ) X-Ref

Add text to the end of the display.

param: string $msg Complete text of message to display
return: HTMLForm $this for chaining calls (since 1.20)

setPostText( $msg ) X-Ref

Set text at the end of the display.

param: string $msg Complete text of message to display
return: HTMLForm $this for chaining calls (since 1.20)

addHiddenField( $name, $value, $attribs = array() X-Ref

Add a hidden field to the output

param: string $name Field name. This will be used exactly as entered
param: string $value Field value
param: array $attribs
return: HTMLForm $this for chaining calls (since 1.20)

addHiddenFields( array $fields ) X-Ref

Add an array of hidden fields to the output

param: array $fields Associative array of fields to add;
return: HTMLForm $this for chaining calls

addButton( $name, $value, $id = null, $attribs = null ) X-Ref

Add a button to the form

param: string $name Field name.
param: string $value Field value
param: string $id DOM id for the button (default: null)
param: array $attribs
return: HTMLForm $this for chaining calls (since 1.20)

setTokenSalt( $salt ) X-Ref

Set the salt for the edit token.

Only useful when the method is "post".

param: string|array $salt Salt to use
return: HTMLForm $this For chaining calls

displayForm( $submitResult ) X-Ref

Display the form (sending to the context's OutputPage object), with an
appropriate error message or stack of messages, and any validation errors, etc.

param: bool|string|array|Status $submitResult Output from HTMLForm::trySubmit()
return: void Nothing, should be last call

getHTML( $submitResult ) X-Ref

Returns the raw HTML generated by the form

param: bool|string|array|Status $submitResult Output from HTMLForm::trySubmit()
return: string

wrapForm( $html ) X-Ref

Wrap the form innards in an actual "<form>" element

param: string $html HTML contents to wrap.
return: string Wrapped HTML.

getHiddenFields() X-Ref

Get the hidden fields that should go inside the form.

return: string HTML.

getButtons() X-Ref

Get the submit and (potentially) reset buttons.

return: string HTML.

getBody() X-Ref

Get the whole body of the form.

return: string

getErrors( $errors ) X-Ref

Format and display an error message stack.

param: string|array|Status $errors
return: string

formatErrors( $errors ) X-Ref

Format a stack of error messages into a single HTML string

param: array $errors Array of message keys/values
return: string HTML, a "<ul>" list of errors

setSubmitText( $t ) X-Ref

Set the text for the submit button

param: string $t Plaintext
return: HTMLForm $this for chaining calls (since 1.20)

setSubmitDestructive() X-Ref

Identify that the submit button in the form has a destructive action

setSubmitTextMsg( $msg ) X-Ref

Set the text for the submit button to a message

param: string|Message $msg Message key or Message object
return: HTMLForm $this for chaining calls (since 1.20)

getSubmitText() X-Ref

Get the text for the submit button, either customised or a default.

return: string

setSubmitName( $name ) X-Ref

param: string $name Submit button name
return: HTMLForm $this for chaining calls (since 1.20)

setSubmitTooltip( $name ) X-Ref

param: string $name Tooltip for the submit button
return: HTMLForm $this for chaining calls (since 1.20)

setSubmitID( $t ) X-Ref

Set the id for the submit button.

param: string $t
return: HTMLForm $this for chaining calls (since 1.20)

suppressDefaultSubmit( $suppressSubmit = true ) X-Ref

Stop a default submit button being shown for this form. This implies that an
alternate submit method must be provided manually.

param: bool $suppressSubmit Set to false to re-enable the button again
return: HTMLForm $this for chaining calls

setTableId( $id ) X-Ref

Set the id of the \<table\> or outermost \<div\> element.

param: string $id New value of the id attribute, or "" to remove
return: HTMLForm $this for chaining calls

setId( $id ) X-Ref

param: string $id DOM id for the form
return: HTMLForm $this for chaining calls (since 1.20)

setWrapperLegend( $legend ) X-Ref

Prompt the whole form to be wrapped in a "<fieldset>", with
this text as its "<legend>" element.

param: string|bool $legend HTML to go inside the "<legend>" element, or
return: HTMLForm $this for chaining calls (since 1.20)

setWrapperLegendMsg( $msg ) X-Ref

Prompt the whole form to be wrapped in a "<fieldset>", with
this message as its "<legend>" element.

param: string|Message $msg Message key or Message object
return: HTMLForm $this for chaining calls (since 1.20)

setMessagePrefix( $p ) X-Ref

Set the prefix for various default messages

param: string $p
return: HTMLForm $this for chaining calls (since 1.20)

setTitle( $t ) X-Ref

Set the title for form submission

param: Title $t Title of page the form is on/should be posted to
return: HTMLForm $this for chaining calls (since 1.20)

getTitle() X-Ref

Get the title

return: Title

setMethod( $method = 'post' ) X-Ref

Set the method used to submit the form

param: string $method
return: HTMLForm $this for chaining calls (since 1.20)

getMethod() X-Ref

No description

displaySection( $fields,$sectionName = '',$fieldsetIDPrefix = '',&$hasUserVisibleFields = false ) X-Ref

param: array[]|HTMLFormField[] $fields Array of fields (either arrays or
param: string $sectionName ID attribute of the "<table>" tag for this
param: string $fieldsetIDPrefix ID prefix for the "<fieldset>" tag of
param: bool &$hasUserVisibleFields Whether the section had user-visible fields.
return: string

loadData() X-Ref

Construct the form fields from the Descriptor array

suppressReset( $suppressReset = true ) X-Ref

Stop a reset button being shown for this form

param: bool $suppressReset Set to false to re-enable the button again
return: HTMLForm $this for chaining calls (since 1.20)

filterDataForSubmit( $data ) X-Ref

Overload this if you want to apply special filtration routines
to the form as a whole, after it's submitted but before it's
processed.

param: array $data
return: array

getLegend( $key ) X-Ref

Get a string to go in the "<legend>" of a section fieldset.
Override this if you want something more complicated.

param: string $key
return: string

setAction( $action ) X-Ref

Set the value for the action attribute of the form.
When set to false (which is the default state), the set title is used.

param: string|bool $action
return: HTMLForm $this for chaining calls (since 1.20)

getAction() X-Ref

Get the value for the action attribute of the form.

return: string

File Size:	1472 lines (40 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of MediaWiki-1.24.0

/includes/htmlform/ -> HTMLForm.php (summary)

Defines 1 class