view release on metacpan or  search on metacpan

lib/Ado/Plugin.pm  view on Meta::CPAN

=pod

=encoding utf8

=head1 NAME

Ado::Plugin - base class for Ado specific plugins.


=head1 SYNOPSIS

Create your plugin like this:

  # CamelCase plugin name is recommended.
  package Ado::Plugin::MyPlugin;
  use Mojo::Base 'Ado::Plugin';

  sub register {
    my ($self, $app, $conf) = shift->initialise(@_);

    # Your magic here!..

    return $self;
  }

but better use L<Ado::Command::generate::adoplugin> to
generate all the files for you.

=head1 DESCRIPTION

Ado::Plugin is a base class for Ado specific plugins.
It provides some methods specific to L<Ado> only.

=head1 ATTRIBUTES

Ado::Plugin inherits all attributes from L<Mojolicious::Plugin>
and provides the following for use by subclasses.

=head2 app

  my $app  = $self->app;
  $command = $self->app(MyApp->new);

Application for plugin, defaults to a L<Mojo::HelloWorld> object.

=head2 config_dir

Path to plugin directory.

  my $config_dir   = $self->config_dir;
  $self->config_dir($app->home->rel_dir('etc/plugins'));

Defaults to C<etc/plugins> relative to the plugin base directory, see L</home_dir>.
This works both while developing a plugin and after installing the plugin.

=head2 config_classes

Returns a hash reference containing C<file-extension =E<gt> class> pairs.
Used to detect which configuration plugin to use depending on the file extension.
The default mapping is:

    {   conf => 'Mojolicious::Plugin::Config',
        json => 'Mojolicious::Plugin::JSONConfig',
        pl   => 'Mojolicious::Plugin::Config'
    };

This attribute allows you to use your own configuration plugin as far as it
supports the L<Mojolicious::Plugin::Config> API.

=head2 ext

Extension used for the plugin specific configuration file. defaults to 'conf';

  my $ext  = $self->ext;

=head2 home_dir

  my $plugin_home = $self->home_dir;

The plugin base directory.
This path works both while developing a plugin and after installing the plugin.
Using the guessed value allows you to have Ado plugins installed at arbitrary paths,
possibly not the same where Ado is installed.
As noted elsewhere, Ado plugins can be distributed as separate Ado applications and used
together with other plugins to create custom enterprise-grade systems.

=head2 name

The name - only the last word of the plugin's package name.

  $self->name # MyPlugin

=head1 METHODS

Ado::Plugin inherits all methods from L<Mojolicious::Plugin>
and provides the following for use by subclasses.

=head2 config

The configuration which is for the currently registering plugin only.
In L<Ado> every plugin can have its own configuration file.
When calling this method for the first time it will parse and merge
configuration files for the plugin. Options from mode specific
configuration file will overwrite options found in the generic file.
You usually do not need to invoke this method directly since it is
invoked in L</initialise>.

  # everything in $self->config_dir.'/$my_plugin.conf'
  # and/or   $self->config_dir.'/$my_plugin.$mode.conf'
  my $config = $self->config;

  #get a config value
  my $value = $self->config('key');
  #set
  my $config = $self->config(foo => 'bar');

=head2 initialise

Used to initialize you plugin and reduce boilerplate code.