The Mojavi 3 Book/Migrating From Mojavi 2

Prerequisites

You should have a decent grasp of Mojavi2 and PHP5 before trying to upgrade to Mojavi3.

If you want a quick crash course of Mojavi 3, see Creating Your First Module.

First Things First

Before you begin transferring your applications over from Mojavi2, make sure whatever host you're using supports PHP5. You can figure out if your host supports PHP5 by running

phpinfo();

Furthermore, you need to download and install the Mojavi3 package, which can be attained by going to this location.

The Context

Probably the most important new and powerful aspect of Mojavi3 is the Context object. Once I figured out what this thing did, I fell in love with it. Basically, it is a sort of catalyst/storage object that allows you to access:

• The $request object via getRequest()
• The $controller object via getController()
• The $user object via getUser()
• The Current Action/Module names via getModuleName() and getActionName()
• And finally the Current module's directory

More or less, most classes that are exposed to the user/developer (you) are going to have a getContext() function, which will allow you to access this object. And with the recent addition of cascading calls, you can perform operations that you were unable to in php4, for example:

The Old Way:

$obj        =& $request->getAttribute('myobj');
$anotherobj =& $obj->doSomethingSpecial();
$anotherobj -> execute();

The New Way:

$this->getContext()->getRequest()->getAttribute('myobj')->doSomethingSpecial()->execute();

Okay, so maybe that wasn't the best example, as it is rather lengthy, but you get my point, 1 line vs 3 lines, and no possible mistakes when dealing with large objects like copying them over without references, etc.

This subsection is to be continued....

Translating your Renderer

Mojavi2 used 'renderers' to translate the API of one templating system into a generic API that would easily allow a developer to switch out one templating system for another. For example, the Smarty templating engine uses $smarty->assign() to allow you to set a variable, while patTemplate, another templating system, uses $pat->addVar(). In Mojavi 2, you would then write or use an existing renderer, which you would then invoke to display your output.

Note: This was done typically through a filter, which would create the renderer object, then assign it to your $request via

$request->setAttribute('MyRenderer',$rendererObj))

Mojavi3 uses largely the same methodology, but instead of getting the renderer directly from the $request object within each of your views, it simply extends the View class.

For example:

abstract class SmartyView extends View
{
.....

function __construct()
{
   $this->engine = $this->getContext()->getRequest()->getAttribute('MySmartyObj');
}

, $value)

{
   $this->engine->assign($name, $value);
}

.....
}

Note: the use of

$this->engine = $this->getContext()->getRequest()->getAttribute('MySmartyObj');

was simply the best solution I could come up with for getting any object from within the view, you could also have done the following just as easily:

$this->engine = new Smarty();

View

The Mojavi3 View is mostly an abstract class, which provides a skeleton of functions to work with, thus providing the unified API as was achieved in Mojavi2 (It's unified because you are forced to comply with the naming conventions implemented by the abstract class View.)

Now, instead of initializing your Renderer object (as you would in Mojavi2) you simply extend View, and initialize that. Like shown above:

abstract class SmartyView extends View
{
...

is what our new View would look like. To put this new View type into action, we extend it when declaring views for our modules. For example:

class DoSomeActionSuccessView extends SmartyView
{
...
}

As you can see, this is much more fluid than pulling the renderer out of $request with every new View, it's also a lot less code that you have to copy and paste, and thus less code to maintain. You may also have noticed that the naming scheme is different for the Views, instead of naming the file DoSomeActionView_success.class.php you would now name it DoSomeActionSuccessView.class.php, and name the class likewise(In Mojavi2 we just named our view classes DoSomeActionView, in Mojavi3 it's DoSomeActionSuccessView replacing 'Success' with your application's state).

This subsection is to be continued....

Actions

Actions in Mojavi3 are fairly similar to those of Mojavi2, with a few enhancement and semantic tweaks here and there. Listed Below:

• When returning a VIEW_SUCCESS in Mojavi2, now return the View class constant corresponding to your application state, i.e.: View::Success, or View::Error
• When checking for view types supporting execution (getRequestMethods) instead of returning REQ_POST etc., return Request::Post etc.
• There is a new return type for getRequestMethods(), Request::All, which serves all request methods.
• The root Action class which all your actions extend now has a getContext() method, which allows you access to the context object.

Configuration

Mojavi3 configurations are done, by default, using .ini files. This simple and straightforward configuration makes configuring mojavi very easy. The base syntax of these ini files is as follows:

[SECTION]

    ; a comment.....
    ConfigKey           = "%MO_APP_DIR%/my/config/value"

Because some people might not like ini files, Mojavi3 was created in such a way that you could write your own configuration handlers. For example, if you wanted to use xml files to configure your mojavi, you could write a configuration handler, plug it in, and start using your custom configuration styles.

This subsection is to be continued....

References

To find out more about PHP5 in general go here: Where can I go to learn more?