X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2FHTMLForm.php;h=ef24b62b26eb9cda1ffc6abb1b514a0e5528f2ce;hb=bc77c6376f7833b575e95792e1574ea48165b91b;hp=9ced19e993740afad9050c40e1cf30075fd16011;hpb=c21843e256be776bea6cdea3b58bf25b01b0c7da;p=lhc%2Fweb%2Fwiklou.git diff --git a/includes/HTMLForm.php b/includes/HTMLForm.php index 9ced19e993..ef24b62b26 100644 --- a/includes/HTMLForm.php +++ b/includes/HTMLForm.php @@ -34,6 +34,10 @@ * 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: + * - http://www.mediawiki.org/wiki/HTMLForm + * - http://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: * @@ -73,6 +77,19 @@ * (eg one without the "wp" prefix), specify it here and * it will be used without modification. * + * Since 1.20, you can chain mutators to ease the form generation: + * @par Example: + * @code + * $form = new HTMLForm( $someFields ); + * $form->setMethod( 'get' ) + * ->setWrapperLegendMsg( 'message-key' ) + * ->suppressReset() + * ->prepareForm() + * ->displayForm(); + * @endcode + * 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 */ class HTMLForm extends ContextSource { @@ -231,13 +248,16 @@ class HTMLForm extends ContextSource { * Set format in which to display the form * @param $format String the name of the format to use, must be one of * $this->availableDisplayFormats + * @throws MWException * @since 1.20 + * @return HTMLForm $this for chaining calls (since 1.20) */ public function setDisplayFormat( $format ) { if ( !in_array( $format, $this->availableDisplayFormats ) ) { throw new MWException ( 'Display format must be one of ' . print_r( $this->availableDisplayFormats, true ) ); } $this->displayFormat = $format; + return $this; } /** @@ -260,6 +280,7 @@ class HTMLForm extends ContextSource { * Initialise a new Object for the field * @param $fieldname string * @param $descriptor string input Descriptor, as described above + * @throws MWException * @return HTMLFormField subclass */ static function loadInputFromParameters( $fieldname, $descriptor ) { @@ -288,7 +309,13 @@ class HTMLForm extends ContextSource { } /** - * Prepare form for submission + * Prepare form for submission. + * + * @attention When doing method chaining, that should be the very last + * method call before displayForm(). + * + * @throws MWException + * @return HTMLForm $this for chaining calls (since 1.20) */ function prepareForm() { # Check if we have the info we need @@ -298,6 +325,7 @@ class HTMLForm extends ContextSource { # Load data from the request. $this->loadData(); + return $this; } /** @@ -350,9 +378,10 @@ class HTMLForm extends ContextSource { /** * Validate all the fields, and call the submision callback * function if everything is kosher. + * @throws MWException * @return Mixed Bool true == Successful submission, Bool false - * == No submission attempted, anything else == Error to - * display. + * == No submission attempted, anything else == Error to + * display. */ function trySubmit() { # Check for validation @@ -390,45 +419,60 @@ class HTMLForm extends ContextSource { * the output from HTMLForm::filterDataForSubmit, and must * return Bool true on success, Bool false if no submission * was attempted, or String HTML output to display on error. + * @return HTMLForm $this for chaining calls (since 1.20) */ function setSubmitCallback( $cb ) { $this->mSubmitCallback = $cb; + return $this; } /** * Set a message to display on a validation error. - * @param $msg Mixed String or Array of valid inputs to wfMsgExt() + * @param $msg Mixed String or Array of valid inputs to wfMessage() * (so each entry can be either a String or Array) + * @return HTMLForm $this for chaining calls (since 1.20) */ function setValidationErrorMessage( $msg ) { $this->mValidationErrorMessage = $msg; + return $this; } /** * Set the introductory message, overwriting any existing message. * @param $msg String complete text of message to display + * @return HTMLForm $this for chaining calls (since 1.20) */ function setIntro( $msg ) { $this->setPreText( $msg ); + return $this; } /** * Set the introductory message, overwriting any existing message. * @since 1.19 * @param $msg String complete text of message to display + * @return HTMLForm $this for chaining calls (since 1.20) */ - function setPreText( $msg ) { $this->mPre = $msg; } + function setPreText( $msg ) { + $this->mPre = $msg; + return $this; + } /** * Add introductory text. * @param $msg String complete text of message to display + * @return HTMLForm $this for chaining calls (since 1.20) */ - function addPreText( $msg ) { $this->mPre .= $msg; } + function addPreText( $msg ) { + $this->mPre .= $msg; + return $this; + } /** * Add header text, inside the form. * @param $msg String complete text of message to display * @param $section string The section to add the header to + * @return HTMLForm $this for chaining calls (since 1.20) */ function addHeaderText( $msg, $section = null ) { if ( is_null( $section ) ) { @@ -439,6 +483,7 @@ class HTMLForm extends ContextSource { } $this->mSectionHeaders[$section] .= $msg; } + return $this; } /** @@ -446,6 +491,7 @@ class HTMLForm extends ContextSource { * @since 1.19 * @param $msg String complete text of message to display * @param $section The section to add the header to + * @return HTMLForm $this for chaining calls (since 1.20) */ function setHeaderText( $msg, $section = null ) { if ( is_null( $section ) ) { @@ -453,12 +499,14 @@ class HTMLForm extends ContextSource { } else { $this->mSectionHeaders[$section] = $msg; } + return $this; } /** * Add footer text, inside the form. * @param $msg String complete text of message to display * @param $section string The section to add the footer text to + * @return HTMLForm $this for chaining calls (since 1.20) */ function addFooterText( $msg, $section = null ) { if ( is_null( $section ) ) { @@ -469,6 +517,7 @@ class HTMLForm extends ContextSource { } $this->mSectionFooters[$section] .= $msg; } + return $this; } /** @@ -476,6 +525,7 @@ class HTMLForm extends ContextSource { * @since 1.19 * @param $msg String complete text of message to display * @param $section string The section to add the footer text to + * @return HTMLForm $this for chaining calls (since 1.20) */ function setFooterText( $msg, $section = null ) { if ( is_null( $section ) ) { @@ -483,39 +533,65 @@ class HTMLForm extends ContextSource { } else { $this->mSectionFooters[$section] = $msg; } + return $this; } /** * Add text to the end of the display. * @param $msg String complete text of message to display + * @return HTMLForm $this for chaining calls (since 1.20) */ - function addPostText( $msg ) { $this->mPost .= $msg; } + function addPostText( $msg ) { + $this->mPost .= $msg; + return $this; + } /** * Set text at the end of the display. * @param $msg String complete text of message to display + * @return HTMLForm $this for chaining calls (since 1.20) */ - function setPostText( $msg ) { $this->mPost = $msg; } + function setPostText( $msg ) { + $this->mPost = $msg; + return $this; + } /** * Add a hidden field to the output * @param $name String field name. This will be used exactly as entered * @param $value String field value * @param $attribs Array + * @return HTMLForm $this for chaining calls (since 1.20) */ public function addHiddenField( $name, $value, $attribs = array() ) { $attribs += array( 'name' => $name ); $this->mHiddenFields[] = array( $value, $attribs ); + return $this; } + /** + * Add a button to the form + * @param $name String field name. + * @param $value String field value + * @param $id String DOM id for the button (default: null) + * @param $attribs Array + * @return HTMLForm $this for chaining calls (since 1.20) + */ public function addButton( $name, $value, $id = null, $attribs = null ) { $this->mButtons[] = compact( 'name', 'value', 'id', 'attribs' ); + return $this; } /** * Display the form (sending to $wgOut), 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(). + * * @param $submitResult Mixed output from HTMLForm::trySubmit() + * @return Nothing, should be last call */ function displayForm( $submitResult ) { $this->getOutput()->addHTML( $this->getHTML( $submitResult ) ); @@ -628,7 +704,7 @@ class HTMLForm extends ContextSource { 'input', array( 'type' => 'reset', - 'value' => wfMsg( 'htmlform-reset' ) + 'value' => $this->msg( 'htmlform-reset' )->text() ) ) . "\n"; } @@ -688,7 +764,7 @@ class HTMLForm extends ContextSource { /** * Format a stack of error messages into a single HTML string * @param $errors Array of message keys/values - * @return String HTML, a