/ 
Mojolicious-Plugin-Notifications-1.03
River stage zero No dependents
/ Mojolicious::Plugin::Notifications

NAME

Mojolicious::Plugin::Notifications - Frontend Event Notifications

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 multiple 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');
$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.

The engine's name will be camelized. If no namespace is given, the default namespace is Mojolicious::Plugin::Notifications.

In case no engine name is passed to the notifications method, an assets object is returned, bundling all registered engines' assets for use in the AssetPack pipeline.

# Register Notifications plugin
app->plugin('Notifications' => {
  Humane => {
    base_class => 'libnotify'
  },
  Alertify => 1
});

# Register AssetPack plugin
app->plugin('AssetPack');

# Add notification assets to pipeline
app->asset('myApp.js'  => 'myscripts.coffee', app->notifications->scripts);
app->asset('myApp.css' => 'mystyles.scss', app->notifications->styles);

%# In templates embed assets ...
%= asset 'myApp.js'
%= asset 'myApp.css'

%# ... and notifications (without assets)
%= notifications 'humane', -no_include;

The asset helper option is experimental and may change without warnings!

ENGINES

Mojolicious::Plugin::Notifications bundles a couple of different notification engines, but you can easily write your own engine.

Bundled engines

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

HOOKS

app->hook(
  before_notifications => sub {
    my ($c, $notes) = @_;
    $c->app->log('Served ' . $notes->size . ' notifications to ' . $c->stash('user'));
  });

This hook is emitted before any notifications are rendered. The hook passes the current controller object and a Mojo::Collection object including all notes. The hook is emitted no matter if notifications are pending.

This hook is EXPERIMENTAL!

SEE ALSO

If you want to use Humane.js without Mojolicious::Plugin::Notifications, you should have a look at Mojolicious::Plugin::Humane, which was the original inspiration for this plugin.

Without my knowledge (due to a lack of research by myself), Mojolicious::Plugin::BootstrapAlerts already established a similar mechanism for notifications using Twitter Bootstrap (not yet supported by this module). Accidentally the helper names collide - I'm sorry for that! On the other hands, that makes these modules in most occasions compatible.

HINTS

As flash information is stored in the session, notifications may be lost in case the session expires using session(expires => 1).

AVAILABILITY

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

COPYRIGHT AND LICENSE

Copyright (C) 2014-2019, 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.