Creating Your First Module
A work in progress
This tutorial is a work in progress, so you may find parts that don’t completely fit together.
Module where we will also look at various file extension cache options.
The module is where the Model and View takes place in the MVC model. For this first example, we will create a very simple module that will move data from a Action to a View and display it on the screen, through a template.
The module is contained within a directory that carries the name of the module. This resides in the modules directory of the webapp directory. Inside the module directory are sub-directories holding the classes that make up the module. Here is the directory hierarchy:
webapp
|
|—modules
|
|—moduleName
|
|—actions
|
|— config
|
|— lib
|
|— models
|
|— templates
|
|— validate
|
|— views
Minimally, you need the actions, config, templates and views directories. However, I prefer to have a blank module created and just copy and rename it. You can get a copy of the blank module (link to be added). I have chosen to call this module Test
Each module must have a module.ini file in the config directory. If you are looking to buffer your files then file extension cache extensions may be helpful.Here is the module.ini for Test
; +—————————————————————————-+
; | This file is part of the Mojavi package. |
; | Copyright (c) 2003, 2004 Sean Kerr. |
; | |
; | For the full copyright and license information, please view the LICENSE |
; | file that was distributed with this source code. You can also view the |
; | LICENSE file online at http://www.mojavi.org. |
; | ————————————————————————– |
; | MODULE INFORMATION FILE |
; +—————————————————————————-+
[module]
ENABLED = “On”
TITLE = “Getting Started Test Module”
VERSION = “0.1″
NAME = “TestModule”
AUTHOR = “Richard D Shank”
HOMEPAGE = “http://www.mojavi.org”
DESCRIPTION = “A test module”
The module is pretty self explanitory. You can also search the web for various file extension cache options. It is necessary to have ENABLED property set to “On” for the module to be used by Mojavi. Now that we have the module set up, we can work on the classes.
Action
The Action class handles the request for the module. It can be as simple as handling a static html template or a full blown multi-page wizard style form. Just a note to Mojavi 2 users, a significant change from Mojavi 2 to Mojavi 3 is that it is not longer necessary to pass the controller, request and user classes in on many of the methods. These are now accessed through a context class. More on that later.
This is a list of the methods you can use in an Action and an explanation of what they do
execute ()
Note: This method is required in your Action class.
This will execute any application/business logic for the action. This method is reached only after the request methods have been checked and any of the parameters have been validated.
When leaving, the execute() method should tell the controller what view is to be used. This is done by returning a string containing the view name associated with the action or an array of the parent module for the view to be executed, parent action for the view and the name of the view. I will show an example of return both in a later tutorial.
getCredential ()
This is a new feature in Mojavi 3. Basically, a credentials are a privilege array that describes any level of security. They work hand in hand with the security aspects of the User class. For Mojavi 2 users, note that this replaces the old Privileges. But it is also important to know that it can do more than just handle privileges. I will handle the usage of creditials in a later section. For now, it is sufficient to know that we set the creditial requirements for the action inside this method and that it is set to NULL by default.
getDefaultView ()
This is the view that will be executed when a given request is not served by the action. This could happen when a form being displayed for the first time or if we are displaying a static page.
Again, just as with the execute() methoad, a string with a view name or an array of a module/action/view is passed back to the controller. By default it will pass back View::INPUT
getRequestMethods ()
This method will determine what types of requests will be recognized. There are 4 choices:
* Request::GET – Indicates that this action serves only GET requests.
* Request::POST – Indicates that this action serves only POST requests.
* Request::NONE – Indicates that this action serves no requests.
You can also select both GET and POST requests by using Request::GET | Request::POST
handleError ()
Execute any post-validation error application logic.
It also returns the view through a string of the view name or the array of a module/action/view. By default, it passes View::ERROR.
initialize ($context)
You can set up the Action in the initialize() method. In a later tutorial, I’ll give an example of doing this. NOTE: It is worth to note that you must handle the context in the initialize() method. You should do this by
parent::initialize($context);
You also need to return a TRUE or FALSE based on the success of the initialization. By default it is TRUE.
isSecure ()
Does the action require security? TRUE if you do, FALSE otherwise. It is FALSE by default.
validate ()
This is used to manually validate input parameters instead of using a pre-progammed validator. This will also be explain later in the tutorial on validation.
Creating Your First Action
Now that we have an overview of the Action class, we can move forward to creating our first Action. For this example, there isn’t any request to be handled so we can set up a minimal Action.
In naming an action you must use this format Actionname Action.class.php where Actionname is what you are calling this particular action. When you declare your class, it also must have the class name in the same format Actionname Action. For this example, I chose to call this FirstAction.
When creating a new action, at the very least, there has to be an execute() method, even if it does nothing. Also, since we are displaying a non-request page, we don’t need to process any request. We tell the controller this with the getRequestMethods() method, by setting the return value to Request::NONE. Finally, we also need to tell the controller what the default view is going to be. We do this by returning View::SUCCESS in getDefaultView().
Here is what my FirstAction.class.php looks like. I basically just took my BLANKAction.class.php, renamed it to FirstAction.class.php, renamed the class to FirstAction, removed the methods I didn’t need and set the remaining 3 methods to match my needs.
class FirstAction extends Action
{
/**
* Execute any application/business logic for this action.
*/
public function execute ()
{
// we don’t need any data here because this action doesn’t serve
// any request methods, so the processing skips directly to the view
}
// ————————————————————————-
/**
* Retrieve the default view to be executed when a given request is not
* served by this action.
*/
public function getDefaultView ()
{
return View::SUCCESS;
}
// ————————————————————————-
/**
* Retrieve the request methods on which this action will process
* validation and execution.
*/
public function getRequestMethods ()
{
return Request::NONE;
}
You can also return a view from another module. You do this by passing an array with the view information intead of the standard View::INPUT. When you use this you create a two element array. The first element is the module name. The second element is which view you want. It cannot be just the Action name, but the Action name with the specific view.
Here’s an example:
class MyClass extends Action
{
…
function execute()
{
…
$returnView[0] = MyModule;
$returnView[1] = DoSomethingInput;
-or-
$returnView[1] = DoSomethingError;
-not-
$returnView[1] = DoSomething;
return $returnView
}
}
View
I’ll add more to this later, describing the View class.
![Reblog this post [with Zemanta]](http://img.zemanta.com/reblog_e.png?x-id=5671a6e9-77fd-430d-9aaf-b416987a49ae)
If you are in sales you know that nothing can happen until you are in front of the customer. In most cases this will mean calling on that potential customer,