Abbiamo visto in Guide precedenti come aggiungere comandi a pagine e Viste. Nella maggior parte dei casi, quei comandi richiamano altre pagine ed altre Viste, costruendo così un percorso all'interno della nostra app. Abbiamo però anche già incontrato un caso in cui il comando avrebbe dovuto modificare una Entità, anche superando i permessi dell'Utente che lo clicca.
In questa Guida vediamo come costruire una ECA che esegue un comando cliccato dall'Utente. Una ECA di questo tipo è formata dai seguenti elementi:
| un Evento Endpoint access | predispone il link /eca/parametro1/parametro2 che, quando viene cliccato, attiva la ECA |
| una o più Azioni Request: Get URL query parameter | recuperano dal link uno o più argomenti, necessari alle Azioni e Condizioni successive. Gli argomenti sono scritti così nel link: /eca/parametro1/parametro2?argomento1=valore1&argomento2=valore2. |
| una serie di Azioni e Condizioni | realizzano il comando |
| un'Azione Reindirizza all'URL | al termine dell'esecuzione del comando, porta l'Utente su una specifica pagina della app. In assenza di questa Azione, all'Utente viene mostrato il messaggio di errore "Pagina non trovata". |
Come esempio, costruiamo per la app "Vicinato" il comando "Accetta una consegna", con cui un Utente accetta la Consegna dell'Attrezzo proposta da un altro Utente. L'esempio è abbastanza complesso e applichiamo in essa molte delle tecniche che abbiamo visto nelle Guide precedenti, compreso l'uso di Viste dentro le ECA. L'accettazione di una Consegna ha infatti una serie di effetti sulla Consegna stessa, sulla Richiesta cui si riferisce e sull'Attrezzo prestato:
- cambia lo stato della Consegna da "in consegna" a "accettato"
- sposta l'Attrezzo dal consegnante al ricevente (es. dal Proprietario al Richiedente o a una Sede)
- se è la prima Consegna, cambia lo stato della Richiesta da "aperta" a "in corso" e scrive la data corrente come data di inizio prestito della Richiesta
- se è la Consegna al Proprietario, cambia lo stato della Richiesta a "conclusa" e scrive la data corrente come data di fine prestito della Richiesta
Ecco come costruirla passo per passo:
| crea una Vista che ci servirà per contare quante Consegne ha una Richiesta (se non ce ne sono, la Consegna in esame è la prima) | In Strutture - Viste crea una Vista "Conta Consegne di Richiesta" che elenca Contenuti di tipo "Consegna". In Relazioni aggiungi il Campo che rimanda dalle Consegne alla loro Richiesta Contenuto - Contenuto referenziato da field_richiesta_consegna e rinomina "Richiesta". In Filtri contestuali aggiungi il Campo che identifica la Richiesta, cioè Contenuto - ID con Relazione "Richiesta". |
| crea la ECA | In Configurazione - ECA clicca Add new model. Clicca l'icona ℹ️ e in Etichetta digita il nome per la ECA, es. "Accetta Consegna" |
| predisponi il link che attiva la ECA | Aggiungi l'Evento Endpoint access. In First path argument digita "consegna" ed in Second path argument digita "accettazione": la ECA sarà attivata quando un Utente clicca il link /eca/consegna/accettazione |
| recupera dal link l'argomento che identifica la Consegna | Aggiungi l'Azione Request: Get URL query parameter. In Name of token digita "id_consegna" per creare il Token in cui memorizzare l'identificativo della Consegna scritto nel link del comando. In Query parameter name digita "consegna" come nome da cercare nel link: la ECA si attende quindi che nel link vi sia un argomento "consegna" con associato il valore dell'identificativo della Consegna, es: /eca/consegna/accettazione?consegna=143 |
| Memorizza negli omonimi Token le Entità che il comando deve modificare o utilizzare: Consegna, Richiesta collegata alla Consegna, Sede della Consegna e Attrezzo collegato alla Richiesta. | Aggiungi l'Azione Entity: load. In Name of Token digita "consegna" per creare il Token in cui memorizzare la Consegna. In Load entity from seleziona Type and ID per identificare l'Entità tramite il suo tipo e il suo identificativo. In Tipo di Entità seleziona Contenuto, perché la Consegna è di quel tipo. In ID Entità digita [id_consegna] perché l'identificativo della Consegna è il valore ricevuto nel link. Aggiungi l'Azione Entity: load. In Name of Token digita "richiesta". In Load entity from seleziona Type and ID. In Tipo di Entità seleziona Contenuto. Dalla gerarchia copia il Token corrispondente all'identificativo della Richiesta collegata alla Consegna es. [node:field_richiesta_consegna:target_id]. In ID Entità incolla quel Token e modificalo in [consegna:field_richiesta_prestito:target_id] perché prelevi il valore dal Token "consegna" Aggiungi l'Azione Entity: load. In Name of Token digita "attrezzo". In Load entity from seleziona Type and ID. In Tipo di Entità seleziona Contenuto. Dalla gerarchia copia il Token corrispondente all'identificativo dell'Attrezzo collegato alla Richiesta es. [node:field_attrezzo_richiesta:target_id]. In ID Entità incolla il Token e modificalo in [richiesta:field_attrezzo_richiesta:target_id] Aggiungi l'Azione Entity: load. In Name of Token digita "sede". In Load entity from seleziona Type and ID. In Tipo di Entità seleziona Contenuto. Dalla gerarchia copia il Token l'identificativo della Sede collegata alla Consegna es. [node:field_sede_consegna:target_id]. In ID Entità incolla il Token e modificalo in [consegna:field_sede_consegna:target_id] |
| Memorizza nel Token "ricevente" l'Utente corrente che sta accettando l'Attrezzo e nel Token "consegnante" l'Utente che consegna l'Attrezzo, cioè l'Autore della Consegna | Aggiungi l'Azione Current user: load. In Name of token digita "ricevente". Aggiungi l'Azione Entity: load. In Name of Token digita "consegnante". In Load entity from seleziona Type and ID. In Tipo di Entità seleziona Utente. Dalla gerarchia copia il Token dell'identificativo dell'Autore di un nodo [node:author:uid]. In ID Entità incolla il Token e modificalo in [consegna:author:uid] |
| Assegna alla ECA i privilegi di Amministratore, per consentire all'Utente corrente di modificare lo Stato della Richiesta, su cui potrebbe non aver diritti di modifica. | Aggiungi l'Azione User: switch current account. In User ID digita "1", che è l'identificativo di Amministratore |
Modifica la Consegna:
| Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il nome del Campo che memorizza lo Stato "field_stato_consegna". In Valore del Campo digita "accettata", che è il nome interno dello stato. In Entità digita "consegna". Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il nome del Campo che memorizza l'Utente che accetta l'Attrezzo "field_accettazione_consegna". In Valore del Campo digita "[ricevente]". In Entità digita "consegna". Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il nome del Campo che memorizza la data di accettazione "field_data_accettazione_consegna". Dalla gerarchia copia il Token della data corrente [current-date] e incollalo in Valore del Campo. In Entità digita "consegna". |
| Modifica l'Attrezzo, memorizzando nel suo Campo "Dove" il luogo dove avviene la Consegna | Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il nome del Campo dell'Attrezzo che ne memorizza la posizione es. "field_dove_attrezzo". Dalla gerarchia copia il Token dell'identificativo generico di un Contenuto [node:nid]. Incollalo in Valore del Campo e modificalo in [sede:nid]. In Entità digita "attrezzo". Attiva Salva |
| Distingui il caso di Consegna al Proprietario (A) dal caso di Consegna ad altri (B) | Aggiungi un gateway (rombo). Da qui partono due percorsi alternativi (A e B) |
A) Se la Consegna è al Proprietario:
| Dal gateway aggiungi una Azione. Sul connettore che va dal gateway a questa Azione aggiungi la Condizione Compare two scalar values. In First value digita il Token che contiene il titolo della Sede [sede:title]. In Operatore di comparazione seleziona contiene. In Second value digita "Proprietario". In questo modo le Azioni che seguono sono eseguite solo se la Consegna è al Proprietario. Nell'Azione seleziona Entity: set field value. In Nome del Campo digita il nome del Campo della Richiesta che ne memorizza lo Stato "field_stato_richiesta". In Valore del Campo digita "conclusa". In Entità digita "richiesta". Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il nome del Campo della Richiesta che memorizza la data di fine prestito "field_fine_richiesta". Dalla gerarchia copia il Token della data corrente [current-date:html_date] e incollalo in Valore del Campo. In Entità digita "richiesta". Attiva Salva |
B) Se la Consegna è altrove:
| Dal gateway aggiungi una Azione. Sul connettore che va dal gateway all'Azione aggiungi la Condizione Compare two scalar values. In First value digita "[sede:title]". In Operatore di comparazione seleziona contiene. In Second value digita "Proprietario". Attiva Nega la condizione. In questo modo le Azioni che seguono sono eseguite solo se la Consegna non è al Proprietario. Aggiungi l'Azione Entity: set field value. In Nome del Campo digita "field_stato_richiesta". In Valore del Campo digita "in_corso". In Entità digita "richiesta". Per verificare se la Consegna che stiamo esaminando è la prima per la sua Richiesta, richiama la Vista "Conta Consegne di Richiesta" passandole l'identificativo della Richiesta e memorizza l'elenco delle Consegne nel Token "elenco_consegne"
Aggiungi un secondo gateway (rombo). Da qui partono i due percorsi alternativi B1 e B2 |
B1) Se la Consegna è la prima per la Richiesta:
| Dal secondo gateway aggiungi una Azione. Sul connettore che va dal gateway a questa Azione aggiungi la Condizione Compare number of list items, che confronta il numero di elementi di una lista con un numero. In Name of token containing the list digita [elenco_consegne]. In Operatore di comparazione seleziona uguale a. In Second value digita "1". In questo modo le Azioni che seguono sono eseguite solo se la Consegna è l'unica, cioè la prima. Aggiungi l'Azione Entity: set field value. In Nome del Campo digita il Campo della Richiesta che ne memorizza la data iniziale "field_inizio_richiesta". Dalla gerarchia copia il Token della data corrente [current-date:html_date] e copialo in Valore del Campo. In Entità digita "richiesta". |
| B2) Se la Consegna non è la prima per la Richiesta: non fare nulla | Dal secondo gateway aggiungi una Azione. Sul connettore che va dal gateway a questa Azione aggiungi la Condizione Compare number of list items, che confronta il numero di elementi di una lista con un numero. In Name of token containing the list digita [elenco_consegne]. In Operatore di comparazione seleziona uguale a. In Second value digita "1". Attiva Nega la condizione. A questo ramo non segue alcuna Azione. |
| Ricongiungi tutti i percorsi | Aggiungi un terzo gateway. Tira connettori da tutte e tre i percorsi A, B1 e B2. |
| Riporta l'Utente alla pagina della Richiesta, dove aveva cliccato il comando | Aggiungi l'Azione Reindirizza all'URL. In URL digita "/node/[richiesta:nid]", perché [node:nid] è il Token che contiene l'identificativo di un Contenuto e quindi [richiesta:nid] contiene l'identificativo della Richiesta memorizzata nel Token "richiesta". |