3 * Special page which uses an HTMLForm to handle processing.
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.
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.
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
21 * @ingroup SpecialPage
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.
29 * @ingroup SpecialPage
31 abstract class FormSpecialPage
extends SpecialPage
{
33 * The sub-page of the special page.
36 protected $par = null;
39 * @var array|null POST data preserved across re-authentication
42 protected $reauthPostData = null;
45 * Get an HTMLForm descriptor array
48 abstract protected function getFormFields();
51 * Add pre-text to the form
52 * @return string HTML which will be sent to $form->addPreText()
54 protected function preText() {
59 * Add post-text to the form
60 * @return string HTML which will be sent to $form->addPostText()
62 protected function postText() {
67 * Play with the HTMLForm if you need to more substantially
68 * @param HTMLForm $form
70 protected function alterForm( HTMLForm
$form ) {
74 * Get message prefix for HTMLForm
79 protected function getMessagePrefix() {
80 return strtolower( $this->getName() );
84 * Get display format for the form. See HTMLForm documentation for available values.
89 protected function getDisplayFormat() {
94 * Get the HTMLForm to control behavior
95 * @return HTMLForm|null
97 protected function getForm() {
98 $context = $this->getContext();
99 $onSubmit = [ $this, 'onSubmit' ];
101 if ( $this->reauthPostData
) {
103 $context = new DerivativeContext( $context );
104 $oldRequest = $this->getRequest();
105 $context->setRequest( new DerivativeRequest(
106 $oldRequest, $this->reauthPostData +
$oldRequest->getQueryValues(), true
109 // But don't treat it as a "real" submission just in case of some
110 // crazy kind of CSRF.
111 $onSubmit = function () {
116 $form = HTMLForm
::factory(
117 $this->getDisplayFormat(),
118 $this->getFormFields(),
120 $this->getMessagePrefix()
122 $form->setSubmitCallback( $onSubmit );
123 if ( $this->getDisplayFormat() !== 'ooui' ) {
124 // No legend and wrapper by default in OOUI forms, but can be set manually
126 $form->setWrapperLegendMsg( $this->getMessagePrefix() . '-legend' );
129 $headerMsg = $this->msg( $this->getMessagePrefix() . '-text' );
130 if ( !$headerMsg->isDisabled() ) {
131 $form->addHeaderText( $headerMsg->parseAsBlock() );
134 $form->addPreText( $this->preText() );
135 $form->addPostText( $this->postText() );
136 $this->alterForm( $form );
137 if ( $form->getMethod() == 'post' ) {
138 // Retain query parameters (uselang etc) on POST requests
139 $params = array_diff_key(
140 $this->getRequest()->getQueryValues(), [ 'title' => null ] );
141 $form->addHiddenField( 'redirectparams', wfArrayToCgi( $params ) );
144 // Give hooks a chance to alter the form, adding extra fields or text etc
145 Hooks
::run( 'SpecialPageBeforeFormDisplay', [ $this->getName(), &$form ] );
151 * Process the form on POST submission.
153 * @param HTMLForm $form
154 * @return bool|string|array|Status As documented for HTMLForm::trySubmit.
156 abstract public function onSubmit( array $data /* $form = null */ );
159 * Do something exciting on successful processing of the form, most likely to show a
160 * confirmation message
161 * @since 1.22 Default is to do nothing
163 public function onSuccess() {
167 * Basic SpecialPage workflow: get a form, send it to the user; get some data back,
169 * @param string|null $par Subpage string if one was specified
171 public function execute( $par ) {
172 $this->setParameter( $par );
175 // This will throw exceptions if there's a problem
176 $this->checkExecutePermissions( $this->getUser() );
178 $securityLevel = $this->getLoginSecurityLevel();
179 if ( $securityLevel !== false && !$this->checkLoginSecurityLevel( $securityLevel ) ) {
183 $form = $this->getForm();
184 if ( $form->show() ) {
190 * Maybe do something interesting with the subpage parameter
191 * @param string|null $par
193 protected function setParameter( $par ) {
198 * Called from execute() to check if the given user can perform this action.
199 * Failures here must throw subclasses of ErrorPageError.
201 * @throws UserBlockedError
203 protected function checkExecutePermissions( User
$user ) {
204 $this->checkPermissions();
206 if ( $this->requiresUnblock() ) {
207 $block = $user->getBlock();
208 if ( $block && $block->isSitewide() ) {
209 throw new UserBlockedError( $block );
213 if ( $this->requiresWrite() ) {
214 $this->checkReadOnly();
219 * Whether this action requires the wiki not to be locked
222 public function requiresWrite() {
227 * Whether this action cannot be executed by a blocked user
230 public function requiresUnblock() {
235 * Preserve POST data across reauthentication
240 protected function setReauthPostData( array $data ) {
241 $this->reauthPostData
= $data;