includes/specialpage/FormSpecialPage.php

   1 <?php
   2 /**
   3  * Special page which uses an HTMLForm to handle processing.
   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 along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup SpecialPage
  22  */
  23
  24 /**
  25  * Special page which uses an HTMLForm to handle processing.  This is mostly a
  26  * clone of FormAction.  More special pages should be built this way; maybe this could be
  27  * a new structure for SpecialPages.
  28  *
  29  * @ingroup SpecialPage
  30  */
  31 abstract class FormSpecialPage extends SpecialPage {
  32         /**
  33          * The sub-page of the special page.
  34          * @var string
  35          */
  36         protected $par = null;
  37
  38         /**
  39          * Get an HTMLForm descriptor array
  40          * @return array
  41          */
  42         abstract protected function getFormFields();
  43
  44         /**
  45          * Add pre-text to the form
  46          * @return string HTML which will be sent to $form->addPreText()
  47          */
  48         protected function preText() {
  49                 return '';
  50         }
  51
  52         /**
  53          * Add post-text to the form
  54          * @return string HTML which will be sent to $form->addPostText()
  55          */
  56         protected function postText() {
  57                 return '';
  58         }
  59
  60         /**
  61          * Play with the HTMLForm if you need to more substantially
  62          * @param HTMLForm $form
  63          */
  64         protected function alterForm( HTMLForm $form ) {
  65         }
  66
  67         /**
  68          * Get message prefix for HTMLForm
  69          *
  70          * @since 1.21
  71          * @return string
  72          */
  73         protected function getMessagePrefix() {
  74                 return strtolower( $this->getName() );
  75         }
  76
  77         /**
  78          * Get display format for the form. See HTMLForm documentation for available values.
  79          *
  80          * @since 1.25
  81          * @return string
  82          */
  83         protected function getDisplayFormat() {
  84                 return 'table';
  85         }
  86
  87         /**
  88          * Get the HTMLForm to control behavior
  89          * @return HTMLForm|null
  90          */
  91         protected function getForm() {
  92                 $form = HTMLForm::factory(
  93                         $this->getDisplayFormat(),
  94                         $this->getFormFields(),
  95                         $this->getContext(),
  96                         $this->getMessagePrefix()
  97                 );
  98                 $form->setSubmitCallback( [ $this, 'onSubmit' ] );
  99                 if ( $this->getDisplayFormat() !== 'ooui' ) {
 100                         // No legend and wrapper by default in OOUI forms, but can be set manually
 101                         // from alterForm()
 102                         $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
 103                 }
 104
 105                 $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
 106                 if ( !$headerMsg->isDisabled() ) {
 107                         $form->addHeaderText( $headerMsg->parseAsBlock() );
 108                 }
 109
 110                 $form->addPreText( $this->preText() );
 111                 $form->addPostText( $this->postText() );
 112                 $this->alterForm( $form );
 113                 if ( $form->getMethod() == 'post' ) {
 114                         // Retain query parameters (uselang etc) on POST requests
 115                         $params = array_diff_key(
 116                                 $this->getRequest()->getQueryValues(), [ 'title' => null ] );
 117                         $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
 118                 }
 119
 120                 // Give hooks a chance to alter the form, adding extra fields or text etc
 121                 Hooks::run( 'SpecialPageBeforeFormDisplay', [ $this->getName(), &$form ] );
 122
 123                 return $form;
 124         }
 125
 126         /**
 127          * Process the form on POST submission.
 128          * @param array $data
 129          * @param HTMLForm $form
 130          * @return bool|string|array|Status As documented for HTMLForm::trySubmit.
 131          */
 132         abstract public function onSubmit( array $data /* $form = null */ );
 133
 134         /**
 135          * Do something exciting on successful processing of the form, most likely to show a
 136          * confirmation message
 137          * @since 1.22 Default is to do nothing
 138          */
 139         public function onSuccess() {
 140         }
 141
 142         /**
 143          * Basic SpecialPage workflow: get a form, send it to the user; get some data back,
 144          *
 145          * @param string $par Subpage string if one was specified
 146          */
 147         public function execute( $par ) {
 148                 $this->setParameter( $par );
 149                 $this->setHeaders();
 150
 151                 // This will throw exceptions if there's a problem
 152                 $this->checkExecutePermissions( $this->getUser() );
 153
 154                 $form = $this->getForm();
 155                 if ( $form->show() ) {
 156                         $this->onSuccess();
 157                 }
 158         }
 159
 160         /**
 161          * Maybe do something interesting with the subpage parameter
 162          * @param string $par
 163          */
 164         protected function setParameter( $par ) {
 165                 $this->par = $par;
 166         }
 167
 168         /**
 169          * Called from execute() to check if the given user can perform this action.
 170          * Failures here must throw subclasses of ErrorPageError.
 171          * @param User $user
 172          * @throws UserBlockedError
 173          */
 174         protected function checkExecutePermissions( User $user ) {
 175                 $this->checkPermissions();
 176
 177                 if ( $this->requiresUnblock() && $user->isBlocked() ) {
 178                         $block = $user->getBlock();
 179                         throw new UserBlockedError( $block );
 180                 }
 181
 182                 if ( $this->requiresWrite() ) {
 183                         $this->checkReadOnly();
 184                 }
 185         }
 186
 187         /**
 188          * Whether this action requires the wiki not to be locked
 189          * @return bool
 190          */
 191         public function requiresWrite() {
 192                 return true;
 193         }
 194
 195         /**
 196          * Whether this action cannot be executed by a blocked user
 197          * @return bool
 198          */
 199         public function requiresUnblock() {
 200                 return true;
 201         }
 202 }