Creare un nuovo strumento

Nelle prossime righe verrà indicata l'architettura base di uno strumento e ciò che lo sviluppatore deve creare per poterlo integrare nel Sistema.

Ogni strumento deve essere composto da:

• un modello, che definisce lo strumento sia a livello di database sia a livello di classe che estende AppModel
• un controller, dove sono definite, oltre ad altre, le funzioni di creazione/modifica di uno strumento
• una vista, che ne permette la visualizzazione
• le api, che gli permettono di comunicare con gli altri moduli
• i “files stringhe” che permettono di gestire la visualizzazione in inglese o italiano delle stringhe di quello strumento
  

Esempio: creazione di uno strumento chiamato “Calendars”.

1. Creazione delle CARTELLE relative allo strumento:
   1. home/app/apis/calendars: contiene le api specifiche del nuovo strumento
   2. home/app/views/calendars: contiene i files che permettono la visualizzazione dello strumento
2. Creazione dei FILES relativi allo strumento:
   1. home/app/models/calendar.php: viene definita la classe Calendar e si specificano le sue dipendenze con altre classi.
   2. home/app/controllers/calendars_controller.php: viene definito il controller di Calendar. Le sue funzioni dipendono dalla tipologia dello strumento e da ciò che lo stesso deve svolgere; presumibilmente, se lo strumento Calendar dovesse servire a creare un nuovo calendario con gli impegni di ogni utente, nel file calendars_controller.php sarebbero racchiuse - tra le altre - le funzioni create ed edit che gestirebbero la creazione e modifica di un nuovo calendario per ogni singolo utente.
   3. home/app/strings/ita/calendars.tpl: file che racchiude le coppie 'identificatore-stringa italiana' per il controller e per le view dello strumento.
   4. home/app/strings/eng/calendars.tpl: file che racchiude le coppie 'identificatore-stringa inglese' per il controller e per le view dello strumento.
   5. home/app/apis/calendars/calendars_api_controller.php: file contenente le funzioni che permettono allo strumento di interfacciarsi con gli altri moduli.
   6. home/app/apis/calendars/calendars_api_view.php: file contenente la classe CalendarApiView che estende ApiView.
   7. home/app/apis/calendars/calendars_event_handlers.xml: file xml nel quale sono riportati gli eventi ai quali risponde lo strumento stesso.

Ci sono poi dei files e delle cartelle che vengono create solo se lo strumento ne richiede l'utilizzo, come la cartella home/app/apis/calendars/views con i file .tpl delle viste relative alle api.
All'interno di home/app/views/calendars vanno inseriti i file .tpl che gestiscono la vista dei componenti dello strumento (come ad esempio edit.tpl, create.tpl, addstep.tpl etc…); questi file quindi dipendono dalla struttura dello strumento stesso.

Per la creazione di un nuovo strumento è utile sapere anche quali sono le funzioni che, indipendentemente dal tipo di strumento, vanno implementate; queste sono le funzioni di permission, ovvero quelle che gestiscono i permessi, riportate di seguito:

• Es. PERMISSION GET OBJECTS per lo strumento AGENDA - produce un array con all'interno tutte le agende prodotte dal modulo agenda.

  function permissionsGetObjects() {
	
	$_agendas['Agenda:*'] = $this->s('ALL_AGENDAS');
	
	$agendas = $this->Agenda->findAll();
	foreach ($agendas as $Agenda) {
		
		$id = $Agenda['Agenda']['id'];
		$_agendas['Agenda:'.$id] = $Agenda['Agenda']['title'];
		
	}
	return $_agendas;
	
}

• Es. PERMISSION GET ACTIONS per lo strumento AGENDA - produce un array di stringhe contenente tutte le azioni prodotte dal modulo agenda.

  function permissionsGetActions() {
	
	return array( 
		'admin' 	=>	$this->s('PERMISSION_ADMIN_DESCRIPTION'),
		'view' 	=>	$this->s('PERMISSION_VIEW_DESCRIPTION'),
		'create'	=>	$this->s('PERMISSION_CREATE_DESCRIPTION'),
		'upload'	=>	$this->s('PERMISSION_UPLOAD_DESCRIPTION'),
		'rate'		=>	$this->s('PERMISSION_RATE_DESCRIPTION'),
		'download'	=>	$this->s('PERMISSION_DOWNLOAD_DESCRIPTION'),
		'edit' 		=>	$this->s('PERMISSION_EDIT_DESCRIPTION'),
		'delete' 	=>	$this->s('PERMISSION_DELETE_DESCRIPTION'),
	);		
}

• Es. PERMISSION GET ROLES per lo strumento AGENDA - produce un array dove sono definiti i ruoli del modulo agenda.

  function permissionsGetRoles() {
	
	$roles['moderator']['label'] = $this->s('AGENDA_MODERATOR');
	$roles['moderator']['values'] = array( 	'admin' =>'deny',
						'edit'  =>'allow',
						'delete'=>'deny'
					);		
					
	$roles['administrator']['label'] = $this->s('AGENDA_ADMINISTRATOR');
	$roles['administrator']['values'] = array(  'admin' =>'allow',
						    'edit'  =>'allow',
						    'delete' =>	'allow'
						);
	return $roles;
}

Oltre alle funzioni che gestiscono i permessi, se il nuovo strumento fa parte della classe degli strumenti deliberativi - come ad esempio lo strumento di consultazione certificata -, è fondamentale inserire il metodo toolinfo, che restituisce un array con le informazioni sullo strumento:

• Es. TOOLINFO dello strumento Consultazione Certificata:

  function toolInfo() {
	
	$info['owner'] = 'Polls';
	$info['toolName'] = $this->s('POLLS_NAME');
	$info['toolDescription'] = $this->s('POLL_TOOL_DESCRIPTION');
	$info['createApiMethod'] = 'toolCreate';
	$info['editPath'] = '/polls/edit/%d';
	$info['viewPath'] = '/polls/view/%d';
	$info['accessPermission'] = 'view';
	
	$info['resultPath'] = '/polls/showresults/%d';
	$info['resultPermission'] = 'view_results';
	
	return $info;
}

Tutte queste funzioni sono gestite tramite gli eventi e riportate nei file XML all'interno delle api di ogni strumento.

All'interno del controller che gestisce il nuovo strumento, per utilizzare le API relative agli strumenti con i quali relazionarsi, basta richiamare le stesse attraverso la funzione “loadApi()”. Riportiamo qui di seguito l'esempio di come lo strumento 'Infodisc' richiama le API del modulo wikitool:

[...]
$this->loadApi('Wikitool');
$wiki=$this->WikitoolApi->getWikiFor('Infodisc',$id);
$this->set('wiki',$wiki );
[...]

indietro - avanti