How to set up customize models, controllers, and views
The goal of this guide is to allow administrators of the application to add custom code to models, controllers and views without editing or changing the original ATiM files. This way, if an update is provided in the future, their custom code is not overridden, and it is relatively easy to re-test.
To accomplish this, changes had to be made to the /cake library files. For more information about this, see ATiM cakephp customizations => Changes to allow custom Controllers/Models/Views
Contents |
Models
Within the "models" folder, choose the model file you wish to customize and then create a subfolder named "customs". Within that "customs" folder, create a file with the exact same name as the model file you are customizing. For example, if the model is models/test.php then you should have created models/customs/test.php.
This new custom file should have a model class that extends the original model class, and the class name should be exactly the same class name with the word Custom appended to it. For example, if your original models/test.php opened up with this line...
class TestModel extends MyExamplePluginAppModel {
Then the custom file should open with...
class TestModelCustom extends TestModel {
var $name = 'TestModel';
var $useTable = 'text_models';
The $name variable should be defined with the name of the extended model. Without this, CakePHP will load the custom model, but fail in some SQL calls because it will be looking for TestModel.field when it's loaded a TestModelCustom table alias. The $useTable variable should be defined with the name of the extended model datatable. Without this, CakePHP will load the custom model, but fail because it is trying to associate it with a non-existant datatable. If the $name variable and/or the $useTable variable is already defined in the extended model, you do not need to specify them in the custom model, as the custom model will inherit them from the extended model. Otherwise, they must be defined in the custom model.
Within this extended model class, you may place any function/action that you can place in a CakePHP model class. If a function/action has the exact same name as one in the original model, that function/action will completely override/replace the original. If you create a function/action in the extended model that does not exist in the original model class, you can access that function/action as if it was part of the original model class.
Controllers
Within the "controllers" folder with the controller file you wise to customize, create a subfolder named "customs". Within that "customs" folder, create a file with the exact same name as the controller file you are customizing. For example, if the controller is controllers/tests_controller.php then you should have created controllers/customs/tests_controller.php.
This new custom file should have a controller class that extends the original model class, and the class name should be exactly the same class name with the word Custom appended to it. For example, if your original controllers/tests_controller.php opened up with this line...
class TestsController extends MyExamplePluginAppController {
Then the custom file should open with...
class TestsControllerCustom extends TestsController {
You may place within this extended controller class any function/action that you can place in a CakePHP controller class. If a function/action has the exact same name as one in the original controller, that function/action will completely override/replace the original. If you create a function/action in the extended controller that does not exist in the original controller class, you can access that function/action as if it was part of the original controller class.
Views
Within the "views" folder with the views file you wise to customize, create a subfolder named "customs". Within that "customs" folder, create a file with the exact same name as the views file you are customizing. For example, if the views is views/tests/index.ctp then you should have created views/tests/customs/index.ctp.
View files are not classes, so they cannot be extended the same way models and controllers are. They can only be overridden/replaced.
Custom Hooks
Controllers
Within the actions of a controller, you will find lines that look like this...
$this->hook();
This is a custom line of code that will attempt to include a PHP file to execute in this exact spot. Unlike the above custom files, these "hooks" do not replace actions/functions; they are plain PHP include files that run at that exact spot/line-number and then allow the action/function to continue.
Within the "controllers" folder and with the controller file you wish to add a hook to, create a subfolder named "hooks". Within that "hooks" folder, create a file with a name combining the controller name and action name file you are hooking. For example, if the controller is controllers/tests_controller.php and the action is function index() then you should have created controllers/hooks/tests_index.php.
Views
Within views, you will find lines that look like this...
$this->structures->hook('hook name');
As controllers, this will try to inclue the hook, if it exists, at the exact sport where the require call is made.
The hook is not necessarily related to the view file name (.ctp). The view file needs to be located under {plugin} / views / {controller} / hooks / {action}{_hook name}.php. It is important to be careful about it when the controller calls $this->render() on a view that is not the same as the default one. Eg.: The participant search action calls render on index.ctp. The caller action is "search" thus the hook within index.ctp will refer to /clinicalannotation/views/participants/hooks/search.php
