merging latest master

[lhc/web/wiklou.git] / includes / Action.php

diff --git a/includes/Action.php b/includes/Action.php
index a25e8aa..5192225 100644 (file)
--- a/includes/Action.php
+++ b/includes/Action.php
@@ -1,15 +1,6 @@
 <?php
 /**
- * @defgroup Actions Action done on pages
- */
-
-/**
- * Actions are things which can be done to pages (edit, delete, rollback, etc).  They
- * are distinct from Special Pages because an action must apply to exactly one page.
- *
- * To add an action in an extension, create a subclass of Action, and add the key to
- * $wgActions.  There is also the deprecated UnknownAction hook
- *
+ * Base classes for actions done on pages.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -27,23 +18,39 @@
  *
  * @file
  */
+
+/**
+ * @defgroup Actions Action done on pages
+ */
+
+/**
+ * Actions are things which can be done to pages (edit, delete, rollback, etc).  They
+ * are distinct from Special Pages because an action must apply to exactly one page.
+ *
+ * To add an action in an extension, create a subclass of Action, and add the key to
+ * $wgActions.  There is also the deprecated UnknownAction hook
+ *
+ * Actions generally fall into two groups: the show-a-form-then-do-something-with-the-input
+ * format (protect, delete, move, etc), and the just-do-something format (watch, rollback,
+ * patrol, etc). The FormAction and FormlessAction classes respresent these two groups.
+ */
 abstract class Action {
 
        /**
         * Page on which we're performing the action
-        * @var Page
+        * @var Page $page
         */
        protected $page;
 
        /**
         * IContextSource if specified; otherwise we'll use the Context from the Page
-        * @var IContextSource
+        * @var IContextSource $context
         */
        protected $context;
 
        /**
         * The fields used to create the HTMLForm
-        * @var Array
+        * @var Array $fields
         */
        protected $fields;
 
@@ -334,7 +341,7 @@ abstract class Action {
         * @return String
         */
        protected function getDescription() {
-               return wfMsgHtml( strtolower( $this->getName() ) );
+               return $this->msg( strtolower( $this->getName() ) )->escaped();
        }
 
        /**
@@ -352,6 +359,9 @@ abstract class Action {
        public abstract function execute();
 }
 
+/**
+ * An action which shows a form and does something based on the input from the form
+ */
 abstract class FormAction extends Action {
 
        /**
@@ -387,7 +397,7 @@ abstract class FormAction extends Action {
                // Give hooks a chance to alter the form, adding extra fields or text etc
                wfRunHooks( 'ActionModifyFormFields', array( $this->getName(), &$this->fields, $this->page ) );
 
-               $form = new HTMLForm( $this->fields, $this->getContext() );
+               $form = new HTMLForm( $this->fields, $this->getContext(), $this->getName() );
                $form->setSubmitCallback( array( $this, 'onSubmit' ) );
 
                // Retain query parameters (uselang etc)
@@ -446,8 +456,8 @@ abstract class FormAction extends Action {
        /**
         * @see Action::execute()
         * @throws ErrorPageError
-        * @param array|null $data
-        * @param bool $captureErrors
+        * @param $data array|null
+        * @param $captureErrors bool
         * @return bool
         */
        public function execute( array $data = null, $captureErrors = true ) {
@@ -488,9 +498,7 @@ abstract class FormAction extends Action {
 }
 
 /**
- * Actions generally fall into two groups: the show-a-form-then-do-something-with-the-input
- * format (protect, delete, move, etc), and the just-do-something format (watch, rollback,
- * patrol, etc).
+ * An action which just does something, without showing a form first.
  */
 abstract class FormlessAction extends Action {
 
@@ -509,10 +517,17 @@ abstract class FormlessAction extends Action {
                return false;
        }
 
+       /**
+        * @param $data Array
+        * @return bool
+        */
        public function onSubmit( $data ) {
                return false;
        }
 
+       /**
+        * @return bool
+        */
        public function onSuccess() {
                return false;
        }