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          * Get the HTMLForm to control behavior
  63          * @return HTMLForm|null
  64          */
  65         protected function getForm() {
  66                 $this->fields = $this->getFormFields();
  67
  68                 // Give hooks a chance to alter the form, adding extra fields or text etc
  69                 Hooks::run( 'ActionModifyFormFields', [ $this->getName(), &$this->fields, $this->page ] );
  70
  71                 $form = new HTMLForm( $this->fields, $this->getContext(), $this->getName() );
  72                 $form->setSubmitCallback( [ $this, 'onSubmit' ] );
  73
  74                 $title = $this->getTitle();
  75                 $form->setAction( $title->getLocalURL( [ 'action' => $this->getName() ] ) );
  76                 // Retain query parameters (uselang etc)
  77                 $params = array_diff_key(
  78                         $this->getRequest()->getQueryValues(),
  79                         [ 'action' => null, 'title' => null ]
  80                 );
  81                 if ( $params ) {
  82                         $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
  83                 }
  84
  85                 $form->addPreText( $this->preText() );
  86                 $form->addPostText( $this->postText() );
  87                 $this->alterForm( $form );
  88
  89                 // Give hooks a chance to alter the form, adding extra fields or text etc
  90                 Hooks::run( 'ActionBeforeFormDisplay', [ $this->getName(), &$form, $this->page ] );
  91
  92                 return $form;
  93         }
  94
  95         /**
  96          * Process the form on POST submission.
  97          *
  98          * If you don't want to do anything with the form, just return false here.
  99          *
 100          * @param array $data
 101          * @return bool|array True for success, false for didn't-try, array of errors on failure
 102          */
 103         abstract public function onSubmit( $data );
 104
 105         /**
 106          * Do something exciting on successful processing of the form.  This might be to show
 107          * a confirmation message (watch, rollback, etc) or to redirect somewhere else (edit,
 108          * protect, etc).
 109          */
 110         abstract public function onSuccess();
 111
 112         /**
 113          * The basic pattern for actions is to display some sort of HTMLForm UI, maybe with
 114          * some stuff underneath (history etc); to do some processing on submission of that
 115          * form (delete, protect, etc) and to do something exciting on 'success', be that
 116          * display something new or redirect to somewhere.  Some actions have more exotic
 117          * behavior, but that's what subclassing is for :D
 118          */
 119         public function show() {
 120                 $this->setHeaders();
 121
 122                 // This will throw exceptions if there's a problem
 123                 $this->checkCanExecute( $this->getUser() );
 124
 125                 $form = $this->getForm();
 126                 if ( $form->show() ) {
 127                         $this->onSuccess();
 128                 }
 129         }
 130
 131         public function doesWrites() {
 132                 return true;
 133         }
 134 }