includes/actions/FormAction.php

   1 <?php
   2 /**
   3  * Base classes for actions done on pages.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  18  *
  19  * @file
  20  * @ingroup Actions
  21  */
  22
  23 /**
  24  * An action which shows a form and does something based on the input from the form
  25  *
  26  * @ingroup Actions
  27  */
  28 abstract class FormAction extends Action {
  29
  30         /**
  31          * Get an HTMLForm descriptor array
  32          * @return array
  33          */
  34         protected function getFormFields() {
  35                 // Default to an empty form with just a submit button
  36                 return [];
  37         }
  38
  39         /**
  40          * Add pre- or post-text to the form
  41          * @return string HTML which will be sent to $form->addPreText()
  42          */
  43         protected function preText() {
  44                 return '';
  45         }
  46
  47         /**
  48          * @return string
  49          */
  50         protected function postText() {
  51                 return '';
  52         }
  53
  54         /**
  55          * Play with the HTMLForm if you need to more substantially
  56          * @param HTMLForm $form
  57          */
  58         protected function alterForm( HTMLForm $form ) {
  59         }
  60
  61         /**
  62          * Whether the form should use OOUI
  63          * @return bool
  64          */
  65         protected function usesOOUI() {
  66                 return false;
  67         }
  68
  69         /**
  70          * Get the HTMLForm to control behavior
  71          * @return HTMLForm|null
  72          */
  73         protected function getForm() {
  74                 $this->fields = $this->getFormFields();
  75
  76                 // Give hooks a chance to alter the form, adding extra fields or text etc
  77                 Hooks::run( 'ActionModifyFormFields', [ $this->getName(), &$this->fields, $this->page ] );
  78
  79                 if ( $this->usesOOUI() ) {
  80                         $form = HTMLForm::factory( 'ooui', $this->fields, $this->getContext(), $this->getName() );
  81                 } else {
  82                         $form = new HTMLForm( $this->fields, $this->getContext(), $this->getName() );
  83                 }
  84                 $form->setSubmitCallback( [ $this, 'onSubmit' ] );
  85
  86                 $title = $this->getTitle();
  87                 $form->setAction( $title->getLocalURL( [ 'action' => $this->getName() ] ) );
  88                 // Retain query parameters (uselang etc)
  89                 $params = array_diff_key(
  90                         $this->getRequest()->getQueryValues(),
  91                         [ 'action' => null, 'title' => null ]
  92                 );
  93                 if ( $params ) {
  94                         $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
  95                 }
  96
  97                 $form->addPreText( $this->preText() );
  98                 $form->addPostText( $this->postText() );
  99                 $this->alterForm( $form );
 100
 101                 // Give hooks a chance to alter the form, adding extra fields or text etc
 102                 Hooks::run( 'ActionBeforeFormDisplay', [ $this->getName(), &$form, $this->page ] );
 103
 104                 return $form;
 105         }
 106
 107         /**
 108          * Process the form on POST submission.
 109          *
 110          * If you don't want to do anything with the form, just return false here.
 111          *
 112          * This method will be passed to the HTMLForm as a submit callback (see
 113          * HTMLForm::setSubmitCallback) and must return as documented for HTMLForm::trySubmit.
 114          *
 115          * @see HTMLForm::setSubmitCallback()
 116          * @see HTMLForm::trySubmit()
 117          * @param array $data
 118          * @return bool|string|array|Status Must return as documented for HTMLForm::trySubmit
 119          */
 120         abstract public function onSubmit( $data );
 121
 122         /**
 123          * Do something exciting on successful processing of the form.  This might be to show
 124          * a confirmation message (watch, rollback, etc) or to redirect somewhere else (edit,
 125          * protect, etc).
 126          */
 127         abstract public function onSuccess();
 128
 129         /**
 130          * The basic pattern for actions is to display some sort of HTMLForm UI, maybe with
 131          * some stuff underneath (history etc); to do some processing on submission of that
 132          * form (delete, protect, etc) and to do something exciting on 'success', be that
 133          * display something new or redirect to somewhere.  Some actions have more exotic
 134          * behavior, but that's what subclassing is for :D
 135          */
 136         public function show() {
 137                 $this->setHeaders();
 138
 139                 // This will throw exceptions if there's a problem
 140                 $this->checkCanExecute( $this->getUser() );
 141
 142                 $form = $this->getForm();
 143                 if ( $form->show() ) {
 144                         $this->onSuccess();
 145                 }
 146         }
 147
 148         public function doesWrites() {
 149                 return true;
 150         }
 151 }