/ 
Nile-0.55
River stage zero No dependents
2 ++
/ Nile::Plugin

NAME

Nile::Plugin - Plugin base class for the Nile framework.

SYNOPSIS

DESCRIPTION

Nile::Plugin - Plugin base class for the Nile framework.

This module is the base class for plugins. You include it by using it which also makes itself as a parent class for the plugin and inherts the method setting which has the plugin setting loaded automatically from the config files.

Creating your first plugin Hello is simple like that, just create a module file called Hello.pm in the folder Nile/Plugin and put the following code in it:

    package Nile::Plugin::Hello;
    
    our $VERSION = '0.55';
    
    # this also extends Nile::Plugin, the plugin base class
    use Nile::Plugin;
    
    # optional our alternative for sub new {} called automaticall on object creation
    sub main {

        my ($self, $arg) = @_;
        
        # plugin settings from config files section
        my $setting = $self->setting();
        #same as
        #my $setting = $self->setting("hello");
        
        # get app context
        my $app = $self->app;

        # good to setup hooks here
        # run this hook after the "start" method
        $app->hook->after_start( sub { 
            my ($me, @args) = @_;
            #...
        });
        
    }
    
    sub welcome {
        my ($self) = @_;
        return "Hello world";
    }

    1;

Then inside other modules or plugins you can access this plugin as

        # get the plugin object
        $hello = $app->plugin->hello;
        
        # or
        $hello = $app->plugin("Hello");
        
        # if plugin name has sub modules
        my $redis = $app->plugin("Cache::Redis");
        
        # call plugin method
    say $app->plugin->hello->welcome;

    # in general, you access plugins like this:
    $app->plugin->your_plugin_name->your_plugin_method([args]);

Plugins will be loaded automatically on the first time it is used and can be load on application startup in the init method:

    $app->init({
        plugin  => [ qw(hello) ],
    });

Plugins also can be loaded on application startup by setting the autoload variable in the plugin configuration in the config files.

Example of plugin configuration to auto load on application startup:

    <plugin>

        <hello>
            <autoload>1</autoload>
        </hello>

    </plugin>

At the plugin load, the plugin optional method main will be called automatically if it exists, this is an alternative for the method new.

Inside the plugin methods, you access the application context by the injected method app and you use it in this way:

    my $app = $self->app;
    $app->request->param("name");
    ...
    $app->config->get("email");

Plugins that setup hooks must be set to autoload on startup for hooks to work as expected.

setting()

    # inside plugin classes, return current plugin class config settings
    my $setting = $self->setting();
    my %setting = $self->setting();

    # 
    # inside plugin classes, return specific plugin class config settings
    my $setting = $self->setting("email");
    my %setting = $self->setting("email");

Returns plugin class settings from configuration files loaded.

Helper plugin settings in config files must be in inside the plugin tag. The plugin class name can be lower case tag, so plugin Email can be email.

Exampler settings for email and cache plugins class below:

    <plugin>
        <email>
            <transport>Sendmail</transport>
            <sendmail>/usr/sbin/sendmail</sendmail>
        </email>
        <cache>
            <autoload>1</autoload>
        </cache>
    </plugin>

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.