.. _widgetpedia/genro/components/linkerbox_bts: 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: .. image:: /_static/images/components/stolen_linkerbox_ricerca.png :width: 200px :align: center 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: .. image:: /_static/images/components/stolen_linkerbox_biglietto.png :width: 200px :align: center 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 `_ .. hint:: 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ì: .. image:: /_static/images/components/photo_2020-01-28_10-04-57.jpg :width: 640px :align: center 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. .. note :: 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') .. note :: 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. .. raw:: html
**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. | +------------------------+------+--------------------------------------------------+ .. sectionauthor:: Danilo Magro