====== 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".**\\

  - Creazione delle CARTELLE relative allo strumento:
    - home/app/apis/calendars: contiene le api specifiche del nuovo strumento
    - home/app/views/calendars: contiene i files che permettono la visualizzazione dello strumento
  - Creazione dei FILES relativi allo strumento:
    - home/app/models/calendar.php: viene definita la classe Calendar e si specificano le sue dipendenze con altre classi.
    - 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.
    - home/app/strings/ita/calendars.tpl: file che racchiude le coppie 'identificatore-stringa italiana' per il controller e per le view dello strumento.
    - home/app/strings/eng/calendars.tpl: file che racchiude le coppie 'identificatore-stringa inglese' per il controller e per le view dello strumento.
    - home/app/apis/calendars/calendars_api_controller.php: file contenente le funzioni che permettono allo strumento di interfacciarsi con gli altri moduli.
    - home/app/apis/calendars/calendars_api_view.php: file contenente la classe CalendarApiView che estende ApiView.
    - 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 [[gli eventi|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 );
  [...]
\\
\\
\\
\\
[[gli strumenti | indietro]] - [[il modello generale | avanti]]