Modules - Doc - Orion, the PHP 5 framework.

Documentation / Modules

Directory structure

Modules are located inside the orion/modules/ directory. Each module file must be placed inside a sub-directory named after the module's name (a.k.a. module URI).

Each module must contained at least a default-mode controller. This controller must be placed right inside the module's directory and put in a file named under the following convention : [modulename].[mode].php ; where [modulename] is the module's URI (same name as module directory) and where [mode] is the mode under which the controller is run.

Modes can be configured inside the Orion configuration file. By convention, "default" is the standard mode which can be accessed with .html extension (more information about modes can be found in Orion's URI format doc).

While all module's views and models can be placed right inside the module's directory, it is recommended to place views and models inside sub-directories, so a standard module directory should look like this :

orion/
    modules/
        mymodule/
            mymodule.default.php (the default controller)
            mymodule.somemode.php (a "somemode"  mode controller)
            models/
                post.php
                category.php
            views/
                list.tpl
                single.tpl

Example

Let's take an example. You want to create a "contact" module, which will contain a simple mailer form.

Creating the required files and directories

So you start off by creating a new directory inside orion/modules/ named "contact".

Since a mailer form doesn't need any database storage you won't create any model file. So the only sub-directory you have to create is contact/views/ to store the form view, and the info view. You will also need to create the default controller's file named "contact.default.php".

Now this is what your contact directory should look like at this point :

orion/
    modules/
        contact/
            contact.default.php
            views/

Creating the two basic views

For this example you will create two view files using the Smarty renderer that is provided with a default Orion installation, one that will hold the mailer form (form.tpl), and another one that will display post-submit information (info.tpl).

Let's fill up the contact/views/form.tpl view with a classic mailer form.

{block name='body'}

    Your name
        
    Your mail address
        
    Your message
        
    

{/block}

Note the usage of the {block} declaration here. This means that we don't have to put the whole html markup in our view (html, head, body, etc...) because we will be able to extend a default template that already contains this markup (this will be done later inside the controller).

Nothing else out of the ordinary here, except that you may be wondering why you are using the {$target} template variable for the form target instead of a simple '#' to use the current URI as target. This is only a matter of accessibility and coding convention, in fact you can of course use a '#' target, but it is common knowledge that using a target URL different from the current page is better for form submits because of its accessibility and refresh behaviour. So by using the {$target} template variable, we will be able to pass the form target URL to the view from the controller.

Now for the post-submit information view.

{block name='body'}
{$info}
{/block}

Nothing to explain here, you're just using a template variable to store the information to display.

Creating the controller

Next step, open up your contact.default.php controller file and fill it with a default controller declaration like this one :

namespace \Orion\Modules\Contact;

use \Orion\Core;
use \Orion\Plugins;

class ContactDefault extends Core\Controller\Template
{
    public function __construct()
    {
        
    }
}

If you don't understand a part of this code, you may want to take a deeper look into Orion Controllers' structure in this documentation.

Note that the Orion\Plugins namespace alias will be used later on this example.

Now let's add a standard routing declaration inside our constructor :

public function __construct()
{
	$this->route = new Core\Route();
	// Mapping the 'do' URI the the _sendmail() method
	$this->route->addRule('do', 'sendmail');
	// Mapping the default URI to the _showform() method
	$this->route->setDefaultMethod('showform');
}

This example shows a quick way to create custom routing rules, so that :

yoursite.com/contact.html calls the _showform() method
yoursite.com/contact/do.html calls the _sendmail() method

The underscore before the method name is the security prefix used to declare route-callable controller methods. This prefix can be changed inside the core/controller.php class and must not be provided in the routing rule declaration.

Creating the default method

Now let's create your default _showform() method inside the ContactDefault controller class.

public function _showform()
{
	$this->assign('target', Core\Context::genModuleURL('contact', 'do'));
	$this->renderView('views/form');
}

This method will simply fill your {$target} template variable with the contact/do.html URL using the URL generator provided by the Core\Context class and then render your form's view.

Note that renderView() will extend your view from the default template defined in the Orion Configuration file. This will, as said before, insert your view's HTML inside a standard html markup, saving up time because you don't have to repeat the document markup for each view, and moreover, this will later enable the use of themes.

Creating the sender method

Now let's create the _sendmail() method inside the ContactDefault controller class.

public function _sendmail()
{
	try {
		$name = Core\Context::post('name', true);
		$mail = Core\Context::post('mail', true);
		$message = Core\Context::post('message', true);
		$subject = 'Contact from '.$name;
		$target = 'me@myself.com';

		// Sending the mail using the Mailer plugin
		Plugins\Mailer::security = true;
		Plugins\Mailer::send($mail, $subject, $message, $name, $target);

		$this->assign('info', 'Mail sent !');
	}
	catch(Core\Exception $e)
	{
		$this->assign('info', $e->getMessage());
	}
	
	$this->renderView('views/info');
}

What this method does is retreive the form's POST variable using the Core\Context::post() method (the second argument, true, makes the method throw an Exception if the variable isn't set). And then, using the built-in Mailer plugin, we send the mail.

Wrap up

The final controller should look like this :

<?php

namespace \Orion\Modules\Contact;

use \Orion\Core;
use \Orion\Plugins;

class ContactDefault extends Core\Controller\Template
{
	public function __construct()
	{
		$this->route = new Core\Route();
		// Mapping the 'do' URI the the _sendmail() method
		$this->route->addRule('do', 'sendmail');
		// Mapping the default URI to the _showform() method
		$this->route->setDefaultMethod('showform');
	}

	public function _sendmail()
	{
		try {
			$name = Core\Context::post('name', true);
			$mail = Core\Context::post('mail', true);
			$message = Core\Context::post('message', true);
			$subject = 'Contact from '.$name;
			$target = 'me@myself.com';

			// Sending the mail using the Mailer plugin
			Plugins\Mailer::security = true;
			Plugins\Mailer::send($mail, $subject, $message, $name, $target);

			$this->assign('info', 'Mail sent !');
		}
		catch(Core\Exception $e)
		{
			$this->assign('info', $e->getMessage());
		}
		
		$this->renderView('views/info');
	}

	public function _showform()
	{
		$this->assign('target', Core\Context::genModuleURL('contact', 'do'));
		$this->renderView('views/form');
	}
}

?>

You can now test your module on yourwebsite.com/contact.html.