Introduzione
Il campo Char è uno degli elementi più diffusi nel modello dati di Odoo. Ogni volta che vedi un nome cliente, un codice prodotto o una nota breve su un ordine, molto probabilmente stai visualizzando un campo Char, anche se non lo riconosci subito.
Sapere come usare correttamente questo tipo di campo è utile sia che tu sia un amministratore che personalizza moduli con Odoo Studio, uno sviluppatore che scrive moduli, o un consulente che progetta l’architettura dati per un cliente.
Apparentemente semplice, il campo Char nasconde alcune proprietà e comportamenti che vale la pena conoscere per evitare problemi pratici. Questa guida spiega cosa memorizza il campo, come si comporta nell’interfaccia, come crearlo e personalizzarlo e quando preferirlo ad altri tipi di campo.
Cos’è il campo Char in Odoo
Nel motore ORM di Odoo, il campo Char è pensato per conservare brevi stringhe di testo. A livello database si traduce in colonne di tipo VARCHAR o TEXT su PostgreSQL, a seconda se viene imposto un limite di lunghezza.
Per l’utente finale, il Char si presenta come un singolo campo di testo nelle form e come una colonna testuale nelle liste. È la scelta standard per nomi, codici, riferimenti, identificativi e qualsiasi breve valore monoriga.
Esempio di come si dichiara in un file Python del modello:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
customer_po_reference = fields.Char(
string='Customer PO Reference',
size=64,
index=True,
)Nel frammento, il parametro string definisce l’etichetta visualizzata; size impone un limite di caratteri (opzionale); index crea un indice nel database per rendere le ricerche più veloci.
Se aggiungi il campo tramite Odoo Studio lo troverai sotto il nome generico “Text (single line)” e il sistema genera automaticamente un prefisso x_studio_ per il nome tecnico. Se lo definisci in codice o via API, sei tu a scegliere il nome tecnico.
Come funziona il campo
Quando dichiari un campo Char, Odoo si occupa di creare la colonna corrispondente nel database al momento dell’installazione o dell’aggiornamento del modulo: non servono migrazioni SQL manuali nella maggior parte dei casi.
In PostgreSQL, un Char senza limite viene salvato come TEXT, mentre con size diventa VARCHAR(n). Dal punto di vista delle prestazioni la differenza è minima: la scelta serve soprattutto a imporre un vincolo di lunghezza quando necessario.
Attributi principali del campo
Di seguito le proprietà più rilevanti di un campo Char in Odoo:
- size: numero massimo di caratteri; se omesso non c’è un limite applicato dal database.
- translate: abilita la traduzione del valore per lingua, utile in contesti multilingua.
- required: rende il campo obbligatorio nell’interfaccia e a livello di modello.
- default: valore predefinito assegnato alla creazione del record.
- index: crea un indice database per velocizzare filtri e ricerche sul campo.
- compute: collega il campo a un metodo Python che ne calcola dinamicamente il valore, utile per valori derivati o concatenati.
- store: usato insieme a
compute, determina se il valore calcolato viene memorizzato nel database. - copy: stabilisce se il valore viene duplicato quando si copia un record; il valore predefinito è
True.
Come viene mostrato nelle viste
Nelle form un Char viene renderizzato come un elemento <input type="text">; nelle list view appare come testo semplice. Nei filtri di ricerca supporta operatori come contiene, uguale e inizia con.
Puoi applicare widget per cambiare il rendering: ad esempio il widget email trasforma il Char in un link cliccabile, mentre il widget url apre il collegamento in una nuova scheda del browser.
Interazione con l’ORM di Odoo
Dal punto di vista dello sviluppatore leggere o scrivere un campo Char è diretto: si accede al valore sull’oggetto record e l’ORM gestisce la validazione e la sanitizzazione secondo la definizione del campo. Non ci sono trasformazioni complesse, il che rende questo tipo di campo molto pratico per gli sviluppi quotidiani.
Esempi pratici per l’azienda
Dove il Char viene usato in azienda
CRM: codici cliente e riferimenti interni
Molte aziende assegnano codici interni ai clienti. Un campo Char su res.partner può contenere questo identificativo, rendendolo facilmente ricercabile e visibile su ordini e fatture: utile quando più clienti hanno nomi simili.
Vendite: riferimenti agli ordini del cliente
Quando il cliente inserisce un numero di ordine d’acquisto, quel riferimento deve comparire su fatture e documenti di trasporto. In Odoo il campo client_order_ref su sale.order è un Char che viene riportato automaticamente sulla fattura, evitando resi e richieste di chiarimento.
Magazzino: codici prodotto interni
Il campo default_code su product.template è un Char che contiene il codice interno usato in magazzino, nei lettori barcode e negli ordini di acquisto. Mantenere questo campo coerente è una priorità di qualità dati nelle implementazioni logistiche.
Contabilità: numeri fiscali e partita IVA
Partita IVA, codici fiscali e numeri di registrazione aziendale vengono memorizzati come Char sui partner e poi riprodotti automaticamente su fatture e ricevute se la configurazione è corretta. Per chi opera in diversi paesi avere questi valori ben organizzati evita correzioni manuali.
HR: identificativi dipendenti e badge
Nei reparti HR si salvano spesso numeri badge, ID dipendente o codici esterni usati dai sistemi paghe o controllo accessi. Un campo Char sul modello dipendente permette di collegare Odoo ad altri strumenti senza dover partire subito con integrazioni complesse.
Come creare o personalizzare un campo Char
Modi per aggiungere un campo Char
Ci sono tre approcci principali per aggiungere un Char a un modello Odoo, scelti in base alle competenze e alla strategia di deployment.
Con Odoo Studio (senza codice)
- Odoo Studio è lo strumento low-code integrato. Per aggiungere un Char senza codice:
- Apri Odoo Studio dal menù principale.
- Vai alla form dove vuoi inserire il campo.
- Trascina il campo “Text (single line)” dalla barra laterale nella form.
- Imposta etichetta, stato obbligatorio e, se serve, un limite di lunghezza nelle proprietà del campo.
Salva e chiudi Studio.
Studio crea automaticamente il campo con prefisso x_studio_ e lo aggiunge alla vista; non è richiesta nessuna migrazione manuale del database.
Con Python in un modulo custom
Per chi sviluppa moduli, si definisce il campo in Python nel modello:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_erp_customer_id = fields.Char(
string='ERP Customer ID',
size=32,
index=True,
copy=False,
)
Dopo aver aggiunto il campo al modello, è necessario inserirlo anche nella vista XML corrispondente in modo che sia visibile. Odoo crea la colonna database all’installazione o aggiornamento del modulo.
Via API XML-RPC
Per chi gestisce configurazioni in modo programmatico (deployment automatizzati o script remoti), i campi Char possono essere creati anche tramite l’API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_reference',
'field_description': 'Custom Reference',
'model_id': model_id,
'ttype': 'char',
'size': 64,
'state': 'manual',
}]
)
Buone pratiche
L’opzione state: manual segnala a Odoo che il campo è stato creato manualmente (non da un modulo), ed è la scelta corretta per campi generati con Studio o via API.
Consiglio 1: usa size quando sai la lunghezza massima
Se il campo conterrà codici a lunghezza fissa — come codici paese ISO, numeri identificativi o formati standardizzati — definisci un size. Questo comunica chiaramente lo scopo del campo e previene inserimenti errati o eccessivamente lunghi.
Consiglio 2: aggiungi un indice per campi ricercati frequentemente
Se gli utenti filtrano spesso per quel campo (codici cliente, riferimenti ordine), abilita index=True. Su tabelle con decine di migliaia di record un indice può ridurre i tempi di ricerca in modo significativo.
Consiglio 3: abilita translate=True per contenuti multilingua
Se l’istanza supporta più lingue e il campo contiene testo che deve cambiare per lingua (nomi di prodotti, titoli di posizione, ecc.), abilita translate=True in modo che ogni utente veda il valore nella propria lingua.
Consiglio 4: nomi tecnici chiari e consistenti
Nei moduli custom scegli nomi tecnici descrittivi (per esempio x_customer_erp_id invece di x_field1). Se usi Studio rinomina il campo prima del deploy: una volta popolato di dati cambiare il nome tecnico è complesso.
Consiglio 5: usa compute per riferimenti derivati
Errori comuni da evitare
Un Char può essere calcolato dinamicamente (per esempio concatenando anno e numero di sequenza). Con store=True il valore viene salvato nel database, rendendolo utilizzabile in ricerche e report senza ricalcolo continuo.
Rischio: niente limite permette dati incoerenti
Senza un limite di lunghezza gli utenti possono incollare paragrafi interi in un campo pensato per un codice: problema reale quando quei valori vengono stampati su documenti o inviati a sistemi esterni con limiti di caratteri. Imposta sempre un limite ragionevole quando la lunghezza conta.
Rischio: mancanza di indice su campi cercati
Filtrare su un campo Char senza indice su tabelle grandi comporta scansioni complete: le performance degradano con la crescita dei dati. Aggiungi l’indice fin dall’inizio se il campo verrà usato per filtri o ricerche frequenti.
Rischio: confondere Char con Text
Il Char è per testo breve su una singola riga; il campo Text è per contenuti lunghi e multilinea. Usare Char per indirizzi, note o descrizioni porta a una scarsa esperienza utente perché non sono possibili ritorni a capo. Quando il testo può essere più lungo di una frase, scegli Text.
Rischio: dimenticare translate sui campi multilingua
In ambienti internazionali dimenticare translate=True significa che tutti gli utenti vedranno lo stesso valore, creando incoerenze nei documenti rivolti a clienti in lingue diverse. Abilita la traduzione dove serve.
Rischio: usare Char per valori che dovrebbero essere Selection o relazione
Domande frequenti
Se un campo può assumere solo un set limitato di valori (stati, categorie, paesi), meglio usare Selection o una relazione Many2one. Il Char libero facilita errori di battitura e varianti che complicano raggruppamenti, filtri e reportistica.
Qual è la differenza tra Char e Text in Odoo?
Il Char contiene testo breve su una riga e appare come campo di input; Text è per contenuti lunghi su più righe e appare come textarea. Usa Char per nomi, codici e riferimenti; Text per descrizioni e note estese.
Posso limitare i caratteri in un campo Char?
Sì: in Python usa il parametro size (es. fields.Char(size=64)). In Studio puoi impostare il limite nelle proprietà del campo. Se non imposti size, non c’è un vincolo di lunghezza applicato dal database.
Come faccio a far comparire un Char nella barra di ricerca?
Devi aggiungerlo alla view di ricerca del modello. In Studio abilita l’opzione di ricerca nelle proprietà del campo. In codice inserisci <field name="your_char_field"/> dentro la view <search> in XML: così gli utenti potranno filtrare direttamente da quella barra.
Posso memorizzare numeri in un Char?
Tecnicamente sì, ma non è consigliato per valori che devono essere calcolati. Per quantità e importi usa Integer o Float. Il Char va bene per identificativi numerici trattati come stringhe (CAP, numeri di telefono, IBAN, seriali).
Come creare un Char calcolato e salvato in database?
Conclusione
Definisci il campo con compute='_compute_my_field' e store=True, poi implementa il metodo di calcolo usando @api.depends() per indicare i trigger. Con store=True il valore sarà memorizzato e disponibile per ricerche ed esportazioni senza ricalcolo ad ogni lettura.
Il campo Char è semplice ma centrale. Molti utenti interagiscono quotidianamente con decine di Char senza pensarci, ma scegliere il tipo giusto e configurarlo correttamente influisce direttamente sulla qualità del modello dati e sull’usabilità del sistema.
Che tu stia aggiungendo un riferimento cliente via Studio, definendo un campo in un modulo Python o creando campi via API, le linee guida di questa guida ti aiutano a fare le scelte giuste sin dall’inizio.
Un modello dati ben progettato, con tipi di campo appropriati, è una delle basi più importanti per un’implementazione Odoo di successo. Il campo Char è un elemento piccolo ma significativo di questo quadro: vale la pena conoscerlo a fondo. Da parte nostra, in Dasolo supportiamo le aziende nell’implementazione, personalizzazione e ottimizzazione di Odoo in tutti i reparti. Se hai bisogno di aiuto per progettare un modello dati coerente, aggiungere campi personalizzati o sviluppare un modulo completo, possiamo affiancarti. Contattaci e parliamo del tuo progetto Odoo.