Notifications

Notification types: info, success, error, warning

Key class: Notify.

Sending a general message:

/**
* Flash a general message.
*
* @param   string  $message
* @param   string  $type
* @param   string  $domain
* @return  $this
*/
public function message($message, $type = 'info', $domain = null)

Shortcut methods: info, success, error, warning, e.g.

/**
* Flash a warning message.
*
* @param   string  $message
* @param   string  $domain
* @return  object
*/
public function warning($message, $domain = null)
{
  $this->message($message, 'warning', $domain);

  return $this;
}

Example usage:

Notify::success("Yay!");
Notify::error("Doh!");
// Get messages
$messages = \App::get('notification')->messages();
echo '<pre>' . var_export($messages, true) . '</pre>';

Output:

array (
  0 => 
  array (
    'message' => 'Yay!',
    'type' => 'success',
  ),
  1 => 
  array (
    'message' => 'Doh!',
    'type' => 'error',
  ),
)

The notification container has id system-message-container and is inserted into the template via the command

<jdoc:include type="message" />

This will insert the message container and any notifications sent from PHP on page load (set via the Notify::*** commands). Here's is the code that creates the html: Document/Type/Html/Message.php

<div id="system-message-container">
	<dl id="system-message">
		<dt class="error">Error</dt>
		<dd class="error message">
			<ul>
				<li>Well fiddly-stix.</li>
			</ul>
		</dd>
        <dt class="success">Success</dt>
        <dd class="success message">
        <ul>
            <li>Posted comment.</li>
        </ul>
        </dd>
	</dl>
</div>

Client-side notification library

It is possible to send notifications from javascript that utilize the same container as server-side notifications. Within the app/templates/bmc/js/hub.js file, there are the two following functions:

// Main one to call explicitly
TPL.renderMessages = function(messages, success_duration = 4000, $container = $('#system-message-container'));

// Gets called automatically when messages added (renderMessages event)
TPL.setMessageDurations = function($container = $('#system-message-container'));

The default durations for error, warning and info messages are sticky and require the user to close them, while success messages have a default of 4 seconds before fading away. This can be changed via the success_duration argument. A setting of Infinity will make the success message sticky and require a manual close by the user. The argument messages should be of the form given above, i.e.

messages = [{'type': 'success', 
             'message': 'Congratulations, it didn't crash!'},
            {'type': 'error',
             'message': 'Well fiddly stix'}]

This is the format returned via the \App::get('notification')->messages() php code.

PHP -> JS notifications

In a non-ajax setting, the PHP will insert notifications in the appropriate container mentioned above prior to page render. The following javascript code in hub.js will then attach the appropriate durations to these notifications, as well as set up an event handler to capture future notification events.

TPL.setMessageDurations();
$(document).on("renderMessages", function() {
    TPL.setMessageDurations();
});

JS -> PHP -> JS notifications (i.e. through AJAX)

In an ajax setting, the PHP code should return an array containing status notifications and the html response, such as:

Notify::success('Something good happened!');
// ... more stuff happens
$response = Array(
    'status' => \App::get('notification')->messages(),
    'html' => $this->view->loadTemplate()
);
echo json_encode($response);
exit();

In JS, there are two ways to handle the response.

(1) Using $.get:

$.get(..., {}, function(response) {
    response = $.parseJSON(response);
    // Can now access response.status and response.html, e.g.
    if (response.status.length) {
		TPL.renderMessages(response.status);
	}
});

(2) Using $.ajax:

$.ajax({
   // ... other parameters
   dataType: "json",
   success: function(response, status, xhr) {
       // response has already been parsed from JSON due to dataType: "json" argument
       if (response.status.length) {
   	       TPL.renderMessages(response.status, Infinity); // This example makes the success messages sticky
       }
   }
});

For more documentation on controlling HubZero CMS responses, see their Hubzero\Http\Response documentation.