FUEL CMS User Guide : Version 1.2.1


Simple Modules

Modules in FUEL can range from simple forms to a complex, interactive, multi-page interface. Simple modules don't require additional views and controllers to be created. Common examples of simple modules include events, news and job postings.

For more on creating a simple module, view the user guide's tutorial.

Configuring

A simple module usually contains a single model that maps to a database table (e.g. news). It is recommended that you create your model first (click here for an example). After your model has been created, you can activate and configure the module in the config/MY_fuel_modules.php file like so:

$config['modules']['example'] = array();

This will create a module that maps to the model named example_model and will have the friendly name of Example.

The above could actually be written a longer way as follows:

$config['modules']['example'] = array(
    'module_name' => 'Example',
    'module_uri' => 'example',
    'model_name' => 'example_model',
    'model_location' => '',
    'display_field' => 'name',
    'preview_path' => '',
    'permission' => 'example',
    'instructions' => 'Here you can manage the examples for your site.',
    'archivable' => TRUE,
    'nav_selected' => 'example'
);

Additional Configuration Parameters

Below is a list of all the parameters you can specify to further customize your module. Many of them base their default values on the key value specified in the config (e.g. example):

Preference Default Value Options Description
module_name The default value is a humanized version of the module key (e.g. a key of example = Example) None the friendly name of the module.
module_uri The default is the module key (e.g. example) None the URI path to the module that will appear after fuel.
model_name The default is the module key with the suffix of _model (e.g. example_model) None the name of the model
model_location By default it will look in the application/model folder. If a value is given it will look in the modules/{model_location}/model folder None The module folder location of the model.
view_location By default it will look in the application/views folder. If a value is given it will look in the modules/{view_location}/views folder None the location of the view files
display_field The default is the field name. If you do not have a field of name, you must specify a new field None The model field to be used for display purposes
js_controller The default is BaseFuelController None The name of the javascript controller. If an array is given, then the key of the array is considered the module folder to look in and the value the name of the controller. The js_controller_path will automatically be changed to the module's assets folder if no js_controller_path is provided. For more information on creating javascript controllers, visit the section on the javascript jqx Framework
js_controller_path The default is the path to the fuel module's asset folder (e.g. fuel/modules/fuel/assets/js/ None The base path of where to look for the controller file.
js_controller_params None None Parameters to pass to the jqx controller. They must be in the form of a json object
js None None additional javascript files to include for the module
preview_path None None The URI path to preview the information from the module in the website
views Built in FUEL pages None View files for the list, form and delete pages
permission The default is the module key (e.g. example) None The name of the permission that users must be subscribed to to have access to the module.
edit_method The default is find_one_array filtered on the id value passed to the form None The model's method to retrieve the information to edit.
instructions None None The instructions to provide users when creating or editing
filters None None Fields to filter the values in the list view
archivable TRUE Boolean Value TRUE/FALSE Saves to the archive table for later retrieval if you need to revert back
table_actions EDIT, VIEW, DELETE None The actions per row to include in the table view
item_actions save, view, publish, activate, delete, duplicate, create save, view, publish, activate, delete, duplicate, create, others The form level actions to include in the toolbar. The others action is a key / value array with the key being the FUEL URI and the value being the button label. It can be used to create additional custom buttons. Each button will submit the form information on the page to the link path of the button.
list_actions None None Other HTML to be displayed at the top above the list table
rows_selectable TRUE Boolean Value TRUE/FALSE A boolean value that will set the whole row to be clickable
precedence_col precedence None The name of the column to contain the custom precedence sorting information
clear_cache_on_save TRUE Boolean Value TRUE/FALSE Clears the cache upon saving new or updated values to a record
create_action_name Create None The name of the button to be used for creating an item
configuration None None Additional configuration files to load
nav_selected None None The left navigation item to be selected
table_headers None None The columns to use for the table view
default_col The default is the second column of the table (e.g. the one normally after the id column) None The default field to sort on
default_order asc asc, desc The default field ordering
sanitize_input TRUE Boolean TRUE/FALSE, string of "xss", "php", "template" OR "entities", OR an array for multiple values e.g. array('xss', 'php', 'template', 'entities'). See the FUEL configuration for changing the different sanitization callbacks. Cleans the input before inserting or updating the data source
sanitize_files (was sanitize_images) TRUE Boolean Value TRUE/FALSE uses xss_clean function on images
displayonly None Boolean Value TRUE/FALSE Will only display the data and not allow you to save it
language None None Additional language files to load
language_col language None The column name that contains the language key value
hidden FALSE Boolean Value TRUE/FALSE If set to TRUE, it will hide the module in the admin menu
disabled FALSE Boolean Value TRUE/FALSE If set to TRUE, it will hide the module in the admin menu as well as show a 404
icon_class None None The CSS icon class to associate with the module
folder None None The advanced module folder in which it lives in
exportable FALSE Boolean Value TRUE/FALSE Will display an "Export" button on the list view page that will allow users to export the currently filtered list data
limit_options array('25' => '25', '50' => '50', '100' => '100') array The "Show" options displayed in the list view
advanced_search FALSE Boolean Value TRUE/FALSE If TRUE, this will display model filters in an advanced search menu
disable_heading_sort FALSE Boolean Value TRUE/FALSE If TRUE, this will disable heading sorting on the list view
description None None A description value that can be used in the site docs

The Model

The module's model is the most important piece of a module. It is what drives the the saving, form and extra interactions needed for the module to work. A module should extend the abstract Base_module_model class which is a child of the MY_Model class and is found in the modules/fuel/model folder. Custom record object should extend the Base_module_record

There are several methods that you can add/overwrite to give you greater functionality for your module (view the tutorial for more information).

Additionally, there are several hooks you may want to use that allow you to insert functionality during the saving and deleting process of a modules record.

The Views

Simple modules are made up of several views:

Module Overwrites

Module overwrites allow for you to overwrite existing module parameters. For example, if you'd like to overwrite the built-in FUEL fuel_pages_model to incorporate your own model hook you've added to the MY_pages_model, you can do so like so:

$config['module_overwrites']['pages']['model_name'] = 'MY_pages_model';