A Gallery 3 module is a collection of models, views, controllers, helpers, libraries and config files gathered in a single directory located under gallery3/modules. All of those elements are optional and are used to add specific features and capabilities to Gallery 3. There is only one mandatory file in a Gallery 3 module and that is the module.info file that contains the name, description and version of the module.
The simplest module looks like this:
hello_world └── module.info
Here's what the module.info file could contain:
name = "Hello world!" description = "This module does nothing!" version = 1
This module can be activated and deactivated in the Admin > Modules interface, but won't actually do anything. To add functionality to the module, you can add controllers, event hooks, rest hooks, search hooks, theme hooks, RSS hooks, task hooks, block hooks, an installer and more. Each of these bits of functionality are easy to add and mostly independent of each other so it's simple to extend Gallery 3 in many directions without writing much code.
Gallery 3 module hooks are very simple. Each hook system expects there to be a specially named helper with specially named functions in them. Once you understand the pattern it's simple and easy to add a new hook with just a few lines of code.
For example, if you'd like to print out the words Hello world at the top of every album, you would need to add a theme hook to your module. In the helpers directory, you'd create a file called hello_world_theme.php containing the following code:
<?
class hello_world_theme {
static function album_top($theme) {
return "Hi";
}
}
A few things to note about this:
There are many other theme hooks, this is just a simple example. But with these two files you can affect many useful changes in Gallery 3.
A more complex Gallery 3 module might look like this:
modules
└── search
├── controllers
│ └── search.php
├── helpers
│ ├── search_event.php
│ ├── search_installer.php
│ ├── search.php
│ ├── search_task.php
│ └── search_theme.php
├── models
│ └── search_record.php
├── module.info
└── views
├── search.html.php
└── search_link.html.php
The search module has 1 controller, accessible at the /search url. It has an event hook at search_event.php, and installer at search_installer.php, an admin task at search_task.php and a theme hook at search_theme.php. It implements a single model in search_record.php and has two views.
A module can be installed, activated and deactivated. In Gallery 3.0, a module cannot be uninstalled, but there are plans to implement that in Gallery 3.1 and beyond.
At install time, the module is responsible for creating and populating any necessary database tables, registering graphics rules and setting module variables. Activation and deactivation of a module is handled by the Gallery 3 framework. In the future when uninstalling is supported, the module can remove any database tables that it created.
The following hooks are available for modules to implement. Any module can introduce its own hooks, but the ones listed below are the ones that are supported by the official Gallery 3 modules.
These are general purpose hooks that are used in a variety of places throughout the system to indicate that an activity of some kind has happened, is about to happen, or has completed. Any module can initiate an event, and any module can handle an event. Multiple modules can handle a single event, it's up to the individual modules to make sure that they don't interfere with each other. The following events are triggered by the official Gallery 3 modules:
An attempt to detail all of the events currently defined in Gallery3 can be found on the Event Hooks page.
Theme hooks are called directly by the theme itself. Not every theme will call every hook, and not every theme page will call every hook. The theme will call each hook as appropriate. For example, when rendering an album page the theme may call the head, header_top, header_bottom, page_top, album_top, thumb_top, thumb_info, thumb_bottom, album_bottom, page_bottom, and credits hooks in that order. Some of those hooks (for example thumb_top) might be called multiple times.
Each implementation of a theme hook returns a bit of HTML that will be rendered on the page at the spot where the theme calls the hook. If multiple modules render HTML at that same spot, the module loading order will determine the order of the HTML and it's up to the modules to not interfere with each other.
Blocks are visual elements that a module can provide for the theme. In Gallery 3.0 there are two types: site blocks and admin blocks. Site blocks are typically shown in the sidebar for the site theme, and admin blocks are typically shown in the sidebar for the admin site.
To register blocks for a module, create a <module_name>_block helper with the following methods. Note that in 3.1, these hooks will likely get turned into module events.
The RSS module allows other modules to provide their own feeds. To add an RSS feed, create a <module_name>_rss helper with the following methods. Note that in 3.1, these hooks will likely get turned into module events.
The Admin > Maintenance interface provides a way to run long lived tasks. Each task is a tiny state machine that is triggered many times. Each time it's triggered, a task should spend no more than 1-2 seconds doing a small amount of work, then return. It will get called again when appropriate. Usually the task is triggered by Javascript in the web browser so that it can display results to the end user and make sure that no single operation takes too much time and resources on the server
To add a task, create a <module_name>_task helper with the following methods. Note that in 3.1, these hooks will likely get turned into module events.
Module installation and upgrading is handled by a special hook. If a module does not provide its own code to handle installing and upgrading, the framework will perform the bare necessities required. In many modules, this is perfectly sufficient, however if your module requires additional operations such as creating or altering database tables or module variables, then an installer is required.
To create an installer, create a <module_name>_installer helper with the following methods:
The rest module provides a RESTful API to Gallery 3 that provides much of the fundamental Gallery 3 functionality via a remote API. This is reasonably well documented in Gallery3:API:REST
