Use MooRainbow as custom field in Joomla module or plugin settings panel

Each Joomla extension allow to configure the various options through the administrator settings panel. In case of modules and plugin the type of control available are very basic. In the majority of cases these control are more than enough for create a good interface. However, for some type of inputs, have a basic control, like a text edit, can work but it makes a little difficult for the user to insert the right value. One of this cases is the insertion of a color code. Luckily Joomla is a very flexible CMS an allow us to add custom control for improve the system usability. In this tutorial we are going to explain how to integrate the famous MooRainbow script into module and plugin settings panel for allow a better help in color selection.

MooRainbow is a script based to MooTools javascript framework that allow to visually select a color code using a dedicated popup window. Since Joomla already have inside the MooTools libraries it will be very fast to add our control inside the CMS.

First of all you need to download the MooRainbow package from this site. Once downloaded and extracted the package you'll need to get the files mooRainbow.js, mooRainbow.css and the entire images folder. All these three elements are necessary for the correct working of the script. Create your module or plugin installation package including these files. In our example we split the files using the following paths:

     assets/mooRainbow.css

     js/mooRainbow.js

     images/

Now you have to create the code for integrate this script as a custom control compatible with Joomla specifications. The code below is a ready-made snippet you can use immediately in your project. You have to change just some bit of them. For all the other additional explanations regarding how this code work you can check the Joomla documentation site. Now let's go to show the custom control code:

<?php

defined('_JEXEC') or die( 'Restricted access' );

class JFormFieldMyModuleNameColor extends JFormField
{
    protected $type = 'MyModuleNameColor';

    protected function getInput()
    {
        $document =& JFactory::getDocument();
        $base_path = JURI::root(true).'/modules/mod_my_module_name/';
        $color_code = '[255,0,0]';

        $document->addScript($base_path.'js/mooRainbow.js');
        $document->addStyleSheet($base_path.'assets/mooRainbow.css');
        
        if(strlen($this->value) == 7 && substr($this->value, 0, 1) == '#') 
        {
            $color_code = '['
                          .hexdec(substr($this->value, 1, 2))
                          .','
                          .hexdec(substr($this->value, 3, 2))
                          .','
                          .hexdec(substr($this->value, 5, 2))
                          .']';
        }
        
        $control_code =  'window.addEvent("domready", function() { '
                        .'new MooRainbow("'.$this->id.'", {'
                        .' id: "'.$this->id.'", '
                        .' startColor: "'.$color_code.'", '
                        .' imgPath: "'.$base_path.'images/", '
                        .'onChange: function(color) {'
                        .'    this.element.value = color.hex;'
                        .'}, '
                        .'}); '
                        .'});';

        $document->addScriptDeclaration($control_code);
            
        $html_code = '<input id="'.$this->id.'" name="'.$this->name.'" type="text" class="text_area" size="9" value="'.$this->value.'"/>';
          
        return $html_code;
    }
}

?>

Save this code into a file that you can call mymodulenamecolor.php and add to your extension installation package under the folder:

     elements/mymodulenamecolor.php

For have it working in your extension you have only to substitute the string  "MyModuleName" (written in red) with your module or plugin name. Also the path used inside this code refer to the "/modules/" folder. If you want to use it in a plugin just change the path into "/plugin/" folder (change the string also in the .php file name specified above). Now you have your custom control working. The last step is to use them through the .xml installation file. Module and plugin extension need to configure the administration settings panel using a special xml syntax inside the installation file just described. Basically you only need to modify the field options as showed below:

<config>
        <fields name="params" addfieldpath="/modules/mod_my_module_name/elements">
            <fieldset name="GENERAL">
                 <field name="field_color_control" type="mymodulenamecolor" size="10" default="#FFFFFF" label="Select Color" description="Set the color" />
            </fieldset>
        </fields>
</config>

Like the first snippet you have to change the string "mymodulename" (the red parts) with your module (or plugin) name.

This is all, no other additional changes are necessary. If your changes will work as expected you'll see the small window allowing to choose the color appear when you set the focus in the color text control itself. Enjoy!

Please note that these example will work in Joomla version 1.7 and (maybe) upper. The code for have it working on Joomla version 1.5 is similar but not completely compatible to allow this example working also in this "old" version.