NAME

Mojolicious::Plugin::Util::Callback - Reverse Helpers for Mojolicious

SYNOPSIS

  # Mojolicious
  $app->plugin('Util::Callback');

  # Mojolicious::Lite
  plugin 'Util::Callback';

  # In app or plugin
  $self->callback(get_cached_profile => sub {
    my ($c, $name) = @_;
    return $c->cache->get( $name );
  });

  # In plugin or controller
  my $profile = $self->callback(
    get_cached_profile => 'Akron'
  );

DESCRIPTION

Callbacks are similar to helpers, with slightly different semantics. While helpers are usually established by plugins and called by controllers, callbacks are usually called by plugins and established by other plugins or inside the main application.

A typical usecase for callbacks is the database agnostic access to data via plugins.

HELPERS

callback

  # Call a callback
  my $profile = $self->callback(
    get_cached_profile => 'Akron'
  );

  # Establish a single callback
  $self->callback(get_cached_profile => sub {
    my ($c, $name) = @_;
    return $c->cache->get( $name );
  });

Establish or release a callback. To release a callback, just pass the unique name of the callback and all necessary parameters to the helper. To establish a callback, pass the unique name of the callback and a code reference to the helper. This code reference will be invoked each time the callback is released, and all parameters will be passed, prepended by the controller object.

An additional -once flag when establishing single or multiple callbacks (see the example below) indicates, that the callbacks are not allowed to be redefined later.

If there is no callback defined for a certain name, undef is returned on releasing.

To establish multiple callbacks, e.g. at the start of the registration routine of a plugin, pass an array reference of callback names followed by a hash reference containing the callbacks to the helper. All callback references will be deleted from the hash, while the rest will stay intact.

  # Inside 'MyUserPlugin'
  sub register {
    my ($self, $app, $param) = @_;

    # Establish Util::Callback plugin
    $app->plugin('Util::Callback');

    # Accept callbacks defined by parameter
    $app->callback(
      ['get_cached_profile','get_db_profile'] => $param, -once
    );

    # Establish database agnostic 'fetch_profile' helper
    $app->helper(
      fetch_profile => sub {
        my $c = shift;
        my $user_name = shift;

        # Return profile from cache or from db, if cache fails,
        #   either because no cache callback is established or
        #   the user is not in cache.
        return
          $c->callback(get_cache_profile => $user_name) ||
          $c->callback(get_db_profile => $user_name);
      }
    );
  };

  # In a Mojolicious::Lite app
  plugin MyUserPlugin => {
    get_db_profile => sub {
      my ($c, $name) = @_;
      return $c->db->load( $name );
    }
  };

  # In another plugin (e.g. for caching) or later in the application
  $app->callback(
    get_cached_profile => sub {
      my ($c, $name) = @_;
      return $c->cache->get( $name );
    }
  );

  # In controller, app or template
  my $profile = $c->fetch_profile('Akron');

If the callback to be defined by parameters is given the -once flag, this will be saved as a signature. The next established callback can't be overwritten, no matter if it is established without a -once flag.

DEPENDENCIES

Mojolicious (best with SSL support).

AVAILABILITY

  https://github.com/Akron/Mojolicious-Plugin-Util-Callback

COPYRIGHT AND LICENSE

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