NAME

Mojolicious::Plugin::Notifications - Event Notifications for your Users

SYNOPSIS

  # Register the plugin and several engines
  plugin Notifications => {
    Humane => {
      base_class => 'libnotify'
    },
    JSON => 1
  };

  # Add notification messages in controllers
  $c->notify(warn => 'Something went wrong');

  # Render notifications in templates ...
  %= notifications 'humane';

  # ... or in any other responses
  my $json = { text => 'That\'s my response' };
  $c->render(json => $c->notifications(json => $json));

DESCRIPTION

Mojolicious::Plugin::Notifications supports several engines to notify users on events. Notifications will survive redirects and can be served depending on response types.

METHODS

Mojolicious::Plugin::Notifications inherits all methods from Mojolicious::Plugin and implements the following new one.

register

  plugin Notifications => {
    Humane => {
      base_class => 'libnotify'
    },
    HTML => 1
  };

Called when registering the plugin.

Accepts the registration of multiple engines for notification responses. Configurations of the engines can be passed as hash references. If no configuration should be passed, just pass a scalar value.

All parameters can be set either as part of the configuration file with the key Notifications or on registration (that can be overwritten by configuration).

HELPERS

notify

  $c->notify(error => 'Something went wrong');1
  $c->notify(error => { timeout => 4000 } => 'Something went wrong');

Notify the user about an event. Expects an event type and a message as strings. In case a notification engine supports further refinements, these can be passed in a hash reference as a second parameter. Event types are free and its treatment is up to the engines, however notifications of the type debug will only be passed in development mode.

notifications

  %= notifications 'humane' => [qw/warn error success/];
  %= notifications 'html';

  $c->render(json => $c->notifications(json => {
    text => 'My message'
  }));

Serve notifications to your user based on an engine. The engine's name has to be passed as the first parameter and the engine has to be registered in advance. Notifications won't be invoked in case no notifications are in the queue and no further engine parameters are passed. Engine parameters are documented in the respective plugins.

ENGINES

Bundled engines

The following engines are bundled with this plugin: HTML, JSON, Humane.js, and Alertify.js,

Writing your own engine

A notification engine is a simple Mojolicious::Plugin, having a register method and a notifications method. The register method is called when the engine is loaded and can be used to establish further configurations, helpers, hooks etc. There is no need to define anything in the method.

The notifications method will be called whenever notifications are rendered. The first parameter passed is the plugin object, the second parameter is the current controller object and the third parameter is an array reference containing all notifications as array references. The first element of the notification is the notification type, the last element is the message. An optional second element may contain further parameters in a hash reference.

All parameters passed to the notifications helper following the engine's name are appended.

The bundled engines can serve as good examples on how to write an engine, especially the simple HTML engine.

AVAILABILITY

  https://github.com/Akron/Mojolicious-Plugin-Notifications

COPYRIGHT AND LICENSE

Copyright (C) 2014, Nils Diewald.

Part of the code was written at the Mojoconf 2014 hackathon.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

cpanm Mojolicious::Plugin::Notifications

perl -MCPAN -e shell
install Mojolicious::Plugin::Notifications