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:

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:

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

Suggerimento

Si noti che il linkerBox è utilizzabile esclusivamente all’interno di una Form di un TableHandler, e dovrà essere collocato all’interno del datapath .record, questo al fine di «ricevere» correttamente i dati del record da visualizzare.

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\th.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ì:

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.

---

Parametri:

Nome parametro	Tipo	Descrizione
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
LinkerBox Parametri
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 Parametri
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.
framePane Parametri
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.
Template Parametri
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.
Internal use Parametri
center_class	T	center_class=None Uso interno. Classe CSS del contentPane, al quale viene inoltrata.

Autore della sezione: Danilo Magro