Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- gwusermanual:interface:widget:gw_digital_document_widget [2019/11/13 16:07]
sabrina.sonno [Configurazione]
+++ gwusermanual:interface:widget:gw_digital_document_widget [2024/05/10 15:42] (versione attuale)
giorgio.scali [DDOC2]
@@ Linea 39: / Linea 39: @@
 I passaggi base per configurare il DDOC sono i seguenti: \\
 . **progettare** il documento, definendo quali attributi vanno in quali sezioni, e quale deve essere la sequenza corretta\\
@@ Linea 56: / Linea 57: @@
 . configurare almeno un **Template del DDOC**, definendo il numero e l'ordine delle sezioni, e attribuendo un Detail Layout a ciascuna di esse. Designare una delle sezioni come header, ovvero la sezione che sarà visualizzata in modo fisso, nella parte superiore in alto del controllo. Nella intestazione del template slezionare, se previsto, il Report definito al punto 4\\
+{{:gwusermanual:interface:widget:ddoc-template.png|}}
 . configurare tra gli attributi il **widget GW_DIGITAL_DOCUMENT_WIDGET**, configurando tra i parametri il nome del Template\\
@@ Linea 68: / Linea 71: @@
-===== MODELLO DATI =====
+===== Modello Dati =====
 {{:gwusermanual:interface:gw_digital_document_modello_dati.png?400|}}
