Bootstrap

Struttura directories, config.php, index.php e .htacess

Il file config.php contiene il define che contiene il path al framework.
INSTALL_PATH è il percorso completo alla root del framework
INSTALL_WC è la directory che contiene la versione del framework che si vuole utilizzare

define(INSTALL_PATH, '/usr/lib/php/amos-framework');
define(INSTALL_WC, 'trunk');
Il file index.php definisce alcune costanti che poi verranno usate all'interno del progetto, richiama il bootstrap del framework e la index.php dell'applicazione. Da qui viene fatto partire il meccanismo MVC:
$url = $_SERVER['REQUEST_URI'];
/* exception handling */
try{
	$dispatcher = new Dispatcher($url);
	$dispatcher->dispatch();
}catch(XanduException $e){
	$e->handleException();
}

Configurazioni applicazione

La directory configuration contiene il file default.ini

[enviroment]
val = development

[site]
dateFormat = dd/mm/yyyy
timeZone = +1
recordPerPage =
published =
passwordExpire = 3
passwordExpireType = m

[ftp]
enabled = 0
host = localhost
port = 21
root = \
user = 
password = 

[db_mssql]
layer = 
username = 
password = 
host = 
database = 
tablePrefix = 

[i18n]
lang[] = it
lang[] = en

[db]
layer = mysqli
username = 
password = 
host = localhost
database = 
tablePrefix =
charset= UTF8

[orm]
engine= doctrine
version= 1.1.4

[template]
engine = smarty
fileExt = html
leftDelimiter = <!--{
rightDelimiter = }-->
La sezione development contiene il nome dell'ambiente utilizzato.
Questo nome corrisponde al nome del file dentro la directory configuration/environments

Router

Il router è quella parte del framework che, dato un determinato URL, sulla base della tabella di routing fornita, decide quale plugin, controller, action utilizzare e passa eventuali argomenti trovati.
Le regole di routing possono essere definite in due livelli:
- a livello di applicazione, dentro la directory configuration
- a livello di plugin, dentro la directory configuration del plugin
Per definire la tabella di routing ci sono due modi

Xml routes

Di seguito un esempio di definizione di regole tramite file xml.

<rules>

	<rule type="#controller/#action" />
	<rule type="#controller/#action/*" />
	
	<rule type=":installer_index">
		<plugin>installer</plugin>
		<controller>installer</controller>
		<action>index</action>
		<requirements>
			<installer_index>installer</installer_index>
		</requirements>
	</rule>
	
	<rule type="installer/:cmd">
		<plugin>installer</plugin>
		<controller>installer</controller>
		<action>index</action>
		<requirements>
			<cmd>set_config|db_connection_check|set_adminisrator</cmd>
		</requirements>
	</rule>
	
</rules>

Dynamic routes

Oltre all'xml, si possono definire regole di routing in php nel seguente modo

class codeviewDynamicRules extends RouteDynamic {
	function __construct($rules) {
        $plugin_name = 'codeview';
        $root_name = $plugin_name;
        $controller_name = $plugin_name;

        parent::__construct($rules, $plugin_name);

		$this->addRule($root_name, array(
            'controller' => $controller_name,
            'action' => 'index',
        ));
        
       	$this->addRule($root_name.'/:plugin/:controller/:action', array(
                'controller' => $controller_name,
                'action' => 'index',
                'args' => array(
                        'plugin' => '[a-zA-Z0-9]*',
                        'controller' => '[a-zA-Z0-9]*',
                        'action' => '[a-zA-Z0-9]*',
                        'fixargs' => array(
                'variabile' => $calcolataInFaseDiRouting
            )
                )
        ));
    }
}
Il file si deve chiamare Route.php, mentre la classe si deve chiamare DynamicRules nel caso di regole di applicazione, e nomepluginDynamicRules nel caso di regole di un plugin.
Passando ad una regola di routing un fixargs possiamo definire degli args prefissati da passare al controller.

Dispatcher

Il Dispatcher è in qualche modo la chiave di volta del framework. Il metodo dispatch richiama il router da cui estrae plugin, controller, action e argomenti, dopodiché instanzia l'oggetto controller e inizia il processo MVC

RouteSanitize

