QCubed

Da WikiLilis.

Introduzione

QCubed è un framework php della famiglia RAD (Rapid Application Development) orientato (ma non limitato) allo sviluppo di applicazioni web db-orientened.

Tra le caratteristiche più importanti abbiamo:

  • astrazione di elementi del dom html come oggetti php
  • salvataggio automatico dello stato degli oggetti (vengono serializzati automaticamente e salvati nella sessione)
  • programmazione orientata ad eventi trasparente (il framework genera automaticamente codice javascript/jquery)
  • possibilità di abilitare/disabilitare interazioni AJAX
  • generazione automatica di codice ORM da un DB esistente

Ne vedremo le potenzialità con questo articolo/tutorial.

Installazione, creazione di un db di test e configurazione

Le seguenti istruzioni si riferiscono ad un ambiente ubuntu 14.04 server amd64 liscio su cui verrà installato apache, php e mysql (oltre che ovviamente a qcubed).

Innanzitutto installiamo i pacchetti:

 apt-get install libapache2-mod-php5 php5-mysql mysql-server-5.6 unzip

per comodità lasciamo vuota la password di mysql root, ma in un ambiente non di test conviene impostarla

poi creiamo il db:

mysql -u root;
create database qcubed;
connect qcubed;
create table anagrafica (nome varchar(100), cognome varchar(100), id int primary key not null auto_increment);
\q

ora installiamo qcubed:

cd /var/www/html
wget https://github.com/qcubed/framework/archive/2.2.3.zip
unzip 2.2.3.zip
chown -R www-data framework-2.2.3
ln -s framework-2.2.3/ qcubed

apriamo il browser su http://hostname/qcubed, dovrebbe apparirci una pagina simile alla seguente (l'ip 192.168.56.102 è quello che ha assegnato virtualbox alla macchina virtuale che sto utilizzando per scrivere questo tutorial)

Qcubed1.png

Clickare dunque su "click here to start the installation wizard":

Qcubed2.png

confermare la cartella di installazione clickando su "Next", comparirà una pagina che chiede alcuni settaggi che per il momento potete ignorare:

Qcubed3.png

e la configurazione del db:

Qcubed4.png

il sistema già propone per default di utilizzare il database qcubed da utente mysql root senza password, se dunque non avete customizzato la configurazione potete lasciare tutto inalterato, altrimenti bisogna adattare i parametri, clickare dunque su "Write Configurtion".

Se tutto è andato a buon fine vi comparirà una pagine che vi conferma che il file di configurazione è stato salvato:

Qcubed5.png

prima di proseguire bisogna abilitare il proprio indirizzo ip all'amministrazione del control-panel di qcubed, se avete installato tutto su "localhost", ossia sulla macchina da cui lanciate il browser non c'è bisogno di fare niente, altrimenti aprite una shell e modificate il file di configurazione ad esempio con il comando nano:

nano -w /var/www/html/qcubed/includes/configuration/configuration.inc.php

e cercate la riga:

define('ALLOW_REMOTE_ADMIN', false);

sostituite false con l'ip della macchina da cui state operando con il browser, racchiudendolo tra apici, nel mio caso ad esempio ho utilizzato '192.168.56.1'

tornate al browser e clickate dunque su "Launch the config checker", se tutto è andato bene vi apparirà una pagina simile alla seguente:

Qcubed6.png

Generazione di codice ORM e form drafts

clickate su "Code Generator" per far si che qcubed auto generi il codice ORM più alcune form per la visualizzazione/modifica dei dati che possono essere usate come base di partenza per la vostra applicazione, se tutto è andato a buon fine vi apparirà la seguente pagina:

Qcubed7.png

tornate con il browser alla pagina precedente (back) e clickate su "View Form Drafts", vi comparirà:

Qcubed8.png

clickate dunque su "Create New" e potrete caricare un nuovo record della tabella "anagrafica" nel db:

Qcubed9.png

inserite qualcosa e clickate su "Save", il record verrà inserito nel db e vi apparirà l'altra "form draft" dedicata all'elenco dei record:

Qcubed10.png

Utilizzo del codice ORM

Per ogni tabella del db qcubed genera un modello ORM, in pratica una classe php con una serie di metodi orientati alla gestione della tabella, vediamo un pò snippet php di esempio (creiamo gli script in /var/www/html/ come riferimento)

Numero di record

<?php
  require_once 'qcubed/qcubed.inc.php';
  echo "Numero di record nella tabella anagrafica: ".Anagrafica::CountAll()."\n";
?>

che potete lanciare da shell con:

cd /var/www/html
php5 nomefile.php

lo script funziona anche via web ma andrebbe modificato

Inserimento nuovo record

<?php
  require_once 'qcubed/qcubed.inc.php';
  $a = new Anagrafica();
  $a->Nome ='pippo';
  $a->Cognome = 'paperino';
  $a->Save();
