/ 
Ado-0.921
River stage zero No dependents
/ Ado::Plugin

NAME

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

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 Ado::Command::generate::adoplugin to generate all the files for you.

DESCRIPTION

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

ATTRIBUTES

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

app

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

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

config_dir

Path to plugin directory.

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

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

config_classes

Returns a hash reference containing file-extension => 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 Mojolicious::Plugin::Config API.

ext

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

my $ext  = $self->ext;

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.

name

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

$self->name # MyPlugin

METHODS

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

config

The configuration which is for the currently registering plugin only. In 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 "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');

initialise

Used to initialise you plugin and reduce boilerplate code.

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

This method should be the first invoked in your "register" in Mojolicious::Plugin method. If you need to do some very custom stuff, you are free to implement the initialisation yourself.

Currently this method does the following:

  • Merges configurations (invokes "config").

  • Pushes @{$conf->{namespaces}} to $app->routes->namespaces if additional namespaces are defined in configuration file.

  • Loads routes if defined in configuration file.

  • Pushes the plugin templates directory to @{app->renderer->paths} (if it exists and is not the same as Ado's one) so the templates can be found by Ado while developing your plugin.

  • Pushes the plugin public directory to @{app->static->paths} (if it exists and is not the same as Ado's one) so the templates can be found by Ado while developing your plugin.

  • Returns ($self, $app, $config).

Look at some of the configuration files of the plugins that come with Ado.

SEE ALSO

Ado::Manual::Plugins, Mojolicious::Plugin, Ado::Plugin::AdoHelpers, Ado::Plugin::Auth, Ado::Plugin::I18n, Ado::Plugin::MarkdownRenderer, Ado::Plugin::Routes, Ado::Command::generate::adoplugin.

AUTHOR

Красимир Беров (Krasimir Berov)

COPYRIGHT AND LICENSE

Copyright 2013-2014 Красимир Беров (Krasimir Berov).

This program is free software, you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3 (LGPL-3.0). You may copy, distribute and modify the software provided that modifications are open source. However, software that includes the license may release under a different license.

See http://opensource.org/licenses/lgpl-3.0.html for more information.