NAME

Ado::Manual::Plugins - Ado plugins and how to write an Ado::Plugin

DESCRIPTION

@Ado::ISA=qw(Mojolicious). It is distributed together with a few plugins to make it usable as a basic Mojolicious application. Theoretically all of the plugins, distributed with Ado could be disabled so you can start your project only as a bare (but full) Mojolicious application, if you wish. Later you can decide to enable some of them and eventually add (your own) Mojolicious or Ado plugins. Here is how it looks.

PLUGINS

Ado comes with the following default plugins. They can be used as examples and for inspiration.

• Ado::Plugin::AdoHelpers - Default Ado helpers

• Ado::Plugin::Auth - Authenticate users

• Ado::Plugin::I18n - Internationalization and localization for Ado

• Ado::Plugin::MarkDownRenderer - Render markdown to HTML

• Ado::Plugin::Routes - Keep routes in their own configuration file separately

• Ado::Control::Test - A controller used for testing Ado (not a plugin by it self)

The following plugins are written by me and are distributed separately. You can install and use them in your application. Please help make them better.

• Ado::Plugin::Admin - system (site) administration user interface.

• Ado::Plugin::Site - Manage your Sites.

• Ado::Plugin::Vest - Messaging services for an Ado system!

Do not hesitate to contact the Ado team and request your plugin to be added to the above list.

WRITING A PLUGIN

There is almost nothing special about writing an Ado::Plugin. The only difference between Ado and Mojolicious plugins is that Ado plugins can retrieve their settings from their own configuration files.

The configuration file must be named after the respective plugin. A plugin Ado::Plugin::Hello (when installed) will search its configuration in app->home->rel_dir('etc/plugins/hello.conf'). depending on the current mode ($ENV{MOJO_MODE}). The file app->home->rel_dir('etc/plugins/hello.$ENV{MOJO_MODE}.conf') will also be loaded and will override all settings from app->home->rel_dir('etc/plugins/hello.conf'). The file must return a HASHREF. See the code of the listed plugins below for examples of how and what can be done in a plugin.

To create your own plugin do the following (Example):

• Create one or more tables to be used by your plugin in etc/ado.sqlite

  CREATE TABLE blog (
    id INTEGER PRIMARY KEY,
    title VARCHAR NOT NULL UNIQUE,
    body TEXT NOT NULL,
    published BOOL DEFAULT '0',
    deleted BOOL NOT NULL DEFAULT '0', 
    user_id INTEGER REFERENCES users(id), 
    group_id INTEGER REFERENCES groups(id), 
    permissions VARCHAR(10) DEFAULT '-rwxr-xr-xr' 
  );
  CREATE INDEX blog_published ON blog(published);
  CREATE INDEX blog_deleted ON blog(deleted);

• Add some dummy records.

  INSERT INTO blog(title,body,user_id,group_id) 
  VALUES('Hey','Hello world',3,3);
  INSERT INTO blog(title,body,user_id,group_id) 
  VALUES('Hey You','Hello Universe',3,3);

• Generate the files for the plugin. These are the files which you will edit :).

  $ cd ~/opt/public_dev
  $ ado generate adoplugin -n Blog --crud -t blog

  The above command will generate the needed files for an ado plugin which can even be uploaded to and subsequently downloaded from CPAN. CPAN is the best open source dependency management system. You can also use Stratopan if you wish.

Ado uses Ado::Build and Ado::BuildPlugin which extend Module::Build. They were created to add some custom actions and handle the additional templates,log and public directories in Ado root folder. The file tree looks like the following:

~/opt/public_dev/Ado-Plugin-Blog$ tree
.
├── Build.PL
├── etc
│   └── plugins
│       └── blog.conf
├── lib
│   └── Ado
│       ├── Control
│       │   └── Blog.pm
│       └── Plugin
│           └── Blog.pm
├── templates
│   └── blog
│       ├── create.html.ep
│       ├── delete.html.ep
│       ├── list.html.ep
│       └── read.html.ep
└── t
    └── plugin
        └── blog-00.t

No worries, your plugin has everything needed to be installed from CPAN. Ado::Plugin::Vest was started using this command.

Ado can be stripped down to a bare Mojolicious application by not loading any plugins. And Ado can be extended infinitely just by adding helpers, conditions, routes, templates and injecting code into hooks from plugins. This is true for any Mojolicious application.

SPONSORS

The original author

SEE ALSO

Mojolicious::Plugins, Mojolicious::Plugin,

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.