Carrington Build Documentation

The View File

Carrington Build’s default Modules all use the combination of a `view.php` file and the `load_view()` method to provide some separation between the module logic and the module display. The default location for the `view.php` file is the root level of your module’s folder. View’s are loaded in an output-buffer so while it is required that Modules return html this allows the use of functions that echo.

While using `load_view()` is recommended, it is not mandatory. The base requirement is that your `display()` method return HTML.

Loading the View

To use the load view function pass $data as the first parameter and optionally supply a `key => value` array of extra parameters that you want to pass in to the view. Anything passed in via the 2nd parameter will be extracted in to the local scope for the view. So, below, `$my_param` will be made available in the view.

class my_build_module extends cfct_build_module {

	// ...

	function display($data) {
		// pre-process the module data here if necessary
		$my_param = 'foo';

		return $this->load_view($data, compact('my_param'));
	}

	// ...
}

Overriding the View

By default the `load_view()` method will look for a `view.php` in your module’s folder. If it finds none it will return null. In some situations it may make sense to alter the view file based on some parameter (like, maybe your front page needs a slightly different output template). In this case use the included filter to change the module’s view file before it is loaded.

The view can be filtered on a per module basis using `cfct-module-module-id-admin-view`. Replace `module-id` with the id of the target module. In your function you need to return the full path to the view file to override the default. `$data` is passed to the filter as well so views can also be filtered based on the content of the module.

An example of overriding the Callout module’s view for the home page:

function my_load_callout_view($view, $data) {
	if (is_home() || is_front_page()) {
		$view = trailingslashit(get_stylesheet_directory()).'views/callout-home-view.php';
	}
	return $view;
}
add_filter('cfct-module-cfct-callout-view', 'my_load_callout_view', 10, 2);

Providing Multiple Views

The view loading mechanism also allows for custom view files to be defined by the module itself. Lets say, for example, that you want to provide different layouts to your module as a selectable preference. Provide the user with a way to select the view template to use and then change the `$this->view` property of the module before calling `load_view()`.

See also:

Back to Carrington Build

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