[Summary view] [Print] [Text view]

   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 the HTMLForm to control behavior
  79       * @return HTMLForm|null
  80       */
  81  	protected function getForm() {
  82          $this->fields = $this->getFormFields();
  83  
  84          $form = new HTMLForm( $this->fields, $this->getContext(), $this->getMessagePrefix() );
  85          $form->setSubmitCallback( array( $this, 'onSubmit' ) );
  86          // If the form is a compact vertical form, then don't output this ugly
  87          // fieldset surrounding it.
  88          // XXX Special pages can setDisplayFormat to 'vform' in alterForm(), but that
  89          // is called after this.
  90          if ( !$form->isVForm() ) {
  91              $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
  92          }
  93  
  94          $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
  95          if ( !$headerMsg->isDisabled() ) {
  96              $form->addHeaderText( $headerMsg->parseAsBlock() );
  97          }
  98  
  99          // Retain query parameters (uselang etc)
 100          $params = array_diff_key(
 101              $this->getRequest()->getQueryValues(), array( 'title' => null ) );
 102          $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
 103  
 104          $form->addPreText( $this->preText() );
 105          $form->addPostText( $this->postText() );
 106          $this->alterForm( $form );
 107  
 108          // Give hooks a chance to alter the form, adding extra fields or text etc
 109          wfRunHooks( 'SpecialPageBeforeFormDisplay', array( $this->getName(), &$form ) );
 110  
 111          return $form;
 112      }
 113  
 114      /**
 115       * Process the form on POST submission.
 116       * @param array $data
 117       * @param HTMLForm $form
 118       * @return bool|string|array|Status As documented for HTMLForm::trySubmit.
 119       */
 120      abstract public function onSubmit( array $data /* $form = null */ );
 121  
 122      /**
 123       * Do something exciting on successful processing of the form, most likely to show a
 124       * confirmation message
 125       * @since 1.22 Default is to do nothing
 126       */
 127  	public function onSuccess() {
 128      }
 129  
 130      /**
 131       * Basic SpecialPage workflow: get a form, send it to the user; get some data back,
 132       *
 133       * @param string $par Subpage string if one was specified
 134       */
 135  	public function execute( $par ) {
 136          $this->setParameter( $par );
 137          $this->setHeaders();
 138  
 139          // This will throw exceptions if there's a problem
 140          $this->checkExecutePermissions( $this->getUser() );
 141  
 142          $form = $this->getForm();
 143          if ( $form->show() ) {
 144              $this->onSuccess();
 145          }
 146      }
 147  
 148      /**
 149       * Maybe do something interesting with the subpage parameter
 150       * @param string $par
 151       */
 152  	protected function setParameter( $par ) {
 153          $this->par = $par;
 154      }
 155  
 156      /**
 157       * Called from execute() to check if the given user can perform this action.
 158       * Failures here must throw subclasses of ErrorPageError.
 159       * @param User $user
 160       * @throws UserBlockedError
 161       * @return bool True
 162       */
 163  	protected function checkExecutePermissions( User $user ) {
 164          $this->checkPermissions();
 165  
 166          if ( $this->requiresUnblock() && $user->isBlocked() ) {
 167              $block = $user->getBlock();
 168              throw new UserBlockedError( $block );
 169          }
 170  
 171          if ( $this->requiresWrite() ) {
 172              $this->checkReadOnly();
 173          }
 174  
 175          return true;
 176      }
 177  
 178      /**
 179       * Whether this action requires the wiki not to be locked
 180       * @return bool
 181       */
 182  	public function requiresWrite() {
 183          return true;
 184      }
 185  
 186      /**
 187       * Whether this action cannot be executed by a blocked user
 188       * @return bool
 189       */
 190  	public function requiresUnblock() {
 191          return true;
 192      }
 193  }