BlueSpice MediaWiki REL1_27
 All Classes Namespaces Files Functions Variables Groups Pages
HTMLForm Class Reference
Inheritance diagram for HTMLForm:
Collaboration diagram for HTMLForm:

Public Member Functions

 __construct ($descriptor, $context=null, $messagePrefix= '')
 
 setDisplayFormat ($format)
 
 getDisplayFormat ()
 
 isVForm ()
 
 prepareForm ()
 
 tryAuthorizedSubmit ()
 
 show ()
 
 showAlways ()
 
 trySubmit ()
 
 wasSubmitted ()
 
 setSubmitCallback ($cb)
 
 setValidationErrorMessage ($msg)
 
 setIntro ($msg)
 
 setPreText ($msg)
 
 addPreText ($msg)
 
 addHeaderText ($msg, $section=null)
 
 setHeaderText ($msg, $section=null)
 
 getHeaderText ($section=null)
 
 addFooterText ($msg, $section=null)
 
 setFooterText ($msg, $section=null)
 
 getFooterText ($section=null)
 
 addPostText ($msg)
 
 setPostText ($msg)
 
 addHiddenField ($name, $value, array $attribs=[])
 
 addHiddenFields (array $fields)
 
 addButton ($data)
 
 setTokenSalt ($salt)
 
 displayForm ($submitResult)
 
 getHTML ($submitResult)
 
 wrapForm ($html)
 
 getHiddenFields ()
 
 getButtons ()
 
 getBody ()
 
 getErrors ($errors)
 
 formatErrors ($errors)
 
 setSubmitText ($t)
 
 setSubmitDestructive ()
 
 setSubmitProgressive ()
 
 setSubmitTextMsg ($msg)
 
 getSubmitText ()
 
 setSubmitName ($name)
 
 setSubmitTooltip ($name)
 
 setSubmitID ($t)
 
 suppressDefaultSubmit ($suppressSubmit=true)
 
 setTableId ($id)
 
 setId ($id)
 
 setName ($name)
 
 setWrapperLegend ($legend)
 
 setWrapperLegendMsg ($msg)
 
 setMessagePrefix ($p)
 
 setTitle ($t)
 
 getTitle ()
 
 setMethod ($method= 'post')
 
 getMethod ()
 
 displaySection ($fields, $sectionName= '', $fieldsetIDPrefix= '', &$hasUserVisibleFields=false)
 
 loadData ()
 
 suppressReset ($suppressReset=true)
 
 filterDataForSubmit ($data)
 
 getLegend ($key)
 
 setAction ($action)
 
 getAction ()
 
 setAutocomplete ($autocomplete)
 
- Public Member Functions inherited from ContextSource
 getContext ()
 
 setContext (IContextSource $context)
 
 getConfig ()
 
 getRequest ()
 
 getTitle ()
 
 canUseWikiPage ()
 
 getWikiPage ()
 
 getOutput ()
 
 getUser ()
 
 getLanguage ()
 
 getSkin ()
 
 getTiming ()
 
 getStats ()
 
 msg ()
 
 exportSession ()
 

Static Public Member Functions

static factory ($displayFormat)
 
static getClassFromDescriptor ($fieldname, &$descriptor)
 
static loadInputFromParameters ($fieldname, $descriptor, HTMLForm $parent=null)
 

Public Attributes

static $mFieldData
 

Static Public Attributes

static $typeMappings
 

Protected Member Functions

 getFormAttributes ()
 
 wrapFieldSetSection ($legend, $section, $attributes)
 
 formatSection (array $fieldsHtml, $sectionName, $anyFieldHasLabel)
 
 getMessage ($value)
 

Protected Attributes

 $mMessagePrefix
 
 $mFlatFields
 
 $mFieldTree
 
 $mShowReset = false
 
 $mShowSubmit = true
 
 $mSubmitFlags = [ 'constructive', 'primary' ]
 
 $mSubmitCallback
 
 $mValidationErrorMessage
 
 $mPre = ''
 
 $mHeader = ''
 
 $mFooter = ''
 
 $mSectionHeaders = []
 
 $mSectionFooters = []
 
 $mPost = ''
 
 $mId
 
 $mName
 
 $mTableId = ''
 
 $mSubmitID
 
 $mSubmitName
 
 $mSubmitText
 
 $mSubmitTooltip
 
 $mTitle
 
 $mMethod = 'post'
 
 $mWasSubmitted = false
 
 $mAction = false
 
 $mAutocomplete = false
 
 $mUseMultipart = false
 
 $mHiddenFields = []
 
 $mButtons = []
 
 $mWrapperLegend = false
 
 $mTokenSalt = ''
 
 $mSubSectionBeforeFields = true
 
 $displayFormat = 'table'
 
 $availableDisplayFormats
 
 $availableSubclassDisplayFormats
 

