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         abstract protected function getFormFields();
  35
  36         /**
  37          * Add pre- or post-text to the form
  38          * @return string HTML which will be sent to $form->addPreText()
  39          */
  40         protected function preText() {
  41                 return '';
  42         }
  43
  44         /**
  45          * @return string
  46          */
  47         protected function postText() {
  48                 return '';
  49         }
  50
  51         /**
  52          * Play with the HTMLForm if you need to more substantially
  53          * @param HTMLForm $form
  54          */
  55         protected function alterForm( HTMLForm $form ) {
  56         }
  57
  58         /**
  59          * Get the HTMLForm to control behavior
  60          * @return HTMLForm|null
  61          */
  62         protected function getForm() {
  63                 $this->fields = $this->getFormFields();
  64
  65                 // Give hooks a chance to alter the form, adding extra fields or text etc
  66                 Hooks::run( 'ActionModifyFormFields', array( $this->getName(), &$this->fields, $this->page ) );
  67
  68                 $form = new HTMLForm( $this->fields, $this->getContext(), $this->getName() );
  69                 $form->setSubmitCallback( array( $this, 'onSubmit' ) );
  70
  71                 // Retain query parameters (uselang etc)
  72                 $form->addHiddenField( 'action', $this->getName() ); // Might not be the same as the query string
  73                 $params = array_diff_key(
  74                         $this->getRequest()->getQueryValues(),
  75                         array( 'action' => null, 'title' => null )
  76                 );
  77                 $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
  78
  79                 $form->addPreText( $this->preText() );
  80                 $form->addPostText( $this->postText() );
  81                 $this->alterForm( $form );
  82
  83                 // Give hooks a chance to alter the form, adding extra fields or text etc
  84                 Hooks::run( 'ActionBeforeFormDisplay', array( $this->getName(), &$form, $this->page ) );
  85
  86                 return $form;
  87         }
  88
  89         /**
  90          * Process the form on POST submission.  If you return false from getFormFields(),
  91          * this will obviously never be reached.  If you don't want to do anything with the
  92          * form, just return false here
  93          * @param array $data
  94          * @return bool|array True for success, false for didn't-try, array of errors on failure
  95          */
  96         abstract public function onSubmit( $data );
  97
  98         /**
  99          * Do something exciting on successful processing of the form.  This might be to show
 100          * a confirmation message (watch, rollback, etc) or to redirect somewhere else (edit,
 101          * protect, etc).
 102          */
 103         abstract public function onSuccess();
 104
 105         /**
 106          * The basic pattern for actions is to display some sort of HTMLForm UI, maybe with
 107          * some stuff underneath (history etc); to do some processing on submission of that
 108          * form (delete, protect, etc) and to do something exciting on 'success', be that
 109          * display something new or redirect to somewhere.  Some actions have more exotic
 110          * behavior, but that's what subclassing is for :D
 111          */
 112         public function show() {
 113                 $this->setHeaders();
 114
 115                 // This will throw exceptions if there's a problem
 116                 $this->checkCanExecute( $this->getUser() );
 117
 118                 $form = $this->getForm();
 119                 if ( $form->show() ) {
 120                         $this->onSuccess();
 121                 }
 122         }
 123 }