Carrington Build Documentation

Custom JavaScript

Modules can provide additional functionality for both the admin and front end displays by overriding the `admin_js()` and `js()` methods. Carrington Build uses a [jQuery](http://docs.jquery.org, “jQuery Documentation”) wrapper with `$` enclosed in a local scope. This may be incompatible with your preferred JavaScript library. There are no plans at this time to officially support other libraries besides jQuery.

Client side JavaScript is straight forward. Add a `js()` method to your module, return the Javascript to be included and it will be included in the front end output.

JavaScript for the Admin requires a bit more attention. Since the modules are loaded in via Ajax

Admin JS Module Load Callbacks

Because modules are loaded via Ajax the typical DOM Ready methods are not relevant. For this purpose Carrington Build provides the ability to add Module Load Callbacks. You are not limited to a single callback function, so if your module extends another module you don’t have to replicate its JavaScript, just include your JavaScript along with it. Any JavaScript actions can be performed within the module including show/hide actions, click events, and Ajax calls. An example of using the Module Load Callback framework:

class my_build_module extends cfct_build_module {

	// ...

	function admin_js() {
		$js = '
			cfct_builder.addModuleLoadCallback('.$this->id_base.', function() {
				$("#my-element").click(function() {
					// attach functionality here
				})
			});
			';
		return $js;
	}

	// ...
}

Admin JS Module Save Callbacks

Carrington Build also provides a callback at Module Save so that the form data can be pre-compiled, cleaned up, or checked for requirements before the form is submitted. Adding a Module Save Callback is similar to the Module Load Callback except that the return value of the function affects whether the module form will submit or not. Returning true allows the module save action to continue, returning false aborts the click action on the module save and the module form will not submit and the module edit window will stay open.

class my_build_module extends cfct_build_module {

	// ...

	function admin_js() {
		$js = '
			cfct_builder.addModuleSaveCallback('.$this->id_base.', function() {
				if ( $("#'.$this->get_module_id('my-element').'").val().length == 0 ) {
					// attach functionality here
				}
			});
			';
		return $js;
	}

	// ...
}

When Extending Other Modules

When extending an existing module you probably also want to include its JavaScript as well. If you don’t need to modify the JavaScript or add any new JavaScript you simply do nothing. The parent module’s `admin_js()` method will be called and included.

If you need to add to the Javascript create an `admin_js()` method that defines all of your required Javascript and also includes the parent class’ `admin_js()`. If the parent class’ Javascript was properly name-spaced then your module’s `$id_base` will be used when including the Javascript to avoid conflicts. For example:

class my_build_module extends some_other_module {

	// ...

	function admin_js() {
		$js = some_other_module::admin_js();
		$js .= '
			cfct_builder.addModuleSaveCallback('.$this->id_base.', function() {
				if ( $("#'.$this->get_module_id('my-element').'").val().length == 0 ) {
					// attach functionality here
				}
			});
			';
		return $js;
	}

	// ...
}

See also:

Back to Carrington Build

These sections are available to the public. The remaining sections are available exclusively to customers.