?>

Forms

Form di esempio con evidenza della gestione dello stato

cd /var/www/html

creare un file test.php dal seguente contenuto:

<?php
	require_once 'qcubed/qcubed.inc.php';

	class TestForm extends QForm {

		protected $numero;
		protected $tbox;
		protected $button;

		function Form_Create() {
			parent::Form_Create();
			
			$this->tbox = new QTextBox($this);
			$this->tbox->Name = 'Numero';
			$this->tbox->Text = '0';

			$this->button = new QButton($this);
			$this->button->Text = 'Incrementa';

			$this->button->addAction( new QClickEvent(), new QServerAction('incrementa') );
		}

		function incrementa() {
			$this->numero++;
			$this->tbox->Text = $this->numero;
		}
	}

	TestForm::Run('TestForm');
?>

ed un file test.tpl.php dal seguente contenuto:

<?php
  require_once 'qcubed/includes/configuration/header.inc.php';<br>
?><br>
<h1>Tutorial n.1</h1><br>
<?php<br>
        $this->RenderBegin();<br>
        $this->tbox->RenderWithName();<br>
        $this->button->Render();<br>
        $this->RenderEnd();<br>
        require_once 'qcubed/includes/configuration/footer.inc.php';
?>

poi aprite il browser per lanciare lo script test.php e clickate una o più volte sul pulsante "Incrementa".

Vediamo ora di capire cosa è successo.

Innanzitutto abbiamo creato un nostra classe estendendo l'oggetto QCubed QForm, abbiamo poi dichiarato al suo interno una proprietà numero che utilizzeremo per gestire un intero, due object handle relativi ad una textbox tbox ed ad un pulsante button, poi abbiamo sovrascritto il metodo Form_Create per instanziare i due oggetti.

Successivamente abbiamo collegato un evento di tipo "mouse click" al bottone collegandolo in callback al metodo 'incrementa', implementato in modo da incrementare il valore della variabile numero e lo assegna alla proprietà Text di tbox;

Infine abbiamo detto a QCubed di lanciare la nostra Form con il metodo Run.

Cosa fa il metodo Run dietro le quinte? esegue la form (lancia una serie di metodi, Form_create, Form_load, etc., poi carica il template 'test.tpl.php', lo renderizza e lo invia al browser, qcubed si preoccuperà di autogenerare le jquery callback che faranno in modo che clickando sul bottone venga effettuato un post alla form richiamando il metodo incrementa e rigenerando l'intera form che verrà mostrata al browser nuovamente ma con il valore numerico aggiornato.

Come fa qcubed a gestire lo stato dell'oggetto (e quindi i valori assegnati alle varie proprietà?), semplicemente serializza/unserializza l'oggetto TestForm e lo salva in una variabile di sessione. Lo sviluppatore dunque non si deve preoccupare di nulla e sviluppa secondo un paradigma simile a quello utilizzato in applicazioni desktop oriented.

Vogliamo ora fare in modo che la nostra form funzioni in modalità AJAX? nulla di più semplice, basta modificare la riga:

$this->button->addAction( new QClickEvent(), new QServerAction('incrementa'));

con

$this->button->addAction( new QClickEvent(), new QAjaxAction('incrementa'));

Qcubed si occuperà di tutto, al click fara una ajax call, ma stavolta la form invece di generare un completo dom html, si limiterà a cambiare solo ciò che non riflette lo stato dell'oggetto TestForm, qcubed è capace anche di aggiungere/rimuovere oggetti dal dom.

Metacontrols

Abbiamo precedentemente visto le cosiddette Form Drafts, ossia delle form (che nella struttura sono come quella dell'esempio precedente), che consentono di aggiungere/modificare/cancellare records dalle tabelle del db configurato. Se analizziamo il codice sorgente delle form drafts vedremo come vengono utilizzati i MetaControls ossia un set di oggetti che semplifica la realizzazione di form per l'editing dei record del db. Si consiglia di analizzarle per comprendere quanto siano comodi questi oggetti per sviluppare la nostra applicazione.

Approfondimenti

Avete potuto assaggiare solo alcune delle possibilità di QCubed, il framework sebbene contenuto e snello fa tanto altro, gestione delle relazioni 1-n o n-m, sistema di caching, datagrid, pager, linguaggio di interrogazione basato su QQN alternativo ad Sql e di semplice utilizzo, etc. etc. Scrivere qui un intero manuale di qcubed non avrebbe molto senso (soprattutto se a lavorare su questa cosa si è in pochi), ma ti invitiamo comunque a modificarlo ed integrarlo. C'è anche un thread sul forum.lilis.it dedicato a qcubed dove puoi chiedere un minimo di supporto (compatibilmente con la disponibilità degli iscritti). Per approfondimenti ti consigliamo di visitare il sito web principale:

https://github.com/qcubed/framework

o il vecchio sito web:

http://qcu.be/