Revision as of 18:08, 19 October 2012

Introduction

X2EngineCRM provides the means to manually customize classes and templates without modifying the source files. This can be performed by creating new files in custom. The need for this arises because the source files may be overwritten (and their customizations destroyed) during each software update, whereas if customizations are stored in other files, they remain in effect, and barring any incompatibilities between new versions and customizations in those files, they will still work as intended.

Overview

(in progress)

Overriding Files

Practically any php file used in X2Engine can be overridden. Traditionally, customizing the software meant changing the original files. That alone could be problematic to keep track of, given the vast number of files. And of course, automatic updates to any of those files would wipe out all of your changes. X2Engine includes a customization framework

Extending Controllers

X2Engine is built on Yii, which uses MVC (model-view-controller) architecture. Overriding an entire file is practical when dealing with views or smaller classes (such as models), but controllers can present a greater challenge. It's only a matter of time before we update one of the 1500+ lines of code in a controller. This means you have to manually find and transfer your changes from the old version, which is time-consuming. To remedy this, we allow substitution of any controller in X2Engine with an extended class.

Whenever a controller is loaded, X2Engine checks for the same filename with "My" at the beginning. For example, if you want to override a single action to ContactsController, you can create a file called MyContactsController in /custom/protected/modules/contacts/controllers containing the following:

<?php
class MyContactsController extends ContactsController {
    function actionIndex() {
        echo 'Hello World!';
    }
}
?>

This file will automatically be used instead of ContactsController and should still work if ContactsController is changed in an update. You may still need to manually merge changes if an update alters the same part of the controller that you changed, but it will be much easier to find.

Known Issues

Currently, only php files can be substituted. To change a CSS or Javascript file you would have to edit the original file.