Detailed Description

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:

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 'dir' – Direction of the element. '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 or object to be parsed to extract the list of options (like 'ipbreason-dropdown'). 'label-message' – message key or object 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 or object 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 keys/objects. 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.

See Also
HTMLFormField::filter() 'validation-callback' – a function name to give you the chance to impose extra validation on the field input.
HTMLFormField::validate() 'name' – By default, the 'name' attribute of the input field is "wp{$fieldname}". If you want a different name (eg one without the "wp" prefix), specify it here and it will be used without modification. 'hide-if' – 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: 'NOT' [ 'NOT', array $expression ] To hide a field if a given expression is not true. '===' [ '===', 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. The expressions will be given to a JavaScript frontend module which will continually update the field's visibility.

Since 1.20, you can chain mutators to ease the form generation:

Example:
$form = new HTMLForm( $someFields );
$form->setMethod( 'get' )
->setWrapperLegendMsg( 'message-key' )
->prepareForm()
->displayForm( '' );
Note that you will have prepareForm and displayForm at the end. Other methods call done after that would simply not be part of the form :(
Todo:
Document 'section' / 'subsection' stuff

Constructor & Destructor Documentation

HTMLForm::__construct (   $descriptor,
  $context = null,
  $messagePrefix = '' 
)

Build a new HTMLForm from an array of field attributes

Parameters
array$descriptorArray of Field constructs, as described above
IContextSource$contextAvailable since 1.18, will become compulsory in 1.18. Obviates the need to call $form->setTitle()
string$messagePrefixA prefix to go in front of default messages

Member Function Documentation

HTMLForm::addButton (   $data)

Add a button to the form

Since
1.27 takes an array as shown. Earlier versions accepted 'name', 'value', 'id', and 'attribs' as separate parameters in that order.
Note
Custom labels ('label', 'label-message', 'label-raw') are not supported for IE6 and IE7 due to bugs in those browsers. If detected, they will be served buttons using 'value' as the button label.
Parameters
array$dataData to define the button:
  • name: (string) Button name.
  • value: (string) Button value.
  • label-message: (string, optional) Button label message key to use instead of 'value'. Overrides 'label' and 'label-raw'.
  • label: (string, optional) Button label text to use instead of 'value'. Overrides 'label-raw'.
  • label-raw: (string, optional) Button label HTML to use instead of 'value'.
  • id: (string, optional) DOM id for the button.
  • attribs: (array, optional) Additional HTML attributes.
  • flags: (string|string[], optional) OOUI flags.
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::addFooterText (   $msg,
  $section = null 
)

Add footer text, inside the form.

Parameters
string$msgComplete text of message to display
string | null$sectionThe section to add the footer text to
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::addHeaderText (   $msg,
  $section = null 
)

Add HTML to the header, inside the form.

Parameters
string$msgAdditional HTML to display in header
string | null$sectionThe section to add the header to
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::addHiddenField (   $name,
  $value,
array  $attribs = [] 
)

Add a hidden field to the output

Parameters
string$nameField name. This will be used exactly as entered
string$valueField value
array$attribs
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::addHiddenFields ( array  $fields)

Add an array of hidden fields to the output

Since
1.22
Parameters
array$fieldsAssociative array of fields to add; mapping names to their values
Returns
HTMLForm $this for chaining calls
HTMLForm::addPostText (   $msg)

Add text to the end of the display.

Parameters
string$msgComplete text of message to display
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::addPreText (   $msg)

Add HTML to introductory message.

Parameters
string$msgComplete HTML of message to display
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::displayForm (   $submitResult)

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

Attention
You should call prepareForm() before calling this function. Moreover, when doing method chaining this should be the very last method call just after prepareForm().
Parameters
bool | string | array | Status$submitResultOutput from HTMLForm::trySubmit()
Returns
void Nothing, should be last call
HTMLForm::displaySection (   $fields,
  $sectionName = '',
  $fieldsetIDPrefix = '',
$hasUserVisibleFields = false 
)
Todo:
Document
Parameters
array[]|HTMLFormField[]$fields Array of fields (either arrays or objects).
string$sectionNameID attribute of the "<table>" tag for this section, ignored if empty.
string$fieldsetIDPrefixID prefix for the "<fieldset>" tag of each subsection, ignored if empty.
bool&$hasUserVisibleFieldsWhether the section had user-visible fields.
Exceptions
LogicExceptionWhen called on uninitialized field data, e.g. When HTMLForm::displayForm was called without calling HTMLForm::prepareForm first.
Returns
string
static HTMLForm::factory (   $displayFormat)
static

Construct a HTMLForm object for given display type. May return a HTMLForm subclass.

Parameters
string$displayFormat
mixed$arguments,...Additional arguments to pass to the constructor.
Returns
HTMLForm
HTMLForm::filterDataForSubmit (   $data)

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.

Parameters
array$data
Returns
array
HTMLForm::formatErrors (   $errors)

Format a stack of error messages into a single HTML string

Parameters
array$errorsArray of message keys/values
Returns
string HTML, a "<ul>" list of errors
HTMLForm::formatSection ( array  $fieldsHtml,
  $sectionName,
  $anyFieldHasLabel 
)
protected

Put a form section together from the individual fields' HTML, merging it and wrapping.

Parameters
array$fieldsHtml
string$sectionName
bool$anyFieldHasLabel
Returns
string HTML
HTMLForm::getAction ( )

Get the value for the action attribute of the form.

Since
1.22
Returns
string
HTMLForm::getBody ( )

Get the whole body of the form.

Returns
string
HTMLForm::getButtons ( )

Get the submit and (potentially) reset buttons.

Returns
string HTML.
static HTMLForm::getClassFromDescriptor (   $fieldname,
$descriptor 
)
static

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.

Since
1.23
Parameters
string$fieldnameName of the field
array$descriptorInput Descriptor, as described above
Exceptions
MWException
Returns
string Name of a HTMLFormField subclass
HTMLForm::getDisplayFormat ( )

Getter for displayFormat

Since
1.20
Returns
string
HTMLForm::getErrors (   $errors)

Format and display an error message stack.

Parameters
string | array | Status$errors
Returns
string
HTMLForm::getFooterText (   $section = null)

Get footer text.

Parameters
string | null$sectionThe section to get the footer text for
Since
1.26
Returns
string
HTMLForm::getFormAttributes ( )
protected

Get HTML attributes for the <form> tag.

Returns
array
HTMLForm::getHeaderText (   $section = null)

Get header text.

Parameters
string | null$sectionThe section to get the header text for
Since
1.26
Returns
string HTML
HTMLForm::getHiddenFields ( )

Get the hidden fields that should go inside the form.

Returns
string HTML.
HTMLForm::getHTML (   $submitResult)

Returns the raw HTML generated by the form

Parameters
bool | string | array | Status$submitResultOutput from HTMLForm::trySubmit()
Returns
string HTML
HTMLForm::getLegend (   $key)

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

Parameters
string$key
Returns
string
HTMLForm::getMessage (   $value)
protected

Turns a *-message parameter (which could be a MessageSpecifier, or a message name, or a name + parameters array) into a Message.

Parameters
mixed$value
Returns
Message
HTMLForm::getMethod ( )
Returns
string Always lowercase
HTMLForm::getSubmitText ( )

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

Returns
string
HTMLForm::getTitle ( )

Get the title

Returns
Title

Implements IContextSource.

HTMLForm::isVForm ( )

Test if displayFormat is 'vform'

Since
1.22
Deprecated:
since 1.25
Returns
bool
HTMLForm::loadData ( )

Construct the form fields from the Descriptor array

static HTMLForm::loadInputFromParameters (   $fieldname,
  $descriptor,
HTMLForm  $parent = null 
)
static

Initialise a new Object for the field

Parameters
string$fieldnameName of the field
array$descriptorInput Descriptor, as described above
HTMLForm | null$parentParent instance of HTMLForm
Exceptions
MWException
Returns
HTMLFormField Instance of a subclass of HTMLFormField
HTMLForm::prepareForm ( )

Prepare form for submission.

Attention
When doing method chaining, that should be the very last method call before displayForm().
Exceptions
MWException
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setAction (   $action)

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

Since
1.19
Parameters
string | bool$action
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setAutocomplete (   $autocomplete)

Set the value for the autocomplete attribute of the form. When set to false (which is the default state), the attribute get not set.

Since
1.27
Parameters
string | bool$autocomplete
Returns
HTMLForm $this for chaining calls
HTMLForm::setDisplayFormat (   $format)

Set format in which to display the form

Parameters
string$formatThe name of the format to use, must be one of $this->availableDisplayFormats
Exceptions
MWException
Since
1.20
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setFooterText (   $msg,
  $section = null 
)

Set footer text, inside the form.

Since
1.19
Parameters
string$msgComplete text of message to display
string | null$sectionThe section to add the footer text to
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setHeaderText (   $msg,
  $section = null 
)

Set header text, inside the form.

Since
1.19
Parameters
string$msgComplete HTML of header to display
string | null$sectionThe section to add the header to
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setId (   $id)
Parameters
string$idDOM id for the form
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setIntro (   $msg)

Set the introductory message, overwriting any existing message.

Parameters
string$msgComplete text of message to display
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setMessagePrefix (   $p)

Set the prefix for various default messages

Todo:
Currently only used for the "<fieldset>" legend on forms with multiple sections; should be used elsewhere?
Parameters
string$p
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setMethod (   $method = 'post')

Set the method used to submit the form

Parameters
string$method
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setName (   $name)
Parameters
string$name'name' attribute for the form
Returns
HTMLForm $this for chaining calls
HTMLForm::setPostText (   $msg)

Set text at the end of the display.

Parameters
string$msgComplete text of message to display
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setPreText (   $msg)

Set the introductory message HTML, overwriting any existing message.

Since
1.19
Parameters
string$msgComplete HTML of message to display
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitCallback (   $cb)

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

Parameters
callable$cbThe function will be passed the output from HTMLForm::filterDataForSubmit and this HTMLForm object, and must return as documented for HTMLForm::trySubmit
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitDestructive ( )

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

Since
1.24
HTMLForm::setSubmitID (   $t)

Set the id for the submit button.

Parameters
string$t
Todo:
FIXME: Integrity of $t is not validated
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitName (   $name)
Parameters
string$nameSubmit button name
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitProgressive ( )

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

Since
1.25
HTMLForm::setSubmitText (   $t)

Set the text for the submit button

Parameters
string$tPlaintext
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitTextMsg (   $msg)

Set the text for the submit button to a message

Since
1.19
Parameters
string | Message$msgMessage key or Message object
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setSubmitTooltip (   $name)
Parameters
string$nameTooltip for the submit button
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setTableId (   $id)

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

Since
1.22
Parameters
string$idNew value of the id attribute, or "" to remove
Returns
HTMLForm $this for chaining calls
HTMLForm::setTitle (   $t)

Set the title for form submission

Parameters
Title$tTitle of page the form is on/should be posted to
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setTokenSalt (   $salt)

Set the salt for the edit token.

Only useful when the method is "post".

Since
1.24
Parameters
string | array$saltSalt to use
Returns
HTMLForm $this For chaining calls
HTMLForm::setValidationErrorMessage (   $msg)

Set a message to display on a validation error.

Parameters
string | array$msgString or Array of valid inputs to wfMessage() (so each entry can be either a String or Array)
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setWrapperLegend (   $legend)

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

Parameters
string | bool$legendIf false, no wrapper or legend will be displayed. If true, a wrapper will be displayed, but no legend. If a string, a wrapper will be displayed with that string as a legend. The string will be escaped before being output (this doesn't support HTML).
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::setWrapperLegendMsg (   $msg)

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

Since
1.19
Parameters
string | Message$msgMessage key or Message object
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::show ( )

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

Returns
bool|Status Whether submission was successful.
HTMLForm::showAlways ( )

Same as self::show with the difference, that the form will be added to the output, no matter, if the validation was good or not.

Returns
bool|Status Whether submission was successful.
HTMLForm::suppressDefaultSubmit (   $suppressSubmit = true)

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

Since
1.22
Parameters
bool$suppressSubmitSet to false to re-enable the button again
Returns
HTMLForm $this for chaining calls
HTMLForm::suppressReset (   $suppressReset = true)

Stop a reset button being shown for this form

Parameters
bool$suppressResetSet to false to re-enable the button again
Returns
HTMLForm $this for chaining calls (since 1.20)
HTMLForm::tryAuthorizedSubmit ( )

Try submitting, with edit token check first

Returns
Status|bool
HTMLForm::trySubmit ( )

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

Exceptions
MWException
Returns
bool|string|array|Status
  • Bool true or a good Status object indicates success,
  • Bool false indicates no submission was attempted,
  • Anything else indicates failure. The value may be a fatal Status object, an HTML string, or an array of arrays (message keys and params) or strings (message keys)
HTMLForm::wasSubmitted ( )

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.

Since
1.23
Returns
bool
HTMLForm::wrapFieldSetSection (   $legend,
  $section,
  $attributes 
)
protected

Wraps the given $section into an user-visible fieldset.

Parameters
string$legendLegend text for the fieldset
string$sectionThe section content in plain Html
array$attributesAdditional attributes for the fieldset
Returns
string The fieldset's Html
HTMLForm::wrapForm (   $html)

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

Parameters
string$htmlHTML contents to wrap.
Returns
string Wrapped HTML.

Member Data Documentation

HTMLForm::$availableDisplayFormats
protected
Initial value:
= [
'table',
'div',
'raw',
'inline',
]
HTMLForm::$availableSubclassDisplayFormats
protected
Initial value:
= [
'vform',
'ooui',
]
HTMLForm::$mSubSectionBeforeFields = true
protected

If true, sections that contain both fields and subsections will render their subsections before their fields.

Subclasses may set this to false to render subsections after fields instead.

HTMLForm::$typeMappings
static
Initial value:
= [
'api' => 'HTMLApiField'

The documentation for this class was generated from the following file: