linkerBox

Il linkerBox nel suo habitat

Il linkerBox è un component versatile e potente che consente di digitare caratteri all’interno di un semplice campo testo, fare una ricerca su una tabella in relazione, visualizzare i record risultanti e, a differenza di semplici widget come dbSelect, modificare e aggiungere record nella tabella collegata:

../_images/stolen_linkerbox_ricerca.png

Tutto questo è possibile perché è composto da elementi distinti che interagiscono tra di loro (un component, appunto) e che, nell’insieme, permettono sia la ricerca e la selezione dei record sia la visualizzazione del form della tabella collegata, fornendo anche comoda possibilità di scegliere (attraverso un template editor molto comune in Genropy) cosa mostrare a video:

../_images/stolen_linkerbox_biglietto.png

Se volete vedere all’opera un linkerBox potete seguire questi link per raggiungere le pagine dove ne viene mostrato l’utilizzo all’interno del Tutorial Fatturazione:

Tutorial fatturazione - Lezione 7: miglioramenti fattura

o la pagina del Manuale Utente che mostra, anche attraverso chiare immagini, l’effetto visivo e pratico che si ottiene sfruttando questo component:

Manuale utente Genropy - Campi in relazione in un form

Dietro le quinte

Pur essendo un component, il linkerBox incorpora concetti e comportamenti tipici dei tableHandler, dei quali è quindi parente stretto, e per questo motivo è definito nel modulo th.py e si trova in genropy\resources\common\th\ty.py

Se volete approfondire la conoscenza della sua struttura e di come è stato creato, potete aprire il file nel vostro editor preferito e cercare:

def th_linkerBox

Vedrete che un linkerBox è fatto così:

../_images/photo_2020-01-28_10-04-57.jpg

Un linkerBox è fondamentalmente un framePane che contiene nella parte top una linkerBar (che a sua volta è semplicemente una slotBar con dentro un linker - dbSelect con pulsante +- e un titolo customizzato) e nella parte center ha un templateChunk che si occupa di visualizzare i dati scelti attraverso il template editor. Infine, se l’editing è attivato e possibile, viene aggiunta in modo dinamico nella parte bottom un’altra slotBar per contenere il pulsante di Edit.

Nota

Il linkerBox è per sua natura un «framePane» e in quanto tale va posizionato e deve avere come padre un elemento adatto a contenerlo, come ad esempio un contentPane, mentre non avrebbe senso metterlo come elemento all’interno di un formBuilder. Come promemoria mettiamo qui il link alla pagina dove parliamo degli elementi di Layout e delle loro caratteristiche: Widgetpedia - Elementi di Layout

Per comodità e riferimento veloce riportiamo comunque qui la sua signature, cioè la sua definizione con elenco dei parametri principali e relativi valori di default, e spieghiamo velocemente il significato dei parametri più comunemente usati.

def th_linkerBox(self, pane, field=None, template='default', frameCode=None, formResource=None,
                  formUrl=None, newRecordOnly=None, openIfEmpty=None,
                  _class='pbl_roundedGroup', label=None, template_kwargs=None,
                  margin=None, editEnabled=True, addEnabled=True,
                  clientTemplate=False, center_class=None, **kwargs)

A titolo di esempio, ecco come è stato usato nella fattura del Tutorial Fatturazione: vedrete i parametri tipici di una chiamata a linkerBox.

bc.contentPane(region='center').linkerBox('cliente_id', margin='2px', openIfEmpty=True,
                                             validate_notnull=True,
                                             columns='$ragione_sociale,$provincia,@cliente_tipo_codice.descrizione',
                                             auxColumns='@comune_id.denominazione,$provincia',
                                             newRecordOnly=True, formResource='Form',
                                             dialog_height='500px', dialog_width='800px')

Nota

Alcuni parametri presenti nel codice non sono espressamente documentati in questa pagina; ad esempio columns e auxColumns, che sono parametri ricevuti dalla linkerBox ma inoltrati direttamente alla dbSelect; stesso discorso per dialog_height e dialog_width che vengono estratti e passati al formHandler di edit del record per dare le dimensioni al dialog. Per avere più informazioni su questi parametri, quindi, potete fare riferimento alla documentazioni dei singoli widget.

Parameters:

Parameter name Type Description
field T field=None È il nome del campo, così come definito nel model, che ha la relazione con la tabella sulla quale vogliamo effettuare la ricerca. Nel nostro caso, il campo cliente_id è in relazione con la colonna cliente.id e la ricerca verrà quindi fatta sulla tabella cliente
framePane Parameters
margin T margin=None Con margin è possibile specificare un margine interno per il template di visualizzazione.
_class T _class='pbl_roundedGroup' Uso interno. Classe CSS del framePane, al quale viene inoltrata.
frameCode T frameCode=None Permette di specificare un nome «custom» per il framePane da creare. Di norma non viene passato perché viene assegnato automaticamente basandosi sul field ma diventa utile in presenza di due linkerBox diversi su uno stesso campo (cliente_id nell’esempio specifico), e in questo caso usare il frameCode ci permette di far riferimento ai due pane distinti con nomi diversi.
Internal use Parameters
center_class T center_class=None Uso interno. Classe CSS del contentPane, al quale viene inoltrata.
LinkerBox Parameters
openIfEmpty B openIfEmpty=None Serve a rendere visibile il campo di input della dbSelect se il valore è vuoto. Tipicamente si usa se nel record primario il campo è obbligatorio.
addEnabled B addEnabled=True Se True indica che è possibile aggiungere record nella tabella collegata attraverso l’apposito pulsantino. Si tratta dell’icona + presente nell’angolo in alto a destra del component.
editEnabled B editEnabled=True A True indica che il pulsantino di edit dei dati è visibile e attivo. Si tratta dell’icona della matita presente nella parte inferiore dell’area del component.
newRecordOnly B newRecordOnly=None Se impostato a True il campo di ricerca del linkerBox è visibile soltanto in fase di creazione nuovo record. Nell’esempio fornito, il Cliente può essere cercato e selezionato soltanto se siamo in presenza di una nuova fattura.
label T label=None Permette di specificare una label di intestazione per il component, se diversa dal nome della tabella.
Edit / Insert Parameters
formResource T formResource=None Indica quale form usare, nella tabella collegata, per l’input e la modifica dei dati. Se non indicato, usa il default Form. La sua presenza è condizione necessaria affinché editEnabled e addEnabled funzionino.
formUrl T formUrl=None Parametro usato molto raramente, in alternativa a formResource serve per indicare una formResource che non è definita nel file di risorsa di default chiamato con il nome della tabella, ma in un’altra pagina. In questo caso nel parametro si indica l’url del file della pagina.
Template Parameters
template_kwargs T template_kwargs=None ? Non usato direttamente. È un dizionario di parametri nominati che viene popolato dal decoratore @extract_kwargs(template=True) e che contiene, di tutti i parametri ricevuti, quelli identificati dal prefisso template_. Viene inoltrato direttamente al template editor.
clientTemplate B clientTemplate=False Parametro legacy mantenuto per retrocompatibilità. Indica se la sostituzione dei dati nel template deve essere fatta lato Client (True) o lato Server (False). La modalità moderna e ormai usata quasi esclusivamente è quella lato Server, che non soffre dei limiti della versione Client (che ha «a disposizione» soltanto i valori delle colonne reali e non quelle alias e formula).
template T template='default' Con questo parametro è possibile indicare il nome del file XML che contiene il template, creato e modificato con il template editor.

Autore della sezione: Danilo Magro