'hidden' => 'HTMLHiddenField',
'edittools' => 'HTMLEditTools',
'checkmatrix' => 'HTMLCheckMatrix',
+ 'cloner' => 'HTMLFormFieldCloner',
// HTMLTextField will output the correct type="" attribute automagically.
// There are about four zillion other HTML5 input types, like range, but
// we don't use those at the moment, so no point in adding all of them.
protected $mTitle;
protected $mMethod = 'post';
+ protected $mWasSubmitted = false;
/**
* Form action URL. false means we will use the URL to set Title
/**
* Format in which to display form. For viable options,
* @see $availableDisplayFormats
- * @var String
+ * @var string
*/
protected $displayFormat = 'table';
/**
* Available formats in which to display the form
- * @var Array
+ * @var array
*/
protected $availableDisplayFormats = array(
'table',
/**
* Build a new HTMLForm from an array of field attributes
*
- * @param array $descriptor of Field constructs, as described above
- * @param $context IContextSource available since 1.18, will become compulsory in 1.18.
+ * @param array $descriptor Array of Field constructs, as described above
+ * @param IContextSource $context Available since 1.18, will become compulsory in 1.18.
* Obviates the need to call $form->setTitle()
- * @param string $messagePrefix a prefix to go in front of default messages
+ * @param string $messagePrefix A prefix to go in front of default messages
*/
public function __construct( $descriptor, /*IContextSource*/ $context = null,
$messagePrefix = ''
/**
* Set format in which to display the form
*
- * @param string $format the name of the format to use, must be one of
- * $this->availableDisplayFormats
+ * @param string $format The name of the format to use, must be one of
+ * $this->availableDisplayFormats
*
* @throws MWException
* @since 1.20
/**
* Getter for displayFormat
* @since 1.20
- * @return String
+ * @return string
*/
public function getDisplayFormat() {
return $this->displayFormat;
/**
* Test if displayFormat is 'vform'
* @since 1.22
- * @return Bool
+ * @return bool
*/
public function isVForm() {
return $this->displayFormat === 'vform';
}
if ( !$class ) {
- throw new MWException( "Descriptor with no class for $fieldname: " . print_r( $descriptor, true ) );
+ throw new MWException( "Descriptor with no class for $fieldname: "
+ . print_r( $descriptor, true ) );
}
+
return $class;
}
/**
* Try submitting, with edit token check first
- * @return Status|boolean
+ * @return Status|bool
*/
function tryAuthorizedSubmit() {
$result = false;
}
if ( $submit ) {
+ $this->mWasSubmitted = true;
$result = $this->trySubmit();
}
* 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 or Status whether submission was successful.
+ * @return bool|Status Whether submission was successful.
*/
function show() {
$this->prepareForm();
* Validate all the fields, and call the submission callback
* function if everything is kosher.
* @throws MWException
- * @return Mixed Bool true == Successful submission, Bool false
+ * @return mixed Bool true == Successful submission, Bool false
* == No submission attempted, anything else == Error to
* display.
*/
function trySubmit() {
+ $this->mWasSubmitted = true;
+
+ # Check for cancelled submission
+ foreach ( $this->mFlatFields as $fieldname => $field ) {
+ if ( !empty( $field->mParams['nodata'] ) ) {
+ continue;
+ }
+ if ( $field->cancelSubmit( $this->mFieldData[$fieldname], $this->mFieldData ) ) {
+ $this->mWasSubmitted = false;
+ return false;
+ }
+ }
+
# Check for validation
foreach ( $this->mFlatFields as $fieldname => $field ) {
if ( !empty( $field->mParams['nodata'] ) ) {
$data = $this->filterDataForSubmit( $this->mFieldData );
$res = call_user_func( $callback, $data, $this );
+ if ( $res === false ) {
+ $this->mWasSubmitted = false;
+ }
return $res;
}
+ /**
+ * 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
+ * @return bool
+ */
+ function wasSubmitted() {
+ return $this->mWasSubmitted;
+ }
+
/**
* Set a callback to a function to do something with the form
* once it's been successfully validated.
*
- * @param string $cb function name. The function will be passed
+ * @param string $cb Function name. The function will be passed
* 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.
/**
* Set a message to display on a validation error.
*
- * @param $msg Mixed String or Array of valid inputs to wfMessage()
+ * @param string|array $msg 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)
/**
* Set the introductory message, overwriting any existing message.
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* Set the introductory message, overwriting any existing message.
* @since 1.19
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Add introductory text.
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Add header text, inside the form.
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
* @param string $section The section to add the header to
*
* @return HTMLForm $this for chaining calls (since 1.20)
* Set header text, inside the form.
* @since 1.19
*
- * @param string $msg complete text of message to display
- * @param $section The section to add the header to
+ * @param string $msg Complete text of message to display
+ * @param string $section The section to add the header to
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* Set footer text, inside the form.
* @since 1.19
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
* @param string $section The section to add the footer text to
*
* @return HTMLForm $this for chaining calls (since 1.20)
/**
* Add text to the end of the display.
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Set text at the end of the display.
*
- * @param string $msg complete text of message to display
+ * @param string $msg Complete text of message to display
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* 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 $attribs Array
+ * @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)
*/
/**
* Add a button to the form
*
- * @param string $name field name.
- * @param string $value field value
+ * @param string $name Field name.
+ * @param string $value Field value
* @param string $id DOM id for the button (default: null)
- * @param $attribs Array
+ * @param array $attribs
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* Moreover, when doing method chaining this should be the very last method
* call just after prepareForm().
*
- * @param $submitResult Mixed output from HTMLForm::trySubmit()
+ * @param mixed $submitResult Mixed output from HTMLForm::trySubmit()
*
* @return Nothing, should be last call
*/
/**
* Returns the raw HTML generated by the form
*
- * @param $submitResult Mixed output from HTMLForm::trySubmit()
+ * @param mixed $submitResult Mixed output from HTMLForm::trySubmit()
*
* @return string
*/
*
* @param string $html HTML contents to wrap.
*
- * @return String wrapped HTML.
+ * @return string Wrapped HTML.
*/
function wrapForm( $html ) {
/**
* Get the hidden fields that should go inside the form.
- * @return String HTML.
+ * @return string HTML.
*/
function getHiddenFields() {
global $wgArticlePath;
/**
* Get the submit and (potentially) reset buttons.
- * @return String HTML.
+ * @return string HTML.
*/
function getButtons() {
$buttons = '';
/**
* Get the whole body of the form.
- * @return String
+ * @return string
*/
function getBody() {
return $this->displaySection( $this->mFieldTree, $this->mTableId );
/**
* Format and display an error message stack.
*
- * @param $errors String|Array|Status
+ * @param string|array|Status $errors
*
- * @return String
+ * @return string
*/
function getErrors( $errors ) {
if ( $errors instanceof Status ) {
*
* @param array $errors of message keys/values
*
- * @return String HTML, a "<ul>" list of errors
+ * @return string HTML, a "<ul>" list of errors
*/
public static function formatErrors( $errors ) {
$errorstr = '';
* Set the text for the submit button to a message
* @since 1.19
*
- * @param string $msg message key
+ * @param string $msg Message key
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Set the id for the submit button.
*
- * @param $t String.
+ * @param string $t
*
* @todo FIXME: Integrity of $t is *not* validated
* @return HTMLForm $this for chaining calls (since 1.20)
*
* @since 1.22
*
- * @param string $id new value of the id attribute, or "" to remove
+ * @param string $id New value of the id attribute, or "" to remove
*
* @return HTMLForm $this for chaining calls
*/
* Prompt the whole form to be wrapped in a "<fieldset>", with
* this text as its "<legend>" element.
*
- * @param string|false $legend HTML to go inside the "<legend>" element, or
+ * @param string|bool $legend HTML to go inside the "<legend>" element, or
* false for no <legend>
* Will be escaped
*
* this message as its "<legend>" element.
* @since 1.19
*
- * @param string $msg message key
+ * @param string $msg Message key
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* @todo Currently only used for the "<fieldset>" legend on forms
* with multiple sections; should be used elsewhere?
*
- * @param $p String
+ * @param string $p
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Set the title for form submission
*
- * @param $t Title of page the form is on/should be posted to
+ * @param Title $t Title of page the form is on/should be posted to
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
/**
* Set the method used to submit the form
*
- * @param $method String
+ * @param string $method
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* section, ignored if empty.
* @param string $fieldsetIDPrefix ID prefix for the "<fieldset>" tag of
* each subsection, ignored if empty.
- * @param boolean &$hasUserVisibleFields Whether the section had user-visible fields.
+ * @param bool &$hasUserVisibleFields Whether the section had user-visible fields.
*
- * @return String
+ * @return string
*/
public function displaySection( $fields,
$sectionName = '',
/**
* Stop a reset button being shown for this form
*
- * @param bool $suppressReset set to false to re-enable the
- * button again
+ * @param bool $suppressReset Set to false to re-enable the button again
*
* @return HTMLForm $this for chaining calls (since 1.20)
*/
* to the form as a whole, after it's submitted but before it's
* processed.
*
- * @param $data
+ * @param array $data
*
* @return
*/
* Get a string to go in the "<legend>" of a section fieldset.
* Override this if you want something more complicated.
*
- * @param $key String
+ * @param string $key
*
- * @return String
+ * @return string
*/
public function getLegend( $key ) {
return $this->msg( "{$this->mMessagePrefix}-$key" )->text();