/ 
Bot-ChatBots-0.014
River stage one • 4 direct dependents • 4 total dependents
/ Bot::ChatBots::MojoPlugin

NAME

Bot::ChatBots::MojoPlugin - Mojolicious Plugin base for Bot::ChatBots

SYNOPSIS

package Bot::ChatBots::Whatever;
use Mojo::Base 'Bot::ChatBots::MojoPlugin';
1;

# in your Mojoliocious app
use Mojolicious::Lite;
plugin 'Bot::ChatBots::Whatever' => instances => [ ... ];
app->start;

DESCRIPTION

This module allows you to create Bot::ChatBots adapter plugins for Mojolicious. In particular, it provides a "register" method that is called by Mojolicious when you load this module as a plugin, taking care to initialize what has to be initialized and set a helper in the Mojolicious app.

The basic model is that with a single plugin you can manage a multitude of different chatbot "instances". This might not be really needed in the general case, as your program will probably serve one single chatbot at a time, but it's handy to have around.

This module is supposed to be used as a base class for your Mojolicious plugin, like this:

package Bot::ChatBots::Whatever;
use Mojo::Base 'Bot::ChatBots::MojoPlugin';
1;

This will provide you with:

  • automatic registration of the plugin via "register". This takes care to parse the input parameters and create instances accordingly;

  • automatically set the name of the helper in Mojolicious' app based on the package name (see "helper_name");

  • provide means to add new instances ("add_instance") and retrieve them ("instances").

METHODS

add_instance

$obj->add_instance($module, %args); # OR 
$obj->add_instance($module, \%args);

Add a new instance (creating it).

The first argument $module is used (via "load_module" in Bot::ChatBots::Utils) to load a class and call its new method with the provided %args. The prefix that is used for this loading is the same as ref $obj, so if your package name is Bot::ChatBots::Whatever, this is what will be used.

While creating the instance, the %args hash is extended with an additional pair with key app and value to whatever "app" provides back. This allows the instance to be able and refer back to the application object should this be needed (beware that this can create loops of references). This overrides any previously present value for app, sorry.

app

my $app = $obj->app;
$self->app($new_app_object);

Accessor for the application object. It is initialized by "register".

helper_name

my $name = $obj->helper_name;

Get the default name for the helper set by "register". This name is built by taking the last part of the package name (e.g. Whatever in package name Bot::ChatBots::Whatever), lowercasing it and pre-pending chatbots. (in the example, the result would be chatbots.whatever). You can override this in your derived class.

This method can also be called as a class method, e.g.:

my $name = Bot::ChatBots::Whatever->helper_name;

register

$obj->register($app, $conf);

Mojolicious::Plugin method for registering the plugin.

The registration process adds a helper function based on $conf->{helper_name} (if present) or "helper_name". For example, if the helper name is chatbots.whatever, the helper can be accessed by the application like this:

my $obj = app->chatbots->whatever;

This will allow you to call the other methods explained in this documentation.

Argument $conf is a hash reference supporting the following keys:

helper_name

to set the helper name, should you not like what "helper_name" gives back by default;

instances

an array reference containing definitions of instances, each represented as another array reference that is expanded to the arguments list for "add_instance".

instances

my $aref = $obj->instances;
$obj->instances($array_ref);

Accessor for defined instances, stored in an array reference.

BUGS AND LIMITATIONS

Report bugs either through RT or GitHub (patches welcome).

SEE ALSO

Bot::ChatBots.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.