-===== TABELLE IN DETTAGLIO =====
+===== Dettaglio delle Tabelle =====
@@ Linea 81: / Linea 84: @@
   * **fk_class**: Integer, required. Chiave esterna con gwm_classes;
   * **status_column**: String, optional. Nome della colonna della classe che verrà usata per recuperare lo stato del record corrente. Il valore dello stato verrà passato come parametro (//entityStatus//) nell’invocazione dei vari metodi groovy (vedi sotto). Se omesso, verrà passato null;
-  * **groovy**: String, optional. Nome del file groovy che ospiterà una class java, la quale dovrà implementare i seguenti metodi dell'interfaccia //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigAbs// oppure estendere la class //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigImpl// (che ne è l’implementazione di default):\\  <code java>public Boolean isVisible(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isEditable(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isDefaultSelected(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> L'utente configuratore, di volta in volta, avrà a disposizione tutti i parametri in ingresso per decidere, ritornando //true// o //false//, se abilitare o negare lo specifico permesso. All'interno dei corpi dei metodi da implementare saranno disponibili anche tutti i servizi normalmente disponibili nei groovy di classe (accedibili con notazione 	//services.identificativo_servizio//). Se il groovy non venisse dichiarato verrà usata un'implementazione di default che abiliterà tutti i permessi. Da ricordare comunque che continuano ad operare sempre e comunque tutti i meccanismi di ACL, statica e dinamica, che sono propri del dettaglio di classe, e che verranno applicati a monte: solo in caso di esito positivo si procederà anche a valutare il responso della classe nel groovy. Inoltre, per evitare di riscrivere nel groovy controlli doppi, se per un dato set di input //isVisible()// dovesse ritornare false e, per gli stessi input //isEditable()// dovesse invece ritornare //true//, la sezione non verrebbe comunque visualizzata. Quindi va tenuto presente che il valore ritornato da //isEditable()// sarà valutato solo per le section per cui l’esito di //isVisible()// è stato positivo. Con //isDefaultSelected// si decide quale section il DDOC presenterà appena aperto. Anche //isDefaultSelected()// verrà valutato solo se //isVisible()// e //isEditable()// abbiano precedentemente ritornato esito positivo. Di default viene presentata la prima section editabile, o la prima in assoluto se sono tutte in sola visualizzazione.
+  * **groovy**: String, optional. Nome del file groovy che ospiterà una class java, la quale dovrà implementare i seguenti metodi dell'interfaccia //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigAbs// oppure estendere la class //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigImpl// (che ne è l’implementazione di default):\\  <code java>public Boolean isVisible(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isEditable(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isDefaultSelected(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code>
+\\
+L'utente configuratore, di volta in volta, avrà a disposizione tutti i parametri in ingresso per decidere, ritornando //true// o //false//, se abilitare o negare lo specifico permesso. All'interno dei corpi dei metodi da implementare saranno disponibili anche tutti i servizi normalmente disponibili nei groovy di classe (accedibili con notazione 	//services.identificativo_servizio//).
+Se il groovy non venisse dichiarato verrà usata un'implementazione di default che abiliterà tutti i permessi. Da ricordare comunque che continuano ad operare sempre e comunque tutti i meccanismi di ACL, statica e dinamica, che sono propri del dettaglio di classe, e che verranno applicati a monte: solo in caso di esito positivo si procederà anche a valutare il responso della classe nel groovy.
+Inoltre, per evitare di riscrivere nel groovy controlli doppi, se per un dato set di input //isVisible()// dovesse ritornare false e, per gli stessi input //isEditable()// dovesse invece ritornare //true//, la sezione non verrebbe comunque visualizzata.
+Quindi va tenuto presente che il valore ritornato da //isEditable()// sarà valutato solo per le section per cui l’esito di //isVisible()// è stato positivo. Con //isDefaultSelected// si decide quale section il DDOC presenterà appena aperto. Anche //isDefaultSelected()// verrà valutato solo se //isVisible()// e //isEditable()// abbiano precedentemente ritornato esito positivo. Di default viene presentata la prima section editabile, o la prima in assoluto se sono tutte in sola visualizzazione.
 //gwm_ddoc_section//:
@@ Linea 149: / Linea 161: @@
 </code>
+===== API js =====
+Avendo disponibile il //ddocWidget//, è possibile fa riferimento alle seguenti proprietà e function esposte:
+  * property:
+    * **ddocSectionHeader**, di tipo Object. <code js>
+{
+  gwid: 123,
+  fkDdoc: 456,
+  name: 'section_name',
+  label: 'section_label',
+  detailLayoutName: 'section_detailLayoutName',
+  isHeader: true,
+  isVisible: true,
+  isEditable: true,
+  isDefaultSelected: false
+}
+</code>
+    * **ddocSections**, di tipo Object[]. <code js>
+[
+  {
+    gwid: 123,
+    fkDdoc: 456,
+    name: 'section_name',
+    label: 'section_label',
+    detailLayoutName: 'section_detailLayoutName',
+    isHeader: true,
+    isVisible: true,
+    isEditable: true,
+    isDefaultSelected: false
+  },
+  {
+    gwid: 123,
+    fkDdoc: 456,
+    name: 'section_name',
+    label: 'section_label',
+    detailLayoutName: 'section_detailLayoutName',
+    isHeader: false,
+    isVisible: true,
+    isEditable: true,
+    isDefaultSelected: true
+  }
+]
+</code>
+  * function:
+    * **getDDOCSection(name)**, function che, dal parametro //name// (//String//), ritorna un Object. <code js>
+{
+  gwid: 123,
+  fkDdoc: 456,
+  name: 'ddoc_section_name',
+  label: 'ddoc_section_label',
+  detailLayoutName: 'ddoc_section_detailLayoutName',
+  isHeader: false,
+  isVisible: true,
+  isEditable: true,
+  isDefaultSelected: true
+}
+</code>
+    * **isDDOCSectionVisible(name)**, boolean
+    * **isDDOCSectionEditable(name)**, boolean
+    * **isDDOCSectionDefaultSelected(name)**, boolean
+    * **isDDOCSectionHeader(name)**, boolean
+==== Esempi ====
-===== OLD =====
+=== Esempio 1 ===
+Si potrebbe volere, per esempio, in un'azione di dettaglio pronto, eseguire delle operazioni solo se una certa //ddocSection// risultasse //editabile// in quel momento (in base alla valutazione dinamica del grrovy).
+<code js>
+var ddocWidget = detailContainer.getGwWidget({name: 'ddoc_widget'}); //detailContainer provided
+var name = 'section_name'; //known
+var isEditable = ddocWidget.isDDOCSectionEditable(name);
+if(isEditable){
+    //do stuff
+}
+</code>
+=== Esempio 2 ===
+<code js>
+var ddocWidget = detailContainer.getGwWidget({name: 'ddoc_widget'}); //detailContainer provided
+var name = 'section_name'; //known
+var isVisible= ddocWidget.isDDOCSectionVisible(name);
+if(isVisible){
+    //do stuff
+}
+</code>
+===== DDOC2 =====
+Dalla versione **4.6.9** (**issue #1070**), è stato rilasciato anche il widget **gwDigitalDocument2 (DDOC2)**, simile al gwDigitalDocument, con la stessa struttura dei metadati, e stessi parametri xml widget, ma diversa forma grafica e comportamento.
+Al posto delle sezioni individuate dal tab, c'è sempre il **documento pdf in primo piano**.
+La report jasper, può utilizzare il parametro booleano **IS_GW_RECORD_EMPTY** (che viene passato a true nel caso il record geoweb non esista ancora)
+al solo fine di garantire in maniera opportuna la visualizzazione di un documento digitale vuoto, anche in assenza di record.
+Scompare l'apposito button di apertura report nella sezione header.
+La sezione **Header**, anche se non contiene più il button della report e le info di intestazione, **va comunque dichiarata, e nel caso nascosta imponendo un altezza di 0px al relativo layout**. In caso contrario, non viene lanciato l'evento di dettaglio pronto.
+Le intestazioni delle **Section** (i vecchi selettori dei tab, che prima comandavano le parti di dettaglio [i detailLayout] impostate per la sezione), ora sono button. La loro stilizzazione attuale è rimasta la medesima, ma senza l'esplicitazione del concetto di ultimo selezionato
+Al click delle intestazioni delle **Section**, solo in caso di permesso di edit, ora vengono aperti dei **floatingPane modali**, contenenti le medesime parti di dettaglio.
+In caso di solo permesso di visualizzazione, al click sulla intestazione di Sezione avviene lo //scroll sul documento
+pdf// (tramite configurazione dei bookmarks (hyperlink + bookmark level) in IReport 5 / Jaspersosft Studio 6)
+A tale proposito si prega di visionare il video [[https://www.youtube.com/watch?v=XkpJq-P2Gko]]
+I permessi edit/visualize derivano, come prima, dal risultato dinamico computato  dall'esecuzione del groovy configurato.
-Questo nuovo componente di Geoweb nasce con l'obbiettivo di dare maggiore evidenza alla rappresentazione digitale del documento, rispetto a come viene attualmente declinata all'interno di Geoweb. Al momento la rappresentazione del documento è strettamente legata alle logiche di funzionamento e di visualizzazione della scheda dettaglio di classe e talvolta della scheda di processo (procedura), che sono funzionalità di base del framework.
-Queste tendono, in maniera variabile rispetto alla specifica configurazione, a nascondere informazioni base del documento, o comunque sia a non darle il giusto risalto.
-Il problema è che l'utente non capisce chiaramente la differenza quando sta visualizzando la scheda di dettaglio di una classe per la gestione di un documento digitale, rispetto a quando sta  visualizzando, per esempio, la scheda di un asset.
-{{:gwusermanual:interface:gw_digital_document.png?600 |}}
-Lato GUI, si procederà quindi a creare una precisa struttura standard del **DDOC**, sempre riconoscibile dall'utente, che sarà divisa in sezioni (**section**).
-La struttura in sezioni è realizzata come un simil TabContainer, con le intestazioni delle sezioni poste a sinistra, in verticale. Al click su ogni sezione viene mostrato a destra lo specifico layout della sezione.
-La visibilità e l'editabilità di ogni singola sezione possono essere configurate con controllo assoluto, tramite l'implementazione di una class java in un file .groovy (vedi sotto).
-Le sezioni del documento possono essere combinate in maniere differenti formando specifici **template**. All'apertura di una scheda documento, esso viene aperto con il //template// specificato (o con uno di default: il primo trovato, per name in ordine alfabetico).
-La scheda DDOC, nella parte superiore, sopra le //section//, presenta una intestazione fissa, contenente uno specifico detailLayout. Questa è di fatto una //section// speciale, marchiata con lo specifico flag **is_header** (vedi sotto) e ne può esistere solo una per template. Questa è concepita per essere usata per mostrare i widget che sono in qualche modo trasversali a tutte le section, e che devono essere sempre in primo piano (per esempio widget codici, codici parlanti, stati vari, etc..). Quindi essa è sempre visibile a prescindere da quale section viene selezionata sotto.
-A destra della section di intestazione può opzionalmente essere presente un bottone **stampa report** pdf (il name della report è specificato nella tabella //gwm_ddoc_template//. Se omesso non viene visualizzato alcun bottone).
-MODELLO DATI
-{{:gwusermanual:interface:gw_digital_document_modello_dati.png?400|}}
-TABELLE IN DETTAGLIO\\
-//gwm_ddoc//:
-  * **gwid**: Integer, required, chiave primaria;
-  * **name**: String, required. Identificativo mnemonico per il DDOC (usato per la GUI nel gwAdmin);
-  * **label**: String, required. (usato per la GUI nel gwAdmin);
-  * **fk_class**: Integer, required. Chiave esterna con gwm_classes;
-  * **status_column**: String, optional. Nome della colonna della classe che verrà usata per recuperare lo stato del record corrente. Il valore dello stato verrà passato come parametro (//entityStatus//) nell’invocazione dei vari metodi groovy (vedi sotto). Se omesso, verrà passato null;
-  * **groovy**: String, optional. Nome del file groovy che ospiterà una class java, la quale dovrà od implementare i seguenti metodi dell'interfaccia //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigAbs// od estendere la class //com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigImpl// (che ne è l’implementazione di default):\\  <code java>public Boolean isVisible(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isEditable(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> <code java>public Boolean isDefaultSelected(String ddocName, String templateName, String sectionName, String entityId, String entityName, String entityStatus, String gwUser, String gwGroup, Map<String, Object> gwActiveScopesMap)</code> L'utente configuratore, di volta in volta, avrà a disposizione tutti i parametri in ingresso per decidere, ritornando //true// o //false//, se abilitare o negare lo specifico permesso. All'interno dei corpi dei metodi da implementare saranno disponibili anche tutti i servizi normalmente disponibili nei groovy di classe (accedibili con notazione 	//services.identificativo_servizio//). Se il groovy non venisse dichiarato verrà usata un'implementazione di default che abilità tutti i permessi. Da ricordare comunque che continuano ad operare sempre e comunque tutti i meccanismi di ACL, statica e dinamica, che sono propri del dettaglio di classe, e che verranno applicati a monte: solo in caso di esito positivo si procederà anche a valutare il responso della classe nel groovy. Inoltre, per evitare di riscrivere nel groovy controlli doppi, se per un dato set di input //isVisible()// dovesse ritornare false e, per gli stessi input //isEditable()// dovesse invece ritornare //true//, la sezione non verrebbe comunque visualizzata. Quindi va tenuto presente che il valore ritornato da //isEditable()// sarà valutato solo per le section per cui l’esito di //isVisible()// è stato positivo. Con //isDefaultSelected// si decide quale section il DDOC presenterà appena aperto. Anche //isDefaultSelected()// verrà valutato solo se //isVisible()// e //isEditable()// abbiano precedentemente ritornato esito positivo. Di default viene presentata la prima section editabile, o la prima in assoluto se sono tutte in sola visualizzazione.
-//gwm_ddoc_section//:
-  * **gwid**: Integer, required, chiave primaria;
-  * **name**: String, required. Identificativo mnemonico per la section (usato per la GUI nel gwAdmin);
-  * **label**: String, required. (usato per la GUI lato client, sarà l'intestazione della sezione di sinistra);
-  * **fk_ddoc**: Integer, required. Chiave esterna con //gwm_ddoc//.
-//gwm_ddoc_template//:
-  * **gwid**: Integer, required, chiave primaria;
-  * **name**: String, required. Identificativo mnemonico per il template (usato per la GUI nel gwAdmin) ;
-  * **fk_ddoc**: Integer, required. Chiave esterna con //gwm_ddoc//.
-//gwm_ddoc_r_template_section//:
-  * **gwid**: Integer, required, chiave primaria;
-  * **name**: String, required. Identificativo mnemonico per il template (usato per la GUI nel gwAdmin) ;
-  * **fk_template**: Integer, required. Chiave esterna con gwm_ddoc_template;
-  * **fk_section**: Integer, required. Chiave esterna con gwm_ddoc_section;
-  * **section_order**: Integer, required. Determinerà lato client l'ordine con le quale verranno presentate le sezioni;
-  * **detail_layout_name**: String, required. Determinerà quale detailLayout, fra quelli configurati per la classe, verrà usato per rappresentare la sezione nello specifico template;
-  * **is_header**: Integer, optional. Determina quale delle section all’interno del template sarà usato come intestazione del DDOC. Ce ne può essere solo uno per template.
-NOTE
-Per visualizzare il documento digitale si è preferito sviluppare un nuovo widget e non un nuovo tipo di scheda, per specifiche ragioni.
-Essendoci l'esigenza, dettata dalle nuove linee di sviluppo, di mostrare assieme al documento anche tutti le istanze di processi che sono in qualche modo collegate ad esso, il documento digitale è inglobato in un widget.
-Tale widget può quindi essere disposto con la massima flessibilità, facendo leva sul meccanismo di layout della classe di geoweb, accanto ad altri specifici widget che si occuperanno di mostrare e gestire i processi collegati al documento (oggetto di sviluppi paralleli).
-Questo nuovo widget ha sostanzialmente il solo parametro //template//.
-ALTRE CONSIDERAZIONI DI SVILUPPO
-Il solo parametro template è sufficiente in quanto il DDOC è recuperato in automatico facendo leva sul fatto che ne può esistere solo uno per classe. Dal DDOC è recuperato il file .groovy che codifica la configurazione del widget
-Come sviluppo futuro si potrebbero aggiungere i seguenti parametri:
-  * //ddoc_class_name//;
-  * //local_field//;
-  * //ddoc_field// con lo scopo di visualizzare dentro un dettaglio di classe il documento i cui dati sono però ospitati in un’altra classe. In particolare, una specifica fase di una scheda workflow di tipo procedure, potrebbe ospitare un widget gwDigitalDocument, che faccia riferimento a dati ospitati, come giusto, su un’apposita classe.
-ESEMPIO DI CONFIGURAZIONE XML WIDGET
-<code xml>
-<gwDigitalDocumentWidget>
-    …
-    <template></template>
-</gwDigitalDocumentWidget>
-</code>
-ESEMPIO DI CONFIGURAZIONE GROOVY
-<code java>
-public class TestGwDigitalDocumentConfigImpl extends com.geowebframework.transfer.objects.digitaldocument.GwDigitalDocumentConfigImpl {
-	public Boolean isVisible(
-		String ddocName,
-		String templateName,
-		String sectionName,
-		String entityId,
-		String entityName,
-		String entityStatus,
-		String gwUser,
-		String gwGroup,
-		Map<String, Object> gwActiveScopesMap
-	){
-		return sectionName!='test_section_5';
-	}
-	public Boolean isEditable(
-		String ddocName,
-		String templateName,
-		String sectionName,
-		String entityId,
-		String entityName,
-		String entityStatus,
-		String gwUser,
-		String gwGroup,
-		Map<String, Object> gwActiveScopesMap
-        ){
-		return sectionName!='test_section_2';
-	}
-        public Boolean isDefaultSelected(
-		String ddocName,
-		String templateName,
-		String sectionName,
-		String entityId,
-		String entityName,
-		String entityStatus,
-		String gwUser,
-		String gwGroup,
-		Map<String, Object> gwActiveScopesMap
-        ){
-		return sectionName=='test_section_4';
-	}
-}
-</code>
-===== Template =====
-Il template è la definizione della tipologia di rappresentazione delle informazioni del Documento Digitale.
-Nel Template sono definibili delle Sezioni che sono associate a specifici Detail Layout della classe che include il Document.
-Sono configurabili più template all'interno della stessa classe.
-{{:gwusermanual:interface:widget:ddoc-template.png|}}