From 5e8e2d76fe515286e07d77c994c3c72078586aa3 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Tue, 24 Jul 2012 11:45:22 +0200 Subject: [PATCH] HTMLForm mutators can now be chained This make HTMLForm mutator to return $this for easy method chaining such as: form = new HTMLForm( $someFields ); $form->setMethod( 'get' ) ->setWrapperLegendMsg( 'message-key' ) ->suppressReset() ->prepareForm() ->displayForm(); prepareForm()->displayForm(); should be at the very end apparently though it is not enforced by the object. Change-Id: Iebaa83a1da3c89e5ab729a889e54844535619d54 --- RELEASE-NOTES-1.20 | 1 + includes/HTMLForm.php | 117 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 112 insertions(+), 6 deletions(-) diff --git a/RELEASE-NOTES-1.20 b/RELEASE-NOTES-1.20 index 1b1cd97d71..df7568d7b3 100644 --- a/RELEASE-NOTES-1.20 +++ b/RELEASE-NOTES-1.20 @@ -110,6 +110,7 @@ upgrade PHP if you have not done so prior to upgrading MediaWiki. * Implemented mw.user.getGroups for getting and caching user groups. * (bug 37830) Added $wgRequirePasswordforEmailChange to control whether password confirmation is required for changing an email address or not. +* HTMLForm mutators can now be chained (they return $this) === Bug fixes in 1.20 === * (bug 30245) Use the correct way to construct a log page title. diff --git a/includes/HTMLForm.php b/includes/HTMLForm.php index 38b15b9e47..6e9548db50 100644 --- a/includes/HTMLForm.php +++ b/includes/HTMLForm.php @@ -73,6 +73,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 { @@ -232,12 +245,14 @@ class HTMLForm extends ContextSource { * @param $format String the name of the format to use, must be one of * $this->availableDisplayFormats * @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; } /** @@ -288,7 +303,12 @@ 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(). + * + * @return HTMLForm $this for chaining calls (since 1.20) */ function prepareForm() { # Check if we have the info we need @@ -298,6 +318,7 @@ class HTMLForm extends ContextSource { # Load data from the request. $this->loadData(); + return $this; } /** @@ -390,45 +411,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() * (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 +475,7 @@ class HTMLForm extends ContextSource { } $this->mSectionHeaders[$section] .= $msg; } + return $this; } /** @@ -446,6 +483,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 +491,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 +509,7 @@ class HTMLForm extends ContextSource { } $this->mSectionFooters[$section] .= $msg; } + return $this; } /** @@ -476,6 +517,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 +525,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 ) ); @@ -716,18 +784,22 @@ class HTMLForm extends ContextSource { /** * Set the text for the submit button * @param $t String plaintext. + * @return HTMLForm $this for chaining calls (since 1.20) */ function setSubmitText( $t ) { $this->mSubmitText = $t; + return $this; } /** * Set the text for the submit button to a message * @since 1.19 * @param $msg String message key + * @return HTMLForm $this for chaining calls (since 1.20) */ public function setSubmitTextMsg( $msg ) { $this->setSubmitText( $this->msg( $msg )->text() ); + return $this; } /** @@ -740,42 +812,65 @@ class HTMLForm extends ContextSource { : wfMsg( 'htmlform-submit' ); } + /** + * @param $name String Submit button name + * @return HTMLForm $this for chaining calls (since 1.20) + */ public function setSubmitName( $name ) { $this->mSubmitName = $name; + return $this; } + /** + * @param $name String Tooltip for the submit button + * @return HTMLForm $this for chaining calls (since 1.20) + */ public function setSubmitTooltip( $name ) { $this->mSubmitTooltip = $name; + return $this; } /** * Set the id for the submit button. * @param $t String. * @todo FIXME: Integrity of $t is *not* validated + * @return HTMLForm $this for chaining calls (since 1.20) */ function setSubmitID( $t ) { $this->mSubmitID = $t; + return $this; } + /** + * @param $id String DOM id for the form + * @return HTMLForm $this for chaining calls (since 1.20) + */ public function setId( $id ) { $this->mId = $id; + return $this; } /** * Prompt the whole form to be wrapped in a "
", with * this text as its "" element. * @param $legend String HTML to go inside the "" element. * Will be escaped + * @return HTMLForm $this for chaining calls (since 1.20) */ - public function setWrapperLegend( $legend ) { $this->mWrapperLegend = $legend; } + public function setWrapperLegend( $legend ) { + $this->mWrapperLegend = $legend; + return $this; + } /** * Prompt the whole form to be wrapped in a "
", with * this message as its "" element. * @since 1.19 * @param $msg String message key + * @return HTMLForm $this for chaining calls (since 1.20) */ public function setWrapperLegendMsg( $msg ) { $this->setWrapperLegend( $this->msg( $msg )->escaped() ); + return $this; } /** @@ -783,17 +878,21 @@ class HTMLForm extends ContextSource { * @todo currently only used for the "
" legend on forms * with multiple sections; should be used elsewhre? * @param $p String + * @return HTMLForm $this for chaining calls (since 1.20) */ function setMessagePrefix( $p ) { $this->mMessagePrefix = $p; + return $this; } /** * Set the title for form submission * @param $t Title of page the form is on/should be posted to + * @return HTMLForm $this for chaining calls (since 1.20) */ function setTitle( $t ) { $this->mTitle = $t; + return $this; } /** @@ -809,9 +908,11 @@ class HTMLForm extends ContextSource { /** * Set the method used to submit the form * @param $method String + * @return HTMLForm $this for chaining calls (since 1.20) */ public function setMethod( $method = 'post' ) { $this->mMethod = $method; + return $this; } public function getMethod() { @@ -921,9 +1022,11 @@ class HTMLForm extends ContextSource { * Stop a reset button being shown for this form * @param $suppressReset Bool set to false to re-enable the * button again + * @return HTMLForm $this for chaining calls (since 1.20) */ function suppressReset( $suppressReset = true ) { $this->mShowReset = !$suppressReset; + return $this; } /** @@ -954,9 +1057,11 @@ class HTMLForm extends ContextSource { * @since 1.19 * * @param string|bool $action + * @return HTMLForm $this for chaining calls (since 1.20) */ public function setAction( $action ) { $this->mAction = $action; + return $this; } } -- 2.20.1