Plugins

A plugin is any subset of the files of an application.

and we really mean any:

• A plugin is not a module, is not a model, it is not a controller, is not a view, yet it may contain modules, models, controllers and/or views.
• A plugin does not need to be functionally autonomous and it may depend on other plugins or specific user code.
• A plugin is not a plugins system and therefore has no concept of registration nor isolation, although we will give rules to try to achieve some isolation.
• We are talking about a plugin for your app, not a plugin for web2py.

So why is it called a plugin? Because it provides a mechanism for packing a subset of an app and unpacking it over another app (i.e. plug-in). Under this definition, any file in your app can be treated as a plugin.

When the app is distributed, its plugins are packed and distributed with it.

In practice, the admin provides an interface for packing and unpacking plugins separately from your app. Files and folder of your application that have names with the prefix plugin_name can be packed together into a file called:

web2py.plugin.name.w2p

and distributed together.

Any file can be made part of a plugin and these files are not treated by web2py any differently than other files. Except that files and folder in that have a plugin_ prefix are recognized by admin and grouper together by admin according to their postfix name. admin treats them differently, not web2py.

In practice we will only be concerned with two types of plugins:

• Component Plugins. These are plugins that contain components as defined in the previous section. A component plugin can contain one or more components. We can think for example of a plugin_comments that contains the comments component proposed above. Another example could be plugin_tagging that contains a tagging component and a tag-cloud component that share some database tables also defined by the plugin.
• Layout Plugins. These are plugins that contain a layout view and the static files required by such layout. When the plugin is applied it gives the app a new look and feel.

By the above definitions, the components created in the previous section, for example “controllers/contact.py”, are already plugins. We can move them from one app to another and use the components they define. Yet they are not recognized as such by admin because there is nothing that labels them as plugins. So there are two problems we need to solve:

• Name the plugin files using a convention, so that admin can recognize them as belonging to the same plugin
• If the plugin has model files, establish a convention so that the objects it defines do not pollute the namespace and do not conflict with each other.

Let’s assume a plugin is called name. Here are the rules that should be followed:

Rule 1: Plugin models and controllers should be called, respectively

• models/plugin_name.py
• controllers/plugin_name.py

and plugin views, modules, static, and private files should be in folders called, respectively:

• views/plugin_name/
• modules/plugin_name/
• static/plugin_name/
• private/plugin_name/

Rule 2: Plugin models can only define objects with names that start with

• plugin_name
• PluginName
• _

Rule 3: Plugin models can only define session variables with names that start with

• session.plugin_name
• session.PluginName

Rule 4: Plugins should include license and documentation. These should be placed in:

• static/plugin_name/license.html
• static/plugin_name/about.html

Rule 5: The plugin can only rely on the existence of the global objects defined in scaffolding “db.py”, i.e.

• a database connection called db
• an Auth instance called auth
• a Crud instance called crud
• a Service instance called service

Some plugins may be more sophisticated and have a configuration parameter in case more than one db instance exists.

Rule 6: If a plugin needs configuration parameters, these should be set via a PluginManager as described below.

By following the above rules we can make sure that:

• admin recognizes all the plugin_name files and folder as part of a single entity.
• plugins do not interfere with each other.

The rules above do not solve the problem of plugin versions and dependencies. That is beyond our scope.