Prima lanciare l'azione il dispatcher controlla se il controller instanziato fornisce prima un metodo RouteSanitize e poi un metodo actionRouteSanitize. All'interno di questi metodi il controller può decidere se la regola di routing scelta è buona. In poche parole comunica al dispatcher se l'aver instanziato lui è stata una buona scelta.

Il valore di ritorno da fornire è un array. Di seguito il metodo processRouteSanitize del dispatcher per vedere i vari valori di ritorno processati:
private function processRouteSanitize($routeSan)
	{
		switch (strtoupper($routeSan['message'])) {
			case 'REDIRECT':
				if ($routeSan['url']) {
					header("Location: ".$routeSan['url']);
					die();
				}
				else
					return $this->getControllerObject($routeSan['controller'], $routeSan['action'], $routeSan['args'], $routeSan['plugin']);
			break;
			case 'BRUTALDIE':
				die('Brutal die.');
			break;
			case 'ALLOK': case 'GREAT': case 'COOL': default:
				// do nothing, run your way...
				return true;
			break;
		}
	}

Application

Controller

Util

Sia all'interno della directory controller alla root dell'applicazione, che in ogni directory controller dei plugin troviamo una directory util in cui è possibile definire delle classi di utilità che poi sarà possibile richiamare facilmente dal controller.
Ogni util deve implementare l'interfaccia controllerUtil. Di seguito un esempio:

class ArrayUtil implements ControllerUtil {

	public function run($controller) {
	
	}
	
	public function groupBy($array, $pattern) {
		$path = explode('.',$pattern);
		$return = array();
		foreach($array as $elem) { 
			$key = $elem[$path[0]][$path[1]];
			$return[$key][] = $elem;
		}
		return $return;
	}
}

Dal controller per richiamare le util è sufficiente dichiarare una proprietà $utils in questo modo:
public $utils = array (
	'SessionRegistry',
	'LoginsRegistry',
	'users.Array',
);
E' anche possibile richiamare una util definita in un diverso plugin con la forma nomeplugin.nomeutil

Pseudo-eventi

Il controller può definire una serie di metodi che il dispatcher, se trova richiamerà in determinati momenti del processo MVC.
Queste definizioni devono essere applicate a livello di costruttore tramite le chiamate:
$this->setBeforeFilter('nomecallback', array('applica solo a queste azioni'), array('escludi queste azioni'));
Verrà invocato dal dispatcher il metodo "nomecallback" appena prima di lanciare l'action del controller
$this->setAfterFilter('nomecallback', array('applica solo a queste azioni'), array('escludi queste azioni'));
Verrà invocato dal dispatcher il metodo "nomecallback" subito dopo il ritorno dell'action del controller
$this->setBeforeRedirectFilter('nomecallback', array('applica solo a queste azioni'), array('escludi queste azioni'));
Verrà invocato dal dispatcher il metodo "nomecallback" prima che venga lanciato il metodo chiamato per il redirectToApplication
$this->setAfterRedirectFilter('nomecallback', array('applica solo a queste azioni'), array('escludi queste azioni'));
Verrà invocato dal dispatcher il metodo "nomecallback" dopo il lnacio del metodo chiamato per il redirectToApplication

redirectToApplication

Il redirectToApplication è un meccanismo molto utile che permette di richiamare una action all'interno di un processo MVC già partito. Es:

$risultato = $this->redirectToApplication('nomecontroller', 'nomeaction', $argomenti, 'nomeplugin');

FrameworkException e ApplicationException

Le eccezzioni di tipo framework mostrano una vista con il backtrace completo dell'errore, cosa molto utile in ambienti di sviluppo, meno in ambienti di produzione. La direttiva (in fase di sviluppo) mailexceptions, da definire nella sezione [server] del file di configurazione, se impostata a 1, in concmitanza con la variabile notifyto=indirizzoemail, dice al framework di mandare l'errore completo via email. La direttiva showexceptions=0 dice al framework di mostrare un messaggio più "amichevole" all'utente.

A livello di applicazione invece, si possono sollevare eccezzioni di tipo ApplicationException.
E' necessario definire un controller alla root del progetto con nome ApplicationException che deve implementare un metiodo execute

view

Nella soluzione progettuale (pattern architetturale) MVC per lo sviluppo di applicazioni object-oriented la View si occupa di visualizzare i dati forniti dal Controller ed elaborati dal Model.

template engines

Il livello della View per la presentazione dei dati elaborati (grafica, testo, css, js etc.) integra un sistema di Template Engine che slega la parte applicativa del software (funzionalità) dal tipo di presentazione utilizzata.

E' possibile scegliere nel default.ini il template engine da utilizzare e l'estensione dei file:

[template]
engine = smarty|php
fileExt = html|php
Sono due i sistemi attualmente supportati: Template Engine PHP e Smarty.

Un veloce sguardo a Smarty
Link: http://www.smarty.net/

Si tratta di un motore di web template scritto in PHP, utilizza Smarty tag, ed in pratica mette a disposizione un pseudo-linguaggio, espandibile e personalizzabile che emula costrutti principali di linguaggio di programmazione mantenendo sintassi semplici ed immediate.
Attualmente, di default, la sintassi dei delimiter left e right utilizza <!--{ }-->. E' possibile modificare i delimiter agendo sulle configurazione del file default.ini alla sezione [template]
[template]
leftDelimiter = <!--{
rightDelimiter = }-->

L'applicativo inoltre memorizza i file di caching di Smarty nel percorso /configuration/smarty/template_c.

layout

All'interno del modello di layout abbiamo a disposizione tutte le variabili definite all'interno della view. Inoltre abbiamo la variable contents_for_layout che contiene la renderizzazione della view, la variaible title_for_layout e la variaible header_for_layout
I metodi per impostare e configurare il comportamento del layout sono:

[utile nel caso in cui l'azione risponde ad una chiamata ajax]
$this->setAutoLayout(true|false);

$this->setLayout($layout, $pluginName);

$this->appView->setPageTitle('titolo');

$this->appView->addPageScript($url, $tag = null, $type="text/javascript");

$this->appView->addPageScriptDeclaration($content, $type = 'text/javascript');

$this->appView->addPageStyleSheet($url, $type = 'text/css', $media = null, $attribs = array());

$this->appView->addPageStyleDeclaration($content, $type = 'text/css');

action view

Le view, di default, vengono caricate dalla root dell'applicazione /view/nam_econtroller/ o per i plugin dalla directory /plugin_name/view/name_controller/. I file prendono il nome del metodo in azione in quel momento con estensione settata nel file default.ini.
E' possibile cambiare i percorsi utilizzando i seguenti metodi all'interno del controller.

$this->setDefaultTemplateController();
$this->setDefaultTemplate();
Inoltre è possibile assegnare variabile alla view con la seguente chiamata da controller
$this->assign('nome', $valore);
Si anche può anche disabilitare l'output della view e del layout tramite il comando:
$this->$this->setAutoRender(false);

gestione inclusioni header

model

doctrine

La realizzazione dei model viene affidata al manager raggiungibile all'indirizzo admin/manager.

La funzionalità di default è la "From DB" che crea i model basandosi sulla struttura del database.

Scegliendo la connessione di default (db) si vedranno le tabelle presenti nel database connesso. Per ogni tabella scelta si possono creare, sia i model, sia i permessi base necessari al CMS per visualizzare la tabella in modalità CRUD.

I model vengono depositati nel folder "webapp/model/doctrine" e "webapp/model/doctrine/generated".

All'interno del folder "generated" sono presenti i model "base". Nel folder "doctrine" sono presenti due file: il primo, il record; il secondo, la table.

I model di doctrine supportano di default la behaviour tra cui la "i18n" utilizzata per la gestione multilingua.

Library

Configurable

Utile il metodo statico:

Configurable::queryConf($section,  $key)

i18n

Con i18n si intende il processo di adattamento ad altre nazioni e culture.
Attualmente la libreria i18n si occupa di aiutare il programmatore nell'utilizzo dei model Doctrine configurati in i18n.

Strumenti

amos-debugger

Amos debugger è un plugin di Firebug per Firefox che ti permette di debuggare l'applicazione.
Nel file di configurazione alla sezione [server] si possono impostare router = true e dispatcher = true
Esempio di utilizzo:

Normal log message
Debugger::log('Message/Array/Object');

Info log message
Debugger::info('Message/Array/Object');

Warning log message
Debugger::warning('Message/Array/Object');

Error log message
Debugger::error('Message/Array/Object');
http://www.amos-framework.com/AmosFrameworkForFirebug

wiki.amos-framework.com

Il wiki in fase di sviluppo è raggiungibile all'indirizzo http://wiki.amos-framework.com

Un prodotto di

Elite Division Logo