Modules
Modules are a way for you to extend the functionality of FUEL. The term modules is used rather loosely and it is entirely possible to nest modules within another module (sometimes called sub-modules). We refer to these types of modules as advanced modules. In fact, FUEL is no more then an advanced module itself.
Most of the time however, modules are simply just data models (simple modules) with a form interface to change values.
Installation
One of the bigger changes in FUEL v1.0 was the removal of all the extra bundled advanced modules. The reason was to keep the initial FUEL install smaller, as well as provide separate GIT repository versioning and issue tracking for each. A list of some available modules can currently be found at https://github.com/daylightstudio. Because of this change, it was deemed necessary to make the installation and updating process of advanced modules a little easier going forward.
Using GIT Submodules
We like to lean on GIT as much as possible for the updating of advanced modules and so we've added a couple command line tools to make this a little easier. The first is to use GIT to add a submodule to your installation in your fuel/modules/{module} folder. Adding the advanced module as a GIT submodule will allow you to run updates independent of your main FUEL CMS repository. Adding a submodule can be done one of two ways. The first way uses the native "submodule" command from GIT, and the second uses the FUEL installer "add_get_submodule" controller method. To get started, you first need to open up a terminal window and "cd" (change directory) to the installation directory (where the index.php CodeIgniter bootstrap file exists alongside the "fuel" folder). Then run the commands below where "php" references the path to your PHP interpreter.
// GIT >php git submodule add git://github.com/daylightstudio/FUEL-CMS-Blog-Module.git fuel/modules/blog // FUEL >php index.php fuel/installer/add_git_submodule git://github.com/daylightstudio/FUEL-CMS-Blog-Module.git blog
If your git repo path has a "@" in it, change it to a "-at-" or else you will get a "The URI you submitted has disallowed characters" error.
Phil Sturgeon of PyroCMS fame has a good article on using submodules.
Finalizing the Installation
After adding the folder to your fuel/modules folder either manually or via GIT, you may need to finalize the installation by running some additional SQL statements. These SQL statements can be found in your modules "install" folder. FUEL provides a simpler way to install both the SQL and any necessary permissions for the module that can be assigned to other users. To do so, you need to open up a terminal window and "cd" (change directory) to the to the installation directory (similar to above). Then run the following:
>php index.php fuel/installer/install blog
Uninstall
If you need to uninstall the module, you can delete the folder and then run the following command to clean up any data associated with the module:
>php index.php fuel/installer/uninstall blog
The "ENVIRONMENT" constant defined in your index.php bootstrap file must be set to "development" in order install modules via the command line
Configuring Your Own Installation
If you create your own advanced module and would like to share it with the community, you can create your own install configuration to help with the installation process. To do so, you can create an install/install.php file with the following parameters in it:
- name
- version
- author
- company
- license
- copyright
- author_url
- description
- compatibility
- instructions
- permissions
- migration_version
- install_sql
- uninstall_sql
- repo
For example, the Blog module has the following install configuration.
fuel/modules/blog/install/install.php
$config['name'] = 'Blog Module';
$config['version'] = BLOG_VERSION;
$config['author'] = 'David McReynolds';
$config['company'] = 'Daylight Studio';
$config['license'] = 'Apache 2';
$config['copyright'] = '2012';
$config['author_url'] = 'http://www.thedaylightstudio.com';
$config['description'] = 'The FUEL Blog Module can be used to create posts and allow comments in an organized manner on your site.';
$config['compatibility'] = '1.0';
$config['instructions'] = '';
$config['permissions'] = array('blog/posts', 'blog/comments', 'blog/categories', 'blog/users');
$config['migration_version'] = 0;
$config['install_sql'] = 'fuel_blog_install.sql';
$config['uninstall_sql'] = 'fuel_blog_uninstall.sql';
$config['repo'] = 'git://github.com/daylightstudio/FUEL-CMS-Blog-Module.git';
Note that you can use CodeIgniter's migrations for managing SQL versioning as an alternative to using install_sql and uninstall_sql parameters.