Notify

Tom Taylor edited this page Mar 2, 2016 · 9 revisions
Clone this wiki locally

Notify is the authoring tool's notifications API, and has been designed to simplify the process of presenting information to the user at runtime.

Contents

The Notify Object

The Notify object itself is just a simple wrapper for other plugins to interface with - the functionality comes from these plugins.

Notify is accessible straight from the Origin object using Origin.Notify. The plugins themselves are functions stored on the Notify object. As such, they are called using Origin.Notify.PLUGIN_NAME() (passing any parameters needed).

Events

[NOT YET IMPLEMENTED]

The Plugins

All Notify plugins should adhere to a very straightforward API, so you don't need to learn how to use each one individually (with the exception of custom configuration settings).

All Notify plugins are stored on the Notify object, and referenced as follows: Origin.Notify.PLUGIN_NAME(DATA_OBJECT) -- where PLUGIN_NAME is the plugin you want to call (e.g. alert, console), and DATA_OBJECT is an object that defines the configuration data for your alert. As a minimum, all Notify plugins support the following data object attributes:

{
  type: String // Varies per plugin, but usually values like error, info etc.
  text: String // The text to display
  callback: Function // Called upon completion (i.e. popup closed or timed out)
}

Notify.alert()

Notify's alert is intended as a replacement for window.alert, giving you a nicely styled dialogue box with a plethora of configurable options, most notably the ability to categorise your alert into a number of different sub-types.

As it's powered by SweetAlert, you're able to use any settings that are defined in the SweetAlert documentation. Just set these on the data object you pass when calling Notify.

Alert Types

The Sweetalert library allows us to categorise alerts into a number of different types:

If no type is set on the config object, the user is shown a simple popup with a single button to dismiss it (comparable to the window.alert function). The popup can have a title, description, and callback function.

In addition to the plain alert popups, you can also set the type to: success, info, or error to add some more appropriate styling. All other functionality remains the same as the standard alert.

See below for more advanced configuration options.

Configuration Options

In addition to the defaults specified above, all alerts can be passed the following attributes in the data object:

{
  type: String // supports 'warning', 'error', 'success' and 'info'
  title: String // Text shown as the popup title
}
// See below for some useful SweetAlert options, check the documentation for the full list
{
  allowEscapeKey: Boolean // Dismiss the modal by pressing Esc
  customClass: String // Will be applied as a CSS class
  allowOutsideClick: Boolean // Dismiss popup by clicking outside it
  showConfirmButton Boolean // Show 'OK/Confirm'-button
  confirmButtonText String // 'Confirm'-button text label
  confirmButtonColor    String // 'Confirm'-button bg colour (HEX value)
  closeOnConfirm    Boolean // Keep popup open even after 'Confirm'-button clicked
  showCancelButton  Boolean // Show 'Cancel' button
  cancelButtonText  String // 'Cancel'-button text label
  closeOnCancel: Boolean // Closes popup on cancel button click
  timer: Number // Auto-close popup after set milliseconds
  html: Boolean // set to true to disable escaping of title/text values
}

Usage

Basic alert:

Origin.Notify.alert({
  title: "Popup title",
  text: "Main popup message."
});

or the shorthand:

Origin.Notify.alert("Main popup message.");

Success message:

Origin.Notify.alert({
  type: "success",
  title: "Plugin uploaded",
  text: "The plugin was uploaded successfully!"
});

Error message:

Origin.Notify.alert({
  type: "error",
  title: "Oops!",
  text: "An error occurred."
});

Notify.confirm()

This is just a quicker way of creating an alert (see above) which resembles the window.confirm 'yes/no'-type dialogue box. You can use any of the configuration options in the preceding section to customise a confirm.

As with alert, a string can be passed rather than an object.

Custom Confirm Types

Warning: Offers different styling more appropriate to warning messages than the default. Note that the title must be specifically set with this type (although does also work without a title).

An extension of confirm, this provides the same functionality, with the exception of the . The styling for this type also differs from the generic confirm type.

Usage

Basic confirm

Origin.Notify.confirm({
  title: "This will override the default title",
  text: "Leaving now will discard any unsaved data."
});

or the shorthand version:

Origin.Notify.confirm("Leaving now will discard any unsaved data.");

Warning confirm:

Origin.Notify.confirm({
  type: "warning",
  title: "This will override the default title",
  text: "Leaving now will discard any unsaved data."
});

Notify.console()

This plugin just provides a hook into the 'window.console' object, so should be familiar. Its purpose is to allow for other code to listen out for logging events (still TODO).

Extending Notify

Notify comes with a few handy plugins from the get-go, but it's been designed with pluggability in mind, so you can easily write your own plugin to meet your own needs.

To register a plugin for use with Notify, you need to call Notify's register function:

Origin.Notify.register(NAME String, TO_CALL Function);

NAME is the name used to call your plugin. This will be set on the Notify object (e.g. Notify.alert, Notify.console), so single words are preferable.

TO_CALL is the function to be called. This function should accept an object, and comply with the data specification in the API section above.