Tutorial

Esempio d'uso
Le componenti di base essenziali per poter realizzare un progetto con
SolsticEngine sono essenzialmente le seguenti:

• la directory "core" del pacchetto progetto
• il programma "container" generalmente rappresentato dal file container.php
• il file di configurazione dell'ambiente pathconfig.inc.php
• il file XML di configurazione action chiamato action-config.xml

A livello più generale la directory "core" contiene il motore vero e proprio del framewrok mentre i tre file descritti rappresentano l'ambiente di esecuzione della particolare istanza del framework. Questo è un modo che rende possibile avere più progetti che condividono lo stesso nucleo di librerie quindi è bene fin da subito considerarli come due gruppi distinti: il core e il container.
Per prima cosa individuare le componenti appena elencate nel pacchetto di rilascio del progetto e copiarle in una direcory creata all'interno della direcotry documenti di Apache.
Supponendo che quest'ultima sia public_html e volendo creare una direcory di progetto chiamata "prova" questo potrebbe essere un valido scenario:

/public_html
    /prova
        /core
        container.php
        patchconfig.inc.php
        action-config.xml

E' importante che il contenuto della direcotry core non venga modificato quindi per adesso non scendiamo nei dettagli del suo contenuto. E' anche importante che i tre file menzionati si trovino nello stesso percorso

Configurazione dell'ambiente
Il file di configurazione d'mabiente pathconfig.inc.php mantiene alcune impostazioni importantissime ed essenziali per il funzionamento del framework. In particolare queste servono per mantenere le posizioni all'interno del filesystem delle componenti del sistema e per modificarne alcuni comportamenti.
A questo punto è necessario configurare l'ambiente perchè possa funzionare e per fare questo bisogna aprire il file pathconfig.inc.php.
La costante relPathSolsticeLib permette al particolare container di individuare la posizione all'interno del filesystem del core di SolsticEngine sotto forma di percorso di directory relativo rispetto alla posizione attuale del container.
Nel nostro caso il nucleo è contenuto all'interno della directory "core" quindi la definizione assume questa forma:

define( 'relPathSolsticeLib', 'core/' );

Ci sono altre due costanti fondamentali: la directory di base dei sorgenti Controller e la directory base per i file di interfaccia (View). Decidiamo, in maniera un pò disordinata, che tali risorse saranno messe nella root principale di progetto, andando a definire le costanti come segue:

define( 'relPathClassProject', '/' );
define( 'relPathFrontendProject', '/' );

Fatta questa operazione, e tralasciando per adesso ogni altro aspetto del file di configurazione ambiente, il framework è già funzionante ed è possibile provarlo chiamando la url:

http://localhost/prova/container.php

Tuttavia al momento non succede nient'altro che la comparsa di un messaggio di errore del framework perchè manca la cosa più importanti: cosa deve fare il vostro progetto e per essere più precisi la sua logica applicativa e l'interfaccia utente.

L'idea che sta alla base del framework è la seguente: a seconda di una determinata url che ti chiedo, tu framework esegui una specifica logica applicativa e, a seconda di quello che ti impartisco in essa dovrai mostrarmi una determinata interfaccia utente.
Nello schema sottostante viene riepilogato a grandi linee lo schema di funzionamento MVC seguito da SolsticEngine:

Container
|
SolsticEngine______________________
                |                |
                Controller       |
                                 View

Il Container, chiamato direttamente dall'utente serve da ambiente di esecuzione del motore SolsticEngine che, una volta avviato, manda in esecuzione il Controller e successivamente la View.
Queste due ultime componenti sono ovvimente definite dallo sviluppatore sotto forma, rispettivamente, di una classe PHP e di un semplice file PHP che funge da pagina web.

Si è detto che una delle caratteristiche di SolsticEngine è quella di avere una logica comportamentale del processo MVC completamente XML driven. Questo significa che avremo un file di configurazione, action-config.xml dove sono descritte le diverse url prese in gestione dal framework.
Ogni url rappresenta un'azione che chiediamo al framework di prendere in carica, per questo è giusto introdurre il concetto di action.
Ogni entry del file XML di configurazione rappresenta proprio una action dove per ogn'una di esse è definita quale logica applicativa eseguire (la classe e il metodo da chiamare) e l'interfaccia utente (la lista delle possibili pagine da mostrare in output). Ogni action è identificata da un nome che sarà anche poi parte della url stessa che chiameremo.
Di seguito un esempio di action:

<action name="helloworld" 
    actionclass="StarterAction.class.php" actionclassname="StarterAction"
    method="helloworld_start" renderengine="STD" >
    <forward name="success" tile="helloworld.tile.php" />
</action>

Come si può vedere ritroviamo tutti gli elementi menzionati fin'ora:

• name è il nome della action
• actionclass (e actionclassname) i riferimenti alla classe Controller
• method è il nome del metodo dela classe Controller da chiamare
• <forward> è il riferimento alla pagina di interfaccia View da mostrare una volta che il Controller ha finito l'esecuzione.
  Adesso che abbiamo visto dove andare a definire i riferimenti per il Controller e per la View non ci resta altro che implementarli.</forward>

Implementare la logica applicativa e l'interfaccia utente
Il framework SolsticEngine segue la filosofia MVC per tale motivo dobbiamo realizzare delle risorse per la logica applicativa (Controller, per adesso il Model non lo consideriamo ancora in modo esplicito) e delle risorse per l'interfaccia utente (View).
Prima di tutto però dobbiamo decidere cosa far fare al nostro sistema. Senza rompere alcuna tradizione il nostro primo obiettivo sarà la stampa del classico "Hello World!!!" all'interno di una pagina web.
La nostra logica di business richiede quindi una classe che faccia da controller che esegua il comando di stampa, chiameremo questa classe così:

StarterAction.class.php

Mentre la nostra interfaccia utente sarà un semplice file php che contiene una pagina web minimale, lo chiameremo:

helloworld.tile.php

Nella fase di configurazione del motore avevamo deciso di lasciare nella root principale di progetto le risorse per il controller e per la view, quindi è proprio qui che metteremo i due file appena descritti.

Dettagli di implementazione
Una classe controller di SolsticEngine è essenzialmente una classe che contiene una serie di metodi che devono rispondere ad una determinata firma per poter funzionare correttamente ed essere utilizzate dal framework.

class StarterAction {

    public function __construct() {
    }

    public function helloworld( AmbientManager $ambientManager,
            RequestBean $requestBean, $formBean) {
        echo( "Hello World!!!" );
        $requestBean->setTileForward( "success" );
    }
}

Il codice precedente è la nostra classe controller. Il metodo, chiamato "helloworld" come anche specificato nel file di configurazione visto prima, ha tre argomenti che il framework ci farà trovare valorizzati per l'uso che più conviene allo sviluppatore.
Tralasciando questo importante aspetto per adesso vediamo la parte principale della logica di business che altro non fa che stampare la classica frase di saluto.
Prima di terminare bisogna soffermarsi sull'ultima riga di codice, importantissima per la fase di elaborazione della View. Precedentemente, nella descrizione dell'elemento <action> del file di configurazione, è stato detto che la sezione <forward>
"è il riferimento alla pagina di interfaccia View da mostrare una volta che il Controller ha finito l'esecuzione."
rivediamo come era impostato l'elemento <forward>:</forward></forward></action>

<forward name="success" tile="helloworld.tile.php" />

In questo caso il riferimento è identificato con l'etichetta "success" e la pagina da utilizzare come view è helloworld.tile.php
L'etichetta "success" è proprio quella che stiamo utilizzando nell'impostazione del tileForward dell'oggetto $requestFormBean. Senza entrare nei dettagli stiamo dicendo al framework di scegliere tra tutte le possibili view definite per quella action quella con etichetta "success".
Questo sistema permette di definire un insieme di differenti view che potranno essere scelte nella fase Controller a seconda della situazione determinata dall'elaborazione. Una volta entrati nell'esecuzione della logica di business infatti potrebbero verificarsi differenti situazioni che richiedono diversi "punti di uscita". In effetti è possibile definire più di un elemento <forward> all'interno di una stessa action.</forward>

La pagina di view, ovvero il file helloworld.tile.php ha la semplice struttura:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="it" xml:lang="it">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>First simple example in SolsticEngine</title>

</head>

<body>
    <div id="container">
        <p>
            This is a test page!
        </p>
    </div>
</body>
</html>

In definita abbiamo la classe che funge da Controller, abbiamo la risorsa per la View. Tutto è pronto per la prima accensione del nostro motore.

Url da invocare
La relazione che c'è tra nome della action e url da chiamare è molto semplice: la action da chiamare sarà definita come parametro in request GET. Tale parametro si chiama "c".
Così per chiamare la action "helloworld" appena analizzata la nostra chiamata a container.php sarà la seguente:

http://localhost/prova/container.php?c=helloworld