Add a JQuery plugin to FUEL CMS module admin page

When creating a new FUEL CMS module, you get a fully fledged administration CRUD when the module is added to MY_fuel_modules.php. As good as that is, there’s often a need to extend its javascript capabilities in certain situations.

FUEL CMS makes use of a javascript framework named JQX. Its employment in the FUEL admin allows additional code and plugins to be added.

Firstly, let’s demonstrate how JQuery can be hooked into the existing HTML & PHP of the admin. We would want to assign a CSS id or classname to a given field or fields as a selector for JQuery. If the application of a plugin is to a single field, then FUEL CMS assigns an HTML id attribute to the fields within the create / edit page of the module anyway, so that’s catered for. If you wish to assign a custom class name then this can be done within the model of the module, using FUEL’s form_fields() method:

$fields['yourfield']['class'] = 'your-class-name';

So, class or id, we are ready to add functionality via JQX.

First off, we need to create a javascript controller file, using the same name of the module. For example, if the module in hand were named “news” we would create a file called ‘NewsController.js’ and add it to the /fuel/modules/fuel/assets/js/fuel/controller folder. This naming convention allows FUEL to use the script without any further intervention! So when you browse to (for example) /your-site/fuel/news/edit/1 any code within the NewsController.js will be executed. However, the code in that file should be an extension of the existing JQX controller class! So the javascript within should look something like:

   1:  fuel.controller.NewsController = jqx.createController(fuel.controller.BaseFuelController, {

   2:      

   3:      init: function(initObj){

   4:          this._super(initObj);

   5:      },

   6:      

   7:      add_edit: function(){

   8:          this._super();

   9:      }    

  10:  });

This example does nothing but create a new class. To make use of it at all though, we need to add the following to MY_fuel_modules in /config:

$config['modules']['news'] = array(
'js_controller' => 'fuel.controller.NewsController'
);

You may have many other module configurations in this array, but 'js_controller' is required to load the js file in the module. With that done, how do we apply a plugin to a field in the create / edit form?

Again, by convention, the JQX framework looks for plugins on a specific path, in v0.93 of FUEL CMS it is in /fuel/modules/fuel/assets/js/fuel/jquery/plugins. Add the plugin to that folder, and then add the following to the beginning of the js controller script, before the class initialisation (NB the .js file extension is not required):

jqx.load('plugin', 'charCount');

This plugin (charCount.js) happens to be a character countdown script which I want to apply to a textarea field called “summary” within the news module. To instance it we need to add a line to the add_edit function, and create a function that will call the plugin and apply it to the field in question. So our controller code becomes:

   1:  jqx.load('plugin', 'charCount');

   2:             

   3:  fuel.controller.NewsController = jqx.createController(fuel.controller.BaseFuelController, {

   4:      

   5:      init: function(initObj){

   6:          this._super(initObj);

   7:      },

   8:      

   9:      add_edit: function(){

  10:          this._super();

  11:          this.charCounter();

  12:      },

  13:      charCounter: function() {

  14:          // applies char countdown to summary field

  15:          $('#summary').charCount({

  16:              allowed: 120,        

  17:              warning: 20,

  18:              counterText: 'Chars left: '    

  19:          });

  20:      }    

  21:  });

The add_edit() now invokes the charCounter() function on line 11. In turn, this then applies (via JQuery) the character counting plugin code to an element with id “summary”, although as noted above, we could have used a class name instead of an id as a selector. If you are adding more plugins to the module, just use jqx.load() and do something similar with the add_edit function to invoke the plugin.

Powerful stuff, JQX!

I've added a similar walkthrough of adding JQuery functionality to admin modules here.