Matchbox
[b]Current version:[/b] File:Matchbox-0.99.zip [b]Forum Thread:[/b] [url]http://codeigniter.com/forums/viewthread/128084/[/url] [b]Last update:[/b] 2009-09-02
Matchbox is a set of extended libraries that lets you organize your application in small components (modules). These modules have several advantages, the main one being portability. Modules are stored in their own folders and so they can be reused in other applications or shared between users by copying just that one folder.
[h2]Installation[/h2] If you can run CodeIgniter, you've already met the server requirements, thus all you have to do is download and unzip the latest version of Matchbox right into your application directory. File:Matchbox-0.99.zip
To test your installation, open up your browser and test the uri [b]http://yoursite.com/pathto/index.php/matchbox/[/b].
If you see the Matchbox dashboard, you've successfully installed Matchbox!
If it's not working see [b]Troubleshooting[/b] further down this page, or if that doesn't answer your questions, ask them in the [url=argh]forum thread[/url].
[h2]Usage[/h2] Installing Matchbox won't effect your current application, though. Any controllers in the [b]APPPATH/controllers/[/b] will work like they used to. To start modulizing your application you have to create a module.
[h3]Creating a module[/h3] To make a new module, you create a new folder in the [b]APPPATH/modules/[/b] directory. For instance, creating the directory [b]APPPATH/modules/my_new_module/[/b] results in a new module named 'my_new_module'.
Within this folder you place additional folders for each type of resource you need in the module. Often you'll want controllers in your module, in which case you make a 'controllers' folder in your module directory. You can also add folders for config files, helpers, languages, libraries, models, plugins and views. Your module folder should like a lot like your application directory.
[h3]Controllers in modules[/h3] So you've got a module directory with a [b]controllers/[/b] folder, and now you want to make a controller to place there. Luckily, module controllers are no different from regular controllers, so if you want to test Matchbox right away, you can go ahead and copy one of your exsisting controllers to your module (or just create a new one).
To access your controller, you go to [b]http://example.com/index.php/MODULE-NAME/CONTROLLER-NAME/[/b]. Basically the only difference from accessing a regular controller, is that you have to add the module name before the controller name in the uri. If you only type in [b]http://example.com/index.php/MODULE-NAME/[/b] and not the controller name, Matchbox will try to load the controller with the same name as the module (unless [b]strict mode[/b] is enabled, which is explained futher down the page). This default controller can be customized, though, which is explained a litle further down the page.
[h3]Resources in modules[/h3] Where things start to get interesting, is when you need to load resources like helpers from your controllers. If the resource is located in the same module or in your application directory, they can be loaded as usual (unless [b]strict mode[/b] is enabled, which is explained futher down the page).
However, if you need to load resource from another module than the one the controller resides in you'll have to tell Matchbox what module to look inside. You do this by either adding the module name as the last argument when using regular load calls. [code]$this->load->model('blog_model', '', FALSE, 'my_other_module');[/code] Or alternatively, you can prefix the load call with 'module_', in which case the module name is the first argument. [code]$this->load->module_model('my_other_module', 'blog_model');[/code]
[h3]Configuration files in modules[/h3] You can also make custom routes.php and autoload.php configuration files for your modules. Simply copy a regular CodeIgniter routes.php or autoload.php into your modules config directory and edit them to your liking.
The [b]default_controller[/b] you set in the module routes.php file will be used instead of the module name when typing only the module name as the uri. So if you go to [b]http://example.com/index.php/MODULE-NAME/[/b] it will attempt to load said default controller.
You can of course also add custom routes like in the regular routes.php.
[h2]Configation[/h2] You can configure your Matchbox installation by editing the [b]application/config/matchbox.php[/b] file. The file contains three configurable items; the 'strict' variable, 'paths' array and 'callers' array. All three are explained below.
[h3]Module directories[/h3] By default, modules are located only in [b]APPPATH/modules/[/b], however this can be configured using the 'paths' config item in the matchbox configuration file. So if you want modules in both your application and system folders change the config item to the following. [code]$config['paths'] = array(APPPATH.'modules', BASEPATH.'modules');[/code]
[h3]Caller Detection[/h3] Matchbox is able to determine where a certain load call originates from using backtraces. What this means, is that even your request starts in a regular controller, and that controller loads a library in a module and that library attempts to load a model, Matchbox will now that the calling library is located in a certain module and attempt to find the model accordingly.
[b]However[/b], if you have, say, a custom view library that you call instead of the regular loading of views, and that library is located in your application folder then if a module controller calls said library to load a view in the same module, then Matchbox will think that the view is located in your application directory, because the final view request comes from the custom view library located in the application folder.
To remedy this, you can add your custom view library the the [b]caller[/b] configuration array in the matchbox configuration file. [code]$config['callers'] = array(APPPATH.'libraries/Custom_view_lib.php');[/code]
[h3]Strict mode[/h3] In the Matchbox configuration file is a [b]strict[/b] config item than can be either TRUE or FALSE.
By default strict mode is disabled. This means that Matchbox will do several additional checks when performing searches for controllers and other resources. For instance, when the uri only contains a module name, Matchbox will attempt to find a controller with the same name as the module, but not with strict mode enabled. More importantly, with strict mode enabled, $this->load->something calls will only search for resources in the current module (and system directory) but not in the application directory. So if a module controller needs to load a helper from the application directory you must specifically do it like so: [code]$this->load->module_helper(APPPATH, 'some_helper')[/code]
The simple reason why you'd want to have strict mode enabled is that it speeds up your application. So you might wanna have strict mode enabled during development, and then go through your code and enable it for production.
[h2]Troubleshooting[/h2] [h3]I'm getting the error "Matchbox: Unable to load the requested class: pledgie"[/h3] The issue has been fixed in the latest release. Download the newest version of Matchbox.
[h2]Donations[/h2]
If you use and enjoy Matchbox, please consider making a donation.
Many thanks for your continued support.
Zacharias.