README

Base controller for CodeIgniter, helps you with loading views, subviews, and populating them with data and loading of language as well as injecting said languages into the view data.

The idea for the BaseController came from Jamie Rumbelows base controller, with some additions and changes. At this point I would also like to thank Marco Monteiro and Sami Keinänen for their help.

If you run into issues or have questions/ideas, please submit a ticket here on GitHub.

This is still in development phase, but is production ready. All existing stuff will be there and if changes do occur, old ways will be kept around in deprecated state.

Install

The easiest way to install at the moment is to use composer. Simply create composer.json file in your project root:

{
  "require": {
    "slaxweb/ci-basecontroller": "~0.4"
  }
}

Then run composer.phar install. When finished, enable composer autoload in application/config/config.php.

Next create the directory in application/config/ called slaxweb, and copy the configuration file found in install/slaxweb/basecontroller.php to the newly created directory. Or use the installation script found in install directory.

Congratulations, BaseController is installed.

View loading and data

Example

<?php
class Contrlr extends \SlaxWeb\BaseController\BaseController
{
  public function showView()
  {
    // nothing, that's enough
    // base controller will load application/views/contrlr/showview/main.php view file
    // if the controller is located in a sub-dir, sub-dir is also included in view path
  }
  
  public function nonDefaultView()
  {
    $this->view = "path/to/different/view/file";
  }
  
  public function noView()
  {
    $this->view = false;
    // do whatever you want
  }
  
  public function subView()
  {
    $this->subViews = array("varName" => "subview/file");
  }
  
  public function viewWithData()
  {
    $this->viewData = array("name" => "value");
  }
}

Basic usage

To start using, all your controllers must extend \SlaxWeb\BaseController\BaseController instead of CI_Controller. If you are already extending MY_Controller, then extend \SlaxWeb\BaseController\BaseController in MY_Controller.

And this is it, after a controller method is done executing, BaseController will automatically load the view file associated with this controller method. The default view being loaded is: application/views/(controllerdir)/controllername/controllermethod/main.

Disable view loading

Some controller methods do not load views. In this case set BaseController property view to false:

$this->view = false

Change view file

Want to load a different view file and not the default one? No problem, just set the desired view file to view property.

$this->view = "desired/view";

Load sub-views

WARNING! Loading of subview has been changed in version 0.4.0. Please see UPDATE0.4.0.md for more information.

If you need to load subviews into your main view, you can do so, by assigning a nested array to the BaseController subViews property. First level array holds the name of the sub-view parameter injected into view data, as the key. The value is an array of arrays. The bottom most array holds the view path and name, and any subview specific data with the key names, "view" and "data" respectively.

$this->subViews = array(
    "name"  =>  array(
        array(
            "view"  =>  "subview/file",
            "data"  =>  array(
                "subviewParameter"  =>  "value"
            )
        )
    )
);

Data is not a required paraeter and can be ommited.

Display the subview in the main view:

<?php echo $subview_name; ?>

View data

To load data into view, simply assign it to the viewData property array.

$this->viewData = array("name" => "value");

Controller 404 page

If a controller method is not found, the Basecontroller will search in the routed-to controller a _404 method and call it, so you can have custom 404 pages per controller. If it is not found, it will call the CodeIgniters show_404 method, and the CodeIgniter 404 page will be displayed as per normal operation.

Languages

BaseController also autoloads language files and loads properly prefixed language strings into the view data before loading the view. Language filename must have the same name as the controller, and all language strings that will be injected into the view data, need to have methodname_ prefix in the language string key.

Example

<?php
class Contrlr extend \SlaxWeb\BaseController\BaseController
{
  public function injectLanguage()
  {
    // you're done, default view is loaded with default language and its prefixed language strings.
  }
  
  public function noLang()
  {
    $this->langFile = false;
  }
  
  public function diffLangFile()
  {
    $this->langFile = "Diffrent";
  }
  
  public function diffPrefix()
  {
    $this->langPrefix = "custom_prefix_";
  }
  
  public function nonDefaultLanguage()
  {
    $this->language = "german";
  }
}

Basic usage

By default, base controller will auto-load the language file that has the same name as the controller name, from the default language directory. By default that is english, changeable in CodeIgniter config. By default it will load all language strings which have the methodname_ as the prefix in the language string key name.

class Contrlr \SlaxWeb\BaseController\BaseController
{
  public function defaultLang()
  {
  }
}

Above will try to autoload application/language/english/Contrlr_lang.php and inject translated strings.

$lang["defaultLang_var1"] = "string";
$lang["defaultLang_var2"] = "string";
$lang["defaultLang_var3"] = "string";

In the view, vars $var1, $var2, and $var3, will be available.

No languages

To disable loading of languages, simply disable it by setting property langFile to false. WARNING! Property used for disabling the language file loading in 0.1.* versions is includeLang!

$this->langFile = false;

Language file

In order to load a different language file, set the langFile property.

$this->langFile = "Different";

If you wish to load multiple language files, set an array with those language file names to the langFile property.

$this->langFile = array("Lang1", "Lang2", "Lang3");

Language prefix

To change the prefix from the default method name, set the langPrefix property.

$this->langPrefix = "langprefix_";

Non-Default language

If you want to load a non-default language, you have to set it with the language property.

$this->language = "german";

Templates

Base controller also supports basic templating. At the moment only by setting a header and footer view.

Example

class Contrlr extends \SlaxWeb\BaseController\BaseController
{
  // DEPRECATED
  public function template()
  {
    $this->head = "head/view";
    $this->foot = "foot/view";
  }
  
  // DEPRECATED
  public function noTemplate()
  {
    // if a template is already loaded, you can disable it
    $this->include = false;
  }

  public function layout()
  {
    // to load a layout, set layout property to true
    // base controller will try to load the controllers layout if not found
    // it will load the application default layout
    $this->layout = true;
  }

  public function specificLayout()
  {
    // if you want your method or whole controller to have a specific
layout file you can set it to the layout property
    $this->layout = "layout/view";
  }
}

DEPRECATED - Setting template files

In order to set the header and/or footer files, properties head, and foot must be set. Then the header view will be loaded before the controller view(s), and the footer will come after.

$this->head = "head/view";
$this->foot = "foot/view";

DEPRECATED - Disable template

If you have set the template files, but would not like to display the header and footer views, you need to set the include property to false.

$this->include = false;

Layout

Instead of header/footer files, BaseController now provides layouts. The layout is the whole template and your controller view gets injected into this layout view through the mainView variable. You have four options:

No layout (default), set BaseController layout property to false
Controller specific layout, set property layout to true, BaseController will try to load the default controller layout file from {views}/layouts/ControllerDir/ControllerName/layout
Application specific layout, set property layout to true, and make sure controller specific layout view file does not exists
Custom layout, set the path to the layout view file to the layout property

// use controller or application specific layout
$this->layout = true;
// use custom layout
$this->layout = 'layout/myLayout';

Manual view loading

BasicController also allows you to manually load any view file you want. Because BaseController is using the ViewLoader, you can access it through the protected _viewLoader property. For help with using the ViewLoader, please read the readme here.

Models

BaseController now tries to auto-load the default model for this controller, which needs to have the same name as the controller it self, with the _model suffix. You can also add additional models you may want to load to the models property. Models are then accessible as $this->{Model name}, without the _model suffix.

Example

class Cntrlr extends \SlaxWeb\BaseController\BaseController
{
    // Autoload models Model1_model and Model2_model
    public $models = array("Model1", "Model2");

    public function someMethod()
    {
        // now just use the model:
        $this->Model1->modelMethod();
        $this->Model2->modelMethod();
    }
}

CRUD

CRUD stands for Create, Retrieve, Update, Delete. BaseController provides basic CRUD methods that retrieve data, inject them into the view data as well as take post data for creation, update and deletion of database data. As long as your models provides the necessary methods for such operations. To be on the safe side, install the BaseModel, and extend your model from it.

There are 4 methods for CRUD:

index - fetches the data from the database and injects the BaseModel Result object into view data as _tableData variable
update_post - takes the post data as well as an ID as the input parameter and updates the database table, if ID is int(0), then all records will be updated
create_post - takes the post data and inserts it into the Table
delete_post - takes the ID as input parameter and deletes the record. If ID is int(0) it deletes all records in the table

All but index(Create) are accessed through POST HTTP request method, and also all 3 provide a means to load a specific view after they have completed, and also set an error in view data if the operation was not successful. This is done through 3 different BaseController properties:

afterUpdate
afterCreate
afterDelete

Those need to contain the string location of the view to be loaded. If left empty, the respective default view will be loaded as per methods HTTP GET request counterpart (update, create, delete).

Update and Create also provide a means for data validation, all you need to do is set a createRules or updateRules public properties in your controller. Those need to contain the normal CodeIgniter validation rules.

On error, Create, Update and Delete will inject the error strings as createError, updateError or deleteError variables. There are 3 types of errors: validation error, create error and update error, as well as a fourth, generic error for delete method. In order to get the message, your controller language file has to be loaded and it needs to contain following keys:

error_validation_error - for when validation error occurs
error_update_error - for when an update error occurs
error_create_error - for when a create error occurs
error_delete_generic - for when a delete error occurs

If those are set, you will get this error message in your view data. On validation errors you can normally use the CodeIgniter validation error printout as well.

ChangeLog

0.4.0

WARNING! This version breaks backward compatibility! See UPDATE0.4.0.md for more information

Enable multiple views to be loaded in single subView parameter

0.3.1

Sort the callback array before executing callbacks

0.3.0

Change callback definition to arrays to support multiple callbacks at same point
Add config file for class name case sensitivity
Convert class names based on case sensitivity

0.2.3

Missing layout property due to merge mess

0.2.2

Language not being set due to merge mess

0.2.1

Fix the merge mess

0.2.0

Add layout support
Add basic CRUD
Autoload models
Autload languages before executing the controller method
Callbacks
Code abstraction
Deprecated old template header/footer
Language file loading disabled with property langFile, was includeLang before

0.1.2

Fix merge conflicts when including the language file loading before execution of controller method

0.1.1

Versioning changed
Load language files before executing the controller method

0.1.1.0

First beta release

0.1.0.3

Multiple language files

0.1.0.2

Cast view path to lower-case before trying to load the guessed view file
Include controller sub-dir in guessed view file

0.1.0.1

Do not check if a view file exists, but let CodeIgniter handle this.

0.1.0.0

Initial version

slaxweb / ci-basecontroller

Maintainers

Details

README

Table of contents

Install

View loading and data

Example

Basic usage

Disable view loading

Change view file

Load sub-views

View data

Controller 404 page

Languages

Example

Basic usage

No languages

Language file

Language prefix

Non-Default language

Templates

Example

DEPRECATED - Setting template files

DEPRECATED - Disable template

Layout

Manual view loading

Models

Example

CRUD

ChangeLog

0.4.0

0.3.1

0.3.0

0.2.3

0.2.2

0.2.1

0.2.0

0.1.2

0.1.1

0.1.1.0

0.1.0.3

0.1.0.2

0.1.0.1

0.1.0.0