diff --git a/admin/tool/templatelibrary/tests/externallib_test.php b/admin/tool/templatelibrary/tests/externallib_test.php index 9b09541f4d7..ac31ab64176 100644 --- a/admin/tool/templatelibrary/tests/externallib_test.php +++ b/admin/tool/templatelibrary/tests/externallib_test.php @@ -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; diff --git a/lib/classes/output/notification.php b/lib/classes/output/notification.php index 6cf19eddd84..f97af740486 100644 --- a/lib/classes/output/notification.php +++ b/lib/classes/output/notification.php @@ -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 notification of level 'success'. + */ + const NOTIFY_SUCCESS = 'success'; + + /** + * A notification of level 'warning'. + */ + 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'; + /** - * A message notifying the user of a successful operation. - */ - const NOTIFY_SUCCESS = 'success'; - /** + * @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(); + 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', + ]; - $data->type = $this->messagetype; - $data->message = $this->message; - - return $data; + if (isset($templatemappings[$this->messagetype])) { + return $templatemappings[$this->messagetype]; + } + return $templatemappings['error']; } } diff --git a/lib/deprecatedlib.php b/lib/deprecatedlib.php index 6222822795f..f71453cb494 100644 --- a/lib/deprecatedlib.php +++ b/lib/deprecatedlib.php @@ -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); diff --git a/lib/outputrenderers.php b/lib/outputrenderers.php index 066f82e6a9f..99997c8075b 100644 --- a/lib/outputrenderers.php +++ b/lib/outputrenderers.php @@ -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') { + 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, - $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 - ); + // 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, + ]; - // 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; + $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. diff --git a/lib/templates/notification_redirect.mustache b/lib/templates/notification_error.mustache similarity index 73% rename from lib/templates/notification_redirect.mustache rename to lib/templates/notification_error.mustache index 4181bd0a4bb..3929ca013c2 100644 --- a/lib/templates/notification_redirect.mustache +++ b/lib/templates/notification_error.mustache @@ -15,11 +15,11 @@ along with Moodle. If not, see . }} {{! - @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 @@ -29,8 +29,11 @@ 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"} }} -
{{{message}}}
+
+ {{{ message }}} +
diff --git a/lib/templates/notification_problem.mustache b/lib/templates/notification_info.mustache similarity index 73% rename from lib/templates/notification_problem.mustache rename to lib/templates/notification_info.mustache index 67b65167de9..dc42ca26484 100644 --- a/lib/templates/notification_problem.mustache +++ b/lib/templates/notification_info.mustache @@ -15,11 +15,11 @@ along with Moodle. If not, see . }} {{! - @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 @@ -29,8 +29,11 @@ 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"} }} -
{{{message}}}
+
+ {{{ message }}} +
diff --git a/lib/templates/notification_success.mustache b/lib/templates/notification_success.mustache index 1f806f03d15..ef7aeb09d0f 100644 --- a/lib/templates/notification_success.mustache +++ b/lib/templates/notification_success.mustache @@ -29,8 +29,11 @@ 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"} }} -
{{{message}}}
+
+ {{{ message }}} +
diff --git a/lib/templates/notification_message.mustache b/lib/templates/notification_warning.mustache similarity index 73% rename from lib/templates/notification_message.mustache rename to lib/templates/notification_warning.mustache index 16d87b74a47..1fe001d3f4f 100644 --- a/lib/templates/notification_message.mustache +++ b/lib/templates/notification_warning.mustache @@ -15,11 +15,11 @@ along with Moodle. If not, see . }} {{! - @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 @@ -29,8 +29,11 @@ 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"} }} -
{{{message}}}
+
+ {{{ message }}} +
diff --git a/lib/upgrade.txt b/lib/upgrade.txt index 68ac67a37f8..87426fb6924 100644 --- a/lib/upgrade.txt +++ b/lib/upgrade.txt @@ -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() diff --git a/theme/base/templates/core/notification_problem.mustache b/theme/base/templates/core/notification_error.mustache similarity index 100% rename from theme/base/templates/core/notification_problem.mustache rename to theme/base/templates/core/notification_error.mustache diff --git a/theme/base/templates/core/notification_redirect.mustache b/theme/base/templates/core/notification_info.mustache similarity index 100% rename from theme/base/templates/core/notification_redirect.mustache rename to theme/base/templates/core/notification_info.mustache diff --git a/theme/base/templates/core/notification_message.mustache b/theme/base/templates/core/notification_warning.mustache similarity index 100% rename from theme/base/templates/core/notification_message.mustache rename to theme/base/templates/core/notification_warning.mustache diff --git a/theme/upgrade.txt b/theme/upgrade.txt index b86f04c16f1..05587d51fff 100644 --- a/theme/upgrade.txt +++ b/theme/upgrade.txt @@ -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 ===