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
list of errors
+ * @return String HTML, a "
" list of errors
*/
public static function formatErrors( $errors ) {
$errorstr = '';
@@ -704,7 +780,7 @@ class HTMLForm extends ContextSource {
$errorstr .= Html::rawElement(
'li',
array(),
- wfMsgExt( $msg, array( 'parseinline' ), $error )
+ wfMessage( $msg, $error )->parse()
);
}
@@ -716,18 +792,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;
}
/**
@@ -737,45 +817,68 @@ class HTMLForm extends ContextSource {
function getSubmitText() {
return $this->mSubmitText
? $this->mSubmitText
- : wfMsg( 'htmlform-submit' );
+ : $this->msg( 'htmlform-submit' )->text();
}
+ /**
+ * @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 "