FUEL CMS User Guide : Version 1.5.2


Javascript

FUEL CMS provides several ways for you to insert javascript functionality for various aspects of the CMS. jQuery is automatically loaded as are most of the jQuery UI libraries for you to take advantage of. A list of all the javascript files loaded in the admin by default can be found on the configuration page. The following are topics which discuss adding javascript to FUEL CMS:

FUEL Configuration

If you'd like to include a javascript file for every page in the CMS, you can add it like so in your fuel/application/config/MY_fuel.php file:

...
$config['fuel_javascript'][] = array('my_js');
...

The javascript file's path will be relative to your assets/js/ folder.

The asset helpers js() function is used for rendering the javascript which means the ending ".js" is not required.

Modules

To add javascript for an entire module, you can add a 'js' parameter to your module's initialization parameters in your fuel/application/config/MY_fuel_modules.php like so:

$config['modules']['my_module'] = array(
	'js' => array('my_js')
);

Forms

FUEL CMS 1.0 offers several new ways to incorporate javascript specific to your forms using the Form_builder class:

add_js() Method

You can use the Form_builder class add_js() method like so:

$this->form_builder->add_js('my_js');

Using the 'js' Parameter

You can add the 'js' parameter to your fields like so to load in a my_js javascript file (must be an array or a string ending with ".js"):

...
$fields['my_field'] = array('label' => 'my_field', 'js' => array('my_js'));
$this->form_builder->set_fields($fields);
$this->form_builder->render();
...

OR you can define a script tag and it will output it on the page:

// OR you can define your script tag here
$fields['my_field'] = array('label' => 'my_field', 'js' => '<script>
$(function(){
	// my amazing javascript goes here
})
</script>');
$this->form_builder->set_fields($fields);
$this->form_builder->render();

Lastly, any string value not beginning with "<script" or ending in ".js" will be treated as a javascript function name that will be called upon rendering of the form.

Custom Field

One of the most powerful new features of FUEL 1.0 is the addition of custom form fields with Form_builder. A custom field is a combination of custom has 2 main parts. The first being a method or function that renders the field type. FUEL comes with several built in custom field types which are rendered using the fuel/modules/fuel/libraries/Fuel_custom_fields.php file. The second component is a configuration that associates the field type to that method or function and any javascript files and/or functions needed for the field. This configuration is done in the fuel/modules/fuel/config/custom_fields.php file and can be done for your specific field types in the fuel/application/config/custom_fields.php file.

Custom fields have 5 javascript related parameters:

FUEL comes with several built in custom field types which can be viewed in the fuel/modules/fuel/libraries/Fuel_custom_fields.php file and are configured with Form_builder in the fuel/modules/fuel/config/form_builder.php file.

AJAX with Models

Sometimes you may want to use AJAX in your module's form. For example, you may have a list of cities that changes based on a state you select. To do this you can setup a method on your model that is prefixed with 'ajax_' (e.g. ajax_cities_by_state). Then use the following URL in your AJAX requests:

// $states is previously defined
$fields['state'] = array('label' => 'state', 'type' => 'select', 'options' => $states, 'first_option' => 'Select a state...', 'js' => '<script>
$(function(){
	$("#state").change(function(e){
		$.get('.fuel_url('my_module/ajax/cities_by_state').', function(data){
			$("#city").empty().append(data);
		})
	})
})
</script>');
$this->form_builder->set_fields($fields);
$this->form_builder->render();

Additional parameters for the AJAX method can be passed via query parameters (e.g. ?state=OR)

jQX Framework

jQX is a small javascript MVC framework. The following are some of the benefits of using JQX instead of simply including javascript files:

jQX Module Initialization Parameters

There are additional module initialization parameters you can set in your fuel/application/config/MY_fuel_modules.php.if you are using a jQX controller which include:

The initialization parameter method has special meaning and should be the name of a method on your controller (e.g. myMethod). Additionally, you can access the controller object after the window has been completely loaded (so $(window).load... not $().ready()) through the window.page variable. 

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

controller.MyModuleController = jqx.createController(fuel.controller.BaseFuelController, {
	
	init: function(initObj){
		this._super(initObj);
	},

	items : function(){
		this._super();
	},

	add_edit : function(){
		this._super();
	},
	
	myMethod : function(){
		
	}
	....
}

The above example would assume that you have a jQX Controller in your advanced modules fuel/{module}/assets/js/controller folder named MyModuleController. If the folder you wanted to save it in was fuel/{module}/assets/js/myfolder, you would need to change the objects name to myfolder.MyModuleController. Essentially, you can swap out the folder "/" with object ".".

Common Controller Methods

There are two main jQX controller methods that you may want to override in your controller:

It's important to call use this.super() to call the parent method if overwriting.

jQX Configuration Parameters

The following jqx config parameters are available for you to use in your jQX controller:

For more examples, look inside the fuel modules js/fuel/controller folder.