MDL-30811 output: Tidy up notifications
authorAndrew Nicols <andrew@nicols.co.uk>
Tue, 16 Feb 2016 00:45:29 +0000 (08:45 +0800)
committerAndrew Nicols <andrew@nicols.co.uk>
Sun, 28 Feb 2016 11:16:34 +0000 (19:16 +0800)
13 files changed:
admin/tool/templatelibrary/tests/externallib_test.php
lib/classes/output/notification.php
lib/deprecatedlib.php
lib/outputrenderers.php
lib/templates/notification_error.mustache [moved from lib/templates/notification_redirect.mustache with 73% similarity]
lib/templates/notification_info.mustache [moved from lib/templates/notification_problem.mustache with 73% similarity]
lib/templates/notification_success.mustache
lib/templates/notification_warning.mustache [moved from lib/templates/notification_message.mustache with 73% similarity]
lib/upgrade.txt
theme/base/templates/core/notification_error.mustache [moved from theme/base/templates/core/notification_problem.mustache with 100% similarity]
theme/base/templates/core/notification_info.mustache [moved from theme/base/templates/core/notification_redirect.mustache with 100% similarity]
theme/base/templates/core/notification_warning.mustache [moved from theme/base/templates/core/notification_message.mustache with 100% similarity]
theme/upgrade.txt

index 9b09541..ac31ab6 100644 (file)
@@ -72,10 +72,10 @@ class tool_templatelibrary_external_testcase extends externallib_advanced_testca
         // Change the theme to 'base' because it overrides these templates.
         $CFG->theme = 'base';
 
-        $template = external::load_canonical_template('core', 'notification_problem');
+        $template = external::load_canonical_template('core', 'notification_error');
 
         // Only the base template should contain the docs.
-        $this->assertContains('@template core/notification_problem', $template);
+        $this->assertContains('@template core/notification_error', $template);
 
         // Restore the original theme.
         $CFG->theme = $originaltheme;
index 6cf19ed..f97af74 100644 (file)
@@ -23,7 +23,6 @@
  */
 
 namespace core\output;
-use stdClass;
 
 /**
  * Data structure representing a notification.
@@ -37,31 +36,57 @@ use stdClass;
 class notification implements \renderable, \templatable {
 
     /**
-     * A generic message.
+     * A notification of level 'success'.
      */
-    const NOTIFY_MESSAGE = 'message';
+    const NOTIFY_SUCCESS = 'success';
+
     /**
-     * A message notifying the user of a successful operation.
+     * A notification of level 'warning'.
      */
-    const NOTIFY_SUCCESS = 'success';
+    const NOTIFY_WARNING = 'warning';
+
+    /**
+     * A notification of level 'info'.
+     */
+    const NOTIFY_INFO = 'info';
+
+    /**
+     * A notification of level 'error'.
+     */
+    const NOTIFY_ERROR = 'error';
+
+    /**
+     * @deprecated
+     * A generic message.
+     */
+    const NOTIFY_MESSAGE = 'message';
+
     /**
+     * @deprecated
      * A message notifying the user that a problem occurred.
      */
     const NOTIFY_PROBLEM = 'problem';
+
     /**
-     * A message to display during a redirect..
+     * @deprecated
+     * A notification of level 'redirect'.
      */
     const NOTIFY_REDIRECT = 'redirect';
 
     /**
      * @var string Message payload.
      */
-    private $message = '';
+    protected $message = '';
 
     /**
      * @var string Message type.
      */
-    private $messagetype = self::NOTIFY_PROBLEM;
+    protected $messagetype = self::NOTIFY_WARNING;
+
+    /**
+     * @var array $extraclasses A list of any extra classes that may be required.
+     */
+    protected $extraclasses = array();
 
     /**
      * Notification constructor.
@@ -69,11 +94,33 @@ class notification implements \renderable, \templatable {
      * @param string $message the message to print out
      * @param string $messagetype normally NOTIFY_PROBLEM or NOTIFY_SUCCESS.
      */
-    public function __construct($message, $messagetype = self::NOTIFY_PROBLEM) {
+    public function __construct($message, $messagetype = null) {
+        $this->message = $message;
+
+        if (empty($messagetype)) {
+            $messagetype = self::NOTIFY_ERROR;
+        }
 
-        $this->message = clean_text($message);
         $this->messagetype = $messagetype;
 
+        switch ($messagetype) {
+            case self::NOTIFY_PROBLEM:
+            case self::NOTIFY_REDIRECT:
+            case self::NOTIFY_MESSAGE:
+                debugging('Use of ' . $messagetype . ' has been deprecated. Please switch to an alternative type.');
+        }
+    }
+
+    /**
+     * Add any extra classes that this notification requires.
+     *
+     * @param array $classes
+     * @return $this
+     */
+    public function set_extra_classes($classes = array()) {
+        $this->extraclasses = $classes;
+
+        return $this;
     }
 
     /**
@@ -83,12 +130,24 @@ class notification implements \renderable, \templatable {
      * @return stdClass data context for a mustache template
      */
     public function export_for_template(\renderer_base $output) {
+        return array(
+            'message'       => clean_text($this->message),
+            'extraclasses'  => implode(' ', $this->extraclasses),
+        );
+    }
 
-        $data = new stdClass();
-
-        $data->type = $this->messagetype;
-        $data->message = $this->message;
+    public function get_template_name() {
+        $templatemappings = [
+            // Current types mapped to template names.
+            'success'           => 'core/notification_success',
+            'info'              => 'core/notification_info',
+            'warning'           => 'core/notification_warning',
+            'error'             => 'core/notification_error',
+        ];
 
-        return $data;
+        if (isset($templatemappings[$this->messagetype])) {
+            return $templatemappings[$this->messagetype];
+        }
+        return $templatemappings['error'];
     }
 }
index 6222822..f71453c 100644 (file)
@@ -912,14 +912,14 @@ function print_container_end($return=false) {
  * @param bool $return whether to return an output string or echo now
  * @return string|bool Depending on $result
  */
-function notify($message, $classes = 'notifyproblem', $align = 'center', $return = false) {
+function notify($message, $classes = 'error', $align = 'center', $return = false) {
     global $OUTPUT;
 
     debugging('notify() is deprecated, please use $OUTPUT->notification() instead', DEBUG_DEVELOPER);
 
     if ($classes == 'green') {
-        debugging('Use of deprecated class name "green" in notify. Please change to "notifysuccess".', DEBUG_DEVELOPER);
-        $classes = 'notifysuccess'; // Backward compatible with old color system
+        debugging('Use of deprecated class name "green" in notify. Please change to "success".', DEBUG_DEVELOPER);
+        $classes = 'success'; // Backward compatible with old color system.
     }
 
     $output = $OUTPUT->notification($message, $classes);
index 066f82e..99997c8 100644 (file)
@@ -2778,38 +2778,63 @@ EOD;
     }
 
     /**
-     * Output a notification (that is, a status message about something that has
-     * just happened).
+     * Output a notification (that is, a status message about something that has just happened).
      *
-     * @param string $message the message to print out
-     * @param string $classes normally 'notifyproblem' or 'notifysuccess'.
+     * @param string $message The message to print out.
+     * @param string $type    The type of notification. See constants on \core\output\notification.
      * @return string the HTML to output.
      */
-    public function notification($message, $classes = 'notifyproblem') {
-
-        $classmappings = array(
-            'notifyproblem' => \core\output\notification::NOTIFY_PROBLEM,
-            'notifytiny' => \core\output\notification::NOTIFY_PROBLEM,
-            'notifysuccess' => \core\output\notification::NOTIFY_SUCCESS,
-            'notifymessage' => \core\output\notification::NOTIFY_MESSAGE,
-            'redirectmessage' => \core\output\notification::NOTIFY_REDIRECT
-        );
-
-        // Identify what type of notification this is.
-        $type = \core\output\notification::NOTIFY_PROBLEM;
-        $classarray = explode(' ', self::prepare_classes($classes));
-        if (count($classarray) > 0) {
-            foreach ($classarray as $class) {
-                if (isset($classmappings[$class])) {
-                    $type = $classmappings[$class];
-                    break;
+    public function notification($message, $type = null) {
+        $typemappings = [
+            // Valid types.
+            'success'           => \core\output\notification::NOTIFY_SUCCESS,
+            'info'              => \core\output\notification::NOTIFY_INFO,
+            'warning'           => \core\output\notification::NOTIFY_WARNING,
+            'error'             => \core\output\notification::NOTIFY_ERROR,
+
+            // Legacy types mapped to current types.
+            'notifyproblem'     => \core\output\notification::NOTIFY_ERROR,
+            'notifytiny'        => \core\output\notification::NOTIFY_ERROR,
+            'notifyerror'       => \core\output\notification::NOTIFY_ERROR,
+            'notifysuccess'     => \core\output\notification::NOTIFY_SUCCESS,
+            'notifymessage'     => \core\output\notification::NOTIFY_INFO,
+            'notifyredirect'    => \core\output\notification::NOTIFY_INFO,
+            'redirectmessage'   => \core\output\notification::NOTIFY_INFO,
+        ];
+
+        $extraclasses = [];
+
+        if ($type) {
+            if (strpos($type, ' ') === false) {
+                // No spaces in the list of classes, therefore no need to loop over and determine the class.
+                if (isset($typemappings[$type])) {
+                    $type = $typemappings[$type];
+                } else {
+                    // The value provided did not match a known type. It must be an extra class.
+                    $extraclasses = [$type];
+                }
+            } else {
+                // Identify what type of notification this is.
+                $classarray = explode(' ', self::prepare_classes($type));
+
+                // Separate out the type of notification from the extra classes.
+                foreach ($classarray as $class) {
+                    if (isset($typemappings[$class])) {
+                        $type = $typemappings[$class];
+                    } else {
+                        $extraclasses[] = $class;
+                    }
                 }
             }
         }
 
-        $n = new \core\output\notification($message, $type);
-        return $this->render($n);
+        $notification = new \core\output\notification($message, $type);
+        if (count($extraclasses)) {
+            $notification->set_extra_classes($extraclasses);
+        }
 
+        // Return the rendered template.
+        return $this->render_from_template($notification->get_template_name(), $notification->export_for_template($this));
     }
 
     /**
@@ -2817,9 +2842,15 @@ EOD;
      *
      * @param string $message the message to print out
      * @return string HTML fragment.
+     * @deprecated since Moodle 3.1 MDL-30811 - please do not use this function any more.
+     * @todo MDL-53113 This will be removed in Moodle 3.5.
+     * @see \core\output\notification
      */
     public function notify_problem($message) {
-        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_PROBLEM);
+        debugging(__FUNCTION__ . ' is deprecated.' .
+            'Please use notification() or \core\output\notification as required',
+            DEBUG_DEVELOPER);
+        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_ERROR);
         return $this->render($n);
     }
 
@@ -2828,8 +2859,14 @@ EOD;
      *
      * @param string $message the message to print out
      * @return string HTML fragment.
+     * @deprecated since Moodle 3.1 MDL-30811 - please do not use this function any more.
+     * @todo MDL-53113 This will be removed in Moodle 3.5.
+     * @see \core\output\notification
      */
     public function notify_success($message) {
+        debugging(__FUNCTION__ . ' is deprecated.' .
+            'Please use notification() or \core\output\notification as required',
+            DEBUG_DEVELOPER);
         $n = new \core\output\notification($message, \core\output\notification::NOTIFY_SUCCESS);
         return $this->render($n);
     }
@@ -2839,9 +2876,15 @@ EOD;
      *
      * @param string $message the message to print out
      * @return string HTML fragment.
+     * @deprecated since Moodle 3.1 MDL-30811 - please do not use this function any more.
+     * @todo MDL-53113 This will be removed in Moodle 3.5.
+     * @see \core\output\notification
      */
     public function notify_message($message) {
-        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_MESSAGE);
+        debugging(__FUNCTION__ . ' is deprecated.' .
+            'Please use notification() or \core\output\notification as required',
+            DEBUG_DEVELOPER);
+        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_INFO);
         return $this->render($n);
     }
 
@@ -2850,9 +2893,15 @@ EOD;
      *
      * @param string $message the message to print out
      * @return string HTML fragment.
+     * @deprecated since Moodle 3.1 MDL-30811 - please do not use this function any more.
+     * @todo MDL-53113 This will be removed in Moodle 3.5.
+     * @see \core\output\notification
      */
     public function notify_redirect($message) {
-        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_REDIRECT);
+        debugging(__FUNCTION__ . ' is deprecated.' .
+            'Please use notification() or \core\output\notification as required',
+            DEBUG_DEVELOPER);
+        $n = new \core\output\notification($message, \core\output\notification::NOTIFY_INFO);
         return $this->render($n);
     }
 
@@ -2864,30 +2913,7 @@ EOD;
      * @return string the HTML to output.
      */
     protected function render_notification(\core\output\notification $notification) {
-
-        $data = $notification->export_for_template($this);
-
-        $templatename = '';
-        switch($data->type) {
-            case \core\output\notification::NOTIFY_MESSAGE:
-                $templatename = 'core/notification_message';
-                break;
-            case \core\output\notification::NOTIFY_SUCCESS:
-                $templatename = 'core/notification_success';
-                break;
-            case \core\output\notification::NOTIFY_PROBLEM:
-                $templatename = 'core/notification_problem';
-                break;
-            case \core\output\notification::NOTIFY_REDIRECT:
-                $templatename = 'core/notification_redirect';
-                break;
-            default:
-                $templatename = 'core/notification_message';
-                break;
-        }
-
-        return self::render_from_template($templatename, $data);
-
+        return $this->render_from_template($notification->get_template_name(), $notification->export_for_template($this));
     }
 
     /**
@@ -4251,13 +4277,13 @@ class core_renderer_cli extends core_renderer {
     /**
      * Returns a template fragment representing a notification.
      *
-     * @param string $message The message to include
-     * @param string $classes A space-separated list of CSS classes
+     * @param string $message The message to print out.
+     * @param string $type    The type of notification. See constants on \core\output\notification.
      * @return string A template fragment for a notification
      */
-    public function notification($message, $classes = 'notifyproblem') {
+    public function notification($message, $type = null) {
         $message = clean_text($message);
-        if ($classes === 'notifysuccess') {
+        if ($type === 'notifysuccess' || $type === 'success') {
             return "++ $message ++\n";
         }
         return "!! $message !!\n";
@@ -4325,10 +4351,10 @@ class core_renderer_ajax extends core_renderer {
      * Used to display a notification.
      * For the AJAX notifications are discarded.
      *
-     * @param string $message
-     * @param string $classes
+     * @param string $message The message to print out.
+     * @param string $type    The type of notification. See constants on \core\output\notification.
      */
-    public function notification($message, $classes = 'notifyproblem') {}
+    public function notification($message, $type = null) {}
 
     /**
      * Used to display a redirection message.
similarity index 73%
rename from lib/templates/notification_redirect.mustache
rename to lib/templates/notification_error.mustache
index 4181bd0..3929ca0 100644 (file)
     along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 }}
 {{!
-    @template core/notification_redirect
+    @template core/notification_error
 
     Moodle notification template.
 
-    The purpose of this template is to render a message notification.
+    The purpose of this template is to render an error notification.
 
     Classes required for JS:
     * none
 
     Context variables required for this template:
     * message A cleaned string (use clean_text()) to display.
+    * extraclasses Additional classes to apply to the notification.
 
     Example context (json):
-    { "message": "Your pants are on fire!" }
+    { "message": "Your pants are on fire!", "extraclasses": "foo bar"}
 }}
-<div class="alert alert-block alert-info">{{{message}}}</div>
+<div class="alert alert-error alert-block fade in {{ extraclasses }}">
+    {{{ message }}}
+</div>
similarity index 73%
rename from lib/templates/notification_problem.mustache
rename to lib/templates/notification_info.mustache
index 67b6516..dc42ca2 100644 (file)
     along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 }}
 {{!
-    @template core/notification_problem
+    @template core/notification_info
 
     Moodle notification template.
 
-    The purpose of this template is to render a problem notification.
+    The purpose of this template is to render an info notification.
 
     Classes required for JS:
     * none
 
     Context variables required for this template:
     * message A cleaned string (use clean_text()) to display.
+    * extraclasses Additional classes to apply to the notification.
 
     Example context (json):
-    { "message": "Your pants are on fire!" }
+    { "message": "Your pants are on fire!", "extraclasses": "foo bar"}
 }}
-<div class="alert alert-error">{{{message}}}</div>
+<div class="alert alert-info alert-block fade in {{ extraclasses }}">
+    {{{ message }}}
+</div>
index 1f806f0..ef7aeb0 100644 (file)
 
     Context variables required for this template:
     * message A cleaned string (use clean_text()) to display.
+    * extraclasses Additional classes to apply to the notification.
 
     Example context (json):
-    { "message": "Your pants are on fire!" }
+    { "message": "Your pants are on fire!", "extraclasses": "foo bar"}
 }}
-<div class="alert alert-success">{{{message}}}</div>
+<div class="alert alert-success alert-block fade in {{ extraclasses }}">
+    {{{ message }}}
+</div>
similarity index 73%
rename from lib/templates/notification_message.mustache
rename to lib/templates/notification_warning.mustache
index 16d87b7..1fe001d 100644 (file)
     along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 }}
 {{!
-    @template core/notification_message
+    @template core/notification_warning
 
     Moodle notification template.
 
-    The purpose of this template is to render a message notification.
+    The purpose of this template is to render a warning notification.
 
     Classes required for JS:
     * none
 
     Context variables required for this template:
     * message A cleaned string (use clean_text()) to display.
+    * extraclasses Additional classes to apply to the notification.
 
     Example context (json):
-    { "message": "Your pants are on fire!" }
+    { "message": "Your pants are on fire!", "extraclasses": "foo bar"}
 }}
-<div class="alert alert-info">{{{message}}}</div>
+<div class="alert alert-warning alert-block fade in {{ extraclasses }}">
+    {{{ message }}}
+</div>
index 68ac67a..87426fb 100644 (file)
@@ -3,6 +3,13 @@ information provided here is intended especially for developers.
 
 === 3.1 ===
 
+* The specification of extra classes in the $OUTPUT->notification()
+  function, and \core\output\notification renderable have been deprecated
+  and will be removed in a future version.
+  Notifications should use the levels found in \core\output\notification.
+* The constants for NOTIFY_PROBLEM, NOTIFY_REDIRECT, and NOTIFY_MESSAGE in
+  \core\output\notification have been deprecated in favour of NOTIFY_ERROR,
+  NOTIFY_WARNING, and NOTIFY_INFO respectively.
 * The following functions, previously used (exclusively) by upgrade steps are not available
   anymore because of the upgrade cleanup performed for this version. See MDL-51580 for more info:
     - upgrade_mysql_fix_unsigned_and_lob_columns()
index b86f04c..05587d5 100644 (file)
@@ -6,6 +6,11 @@ information provided here is intended especially for theme designer.
 * A new search box for global search has been added to bootstrap and clean layout files, if
   your theme is overwriting columns1.php, columns2.php or columns3.php you will need to add a
   call to core_renderer::search_box to display it.
+* Notification templates have been renamed to better suit types of alert
+  rather than uses. The following changes have been made:
+  * notification_problem.mustache => notification_error.mustache
+  * notification_message          => notification_info
+  * notification_redirect         => notification_warning
 
 === 3.0 ===