Guida Completa al Campo HTML in Odoo

Introduzione

Quando si guarda a una descrizione del prodotto in un negozio e-commerce Odoo, il testo formattato con intestazioni in grassetto, punti elenco e immagini è alimentato da un unico tipo di campo: il campo Html. È uno dei campi più versatili nel modello di dati di Odoo e appare in più luoghi di quanto la maggior parte degli utenti realizzi.

A differenza di un campo di testo semplice che memorizza stringhe semplici, il campo Html memorizza contenuti ricchi con formattazione completa. Questo lo rende essenziale ovunque gli utenti debbano scrivere testo strutturato o stilizzato, che si tratti di una descrizione del prodotto, di un modello di email, di una nota interna o di una sezione del sito web.

Questa guida copre cos'è il campo Html, come funziona nell'ORM e nel database di Odoo, dove viene utilizzato nei flussi di lavoro aziendali reali e come crearlo o personalizzarlo utilizzando Odoo Studio o codice Python. Copriamo anche gli errori più comuni che le persone fanno quando lavorano con questo tipo di campo.

Cos'è il campo Html in Odoo

Nell'ORM di Odoo, il campo Html è progettato per memorizzare contenuti HTML formattati. Mappa a una colonna TEXT in PostgreSQL e il valore memorizzato è una stringa HTML. Odoo gestisce automaticamente il rendering e la sanitizzazione, quindi ciò che gli utenti vedono nell'interfaccia è un editor di testo ricco completamente formattato, non codice HTML grezzo.

Dal punto di vista dell'utente, un campo Html appare come un editor WYSIWYG (Ciò che Vedi È Ciò che Ottieni). Gli utenti possono applicare grassetto, corsivo, intestazioni, elenchi, collegamenti, tabelle e persino inserire immagini direttamente nel campo. Il risultato viene salvato come HTML strutturato dietro le quinte.

Ecco come appare il campo in una definizione di modello Python:

from odoo import fields, models

class ProductTemplate(models.Model):
    _inherit = 'product.template'

    x_technical_specs = fields.Html(
        string='Specifiche Tecniche',
        sanitize=True,
        sanitize_tags=True,
    )

Il parametro string imposta l'etichetta visibile. Il parametro sanitize controlla se Odoo rimuove HTML potenzialmente pericoloso prima di salvare il valore. Questo è importante per motivi di sicurezza ed è abilitato per impostazione predefinita.

In Odoo Studio, questo tipo di campo è chiamato Html o Rich Text. Quando creato tramite Studio, riceve un prefisso x_studio_. Quando definito in Python o tramite l'API XML-RPC, scegli tu stesso il nome tecnico.

Come funziona il campo

Quando definisci un campo Html in Odoo, il framework crea una colonna TEXT nel database PostgreSQL. Non ci sono vincoli di lunghezza a livello di database, il che lo rende adatto per contenuti di lunga durata. Il framework Odoo gestisce il livello di sanitizzazione prima che il valore venga scritto nel database.

Sanitizzazione e Sicurezza

Il comportamento più distintivo del campo Html rispetto ad altri tipi di campo è il suo livello di sanitizzazione. Per impostazione predefinita, Odoo rimuove eventuali tag o attributi HTML che potrebbero essere utilizzati per attacchi di cross-site scripting (XSS). Questo è controllato da un insieme di attributi del campo:

• sanitize: Quando True (il predefinito), Odoo applica l'intero processo di sanitizzazione prima di salvare il valore. Imposta su False solo quando sei certo che il contenuto provenga da una fonte fidata e deve preservare HTML grezzo.
• sanitize_tags: Quando True, Odoo rimuove eventuali tag HTML non presenti nell'elenco consentito. Disabilitare questo consente tag arbitrari ma dovrebbe essere fatto con cautela.
• sanitize_attributes: Controlla se anche gli attributi sui tag HTML vengono sanitizzati.
• sanitize_style: Controlla se gli attributi di stile inline vengono sanitizzati. Per impostazione predefinita, alcune proprietà CSS sono consentite mentre quelle potenzialmente pericolose vengono rimosse.
• strip_style: Quando True, rimuove completamente tutti gli attributi di stile inline.
• strip_classes: Quando True, rimuove tutti gli attributi di classe CSS dal contenuto memorizzato.

Questa sanificazione rende il campo Html sicuro da utilizzare per contenuti generati dagli utenti, motivo per cui appare nei moduli rivolti ai clienti e nei modelli di email in tutto Odoo.

Attributi Chiave del Campo

Oltre alla sanificazione, il campo Html condivide molti degli attributi standard dei campi Odoo:

• translate: Quando impostato su True, il contenuto del campo può essere tradotto per lingua. Odoo memorizza una versione separata dell'HTML per ogni lingua attiva nel database.
• required: Rende il campo obbligatorio. Si noti che un campo Html contenente solo spazi bianchi o tag vuoti apparirà comunque non vuoto all'interfaccia, quindi la validazione obbligatoria funziona meglio su valori veramente vuoti.
• default: Imposta un valore HTML predefinito per i nuovi record. Utile per precompilare modelli di email o descrizioni di prodotti con testo standard.
• compute: Collega un metodo Python che costruisce dinamicamente il contenuto HTML. Con store=True, il risultato viene persistito nel database.
• copy: Controlla se il contenuto HTML viene duplicato quando si copia un record. Di default è impostato su True.

Come Appare nelle Visualizzazioni

Nelle visualizzazioni dei moduli, un campo Html viene visualizzato come l'editor di testo ricco di Odoo. Gli utenti ottengono una barra degli strumenti con opzioni di formattazione e l'area di contenuto gestisce testo formattato, immagini e link. Nelle visualizzazioni elenco, Odoo di solito mostra un'anteprima di testo semplice con i tag HTML rimossi, per mantenere l'elenco leggibile.

L'attributo widget nelle viste XML consente di controllare il rendering. Il widget predefinito per i campi Html è l'editor di testo avanzato. Puoi anche rendere un campo Html come output HTML di sola lettura utilizzando il widget html, che è utile nelle viste di report o nelle pagine del portale dove desideri visualizzare contenuti formattati senza una barra degli strumenti modificabile.

Interazione con l'ORM di Odoo

Dal punto di vista dello sviluppo, la lettura di un campo Html restituisce una stringa contenente il markup HTML grezzo. La scrittura in esso si aspetta anch'essa una stringa HTML. La sanitizzazione avviene a livello di ORM prima che la scrittura raggiunga il database, quindi anche i valori scritti tramite l'API XML-RPC passano attraverso lo stesso processo di pulizia quando sanitize=True.

Una implicazione pratica: se hai bisogno di memorizzare e recuperare contenuti che includono tag o attributi HTML personalizzati non presenti nell'elenco consentito di Odoo, dovrai impostare sanitize=False o regolare i flag di sanitizzazione nella definizione del campo. Questo è un caso d'uso avanzato che richiede una attenta considerazione delle implicazioni di sicurezza nella tua implementazione.

Casi d'uso aziendali

Il campo Html appare in molte aree di un'implementazione Odoo. Ecco cinque esempi del mondo reale da flussi di lavoro aziendali comuni.

Inventario e E-commerce: Descrizioni dei Prodotti

Il campo Html più utilizzato in Odoo è il campo description_sale su product.template. Questa è la descrizione del prodotto che i clienti vedono nel negozio online e nelle righe degli ordini di vendita. Utilizzare un campo Html qui consente ai team di merchandising di scrivere contenuti di prodotto strutturati con punti elenco, intestazioni e immagini incorporate, tutto ciò si traduce direttamente in migliori conversioni e-commerce. Lo stesso record di prodotto alimenta sia il back-office che il punto vendita, quindi non c'è duplicazione di contenuti tra i sistemi.

Email Marketing: Corpi dei Modelli

I modelli di email di Odoo si basano fortemente sui campi Html. Il campo body_html su mail.template memorizza l'intero corpo dell'email come HTML, inclusi layout, immagini e segnaposto dinamici che vengono sostituiti con valori reali al momento dell'invio. I team di marketing possono progettare contenuti email ricchi direttamente in Odoo senza bisogno di uno strumento di design email esterno. Il contenuto è versionato e riutilizzabile in campagne, preventivi e flussi di lavoro automatizzati.

CRM: Note e Descrizioni delle Opportunità

I team di vendita spesso hanno bisogno di catturare contesti dettagliati su un potenziale cliente o affare. I campi Html sui lead e le opportunità CRM consentono ai rappresentanti di scrivere note strutturate con formattazione, elenchi e link incorporati a documenti esterni o proposte. Questo è più utile rispetto ai campi di testo semplice quando le note devono essere condivise tra un team o incluse in report stampati, poiché la formattazione sopravvive in tutti questi contesti.

Contabilità: Termini e Condizioni della Fattura

Molte aziende includono termini di pagamento, clausole legali o informazioni sulla garanzia in fondo alle fatture e agli ordini di vendita. Il campo note negli ordini di vendita e nelle fatture è un campo Html, che consente ai team finanziari e operativi di formattare questi termini con una struttura adeguata. Il contenuto appare in modo chiaro sui documenti PDF stampati, con interruzioni di riga e enfasi preservate esattamente come inserite.

HR: Descrizioni delle Posizioni Lavorative

Quando i team HR pubblicano offerte di lavoro tramite Odoo Recruitment, la descrizione del lavoro è memorizzata in un campo Html nei modelli hr.job e hr.applicant. Questo consente di avere annunci di lavoro strutturati con sezioni chiare per responsabilità, requisiti e benefici, esattamente il tipo di contenuto formattato che appare professionale su una pagina delle carriere e aiuta ad attrarre i candidati giusti.

Creazione o personalizzazione del campo Html

Ci sono tre modi principali per aggiungere un campo Html a un modello Odoo, a seconda della tua configurazione tecnica e dell'approccio di distribuzione.

Utilizzando Odoo Studio (Nessun Codice)

Odoo Studio rende semplice aggiungere un campo Html a qualsiasi modulo esistente senza scrivere codice:

1. Apri Odoo Studio dal menu principale.
2. Naviga al modulo in cui desideri il campo.
3. Dalla barra laterale, trascina un campo Html o Rich Text nel modulo.
4. Imposta l'etichetta e qualsiasi altra opzione nel pannello delle proprietà del campo.
5. Salva e chiudi Studio.

Studio crea automaticamente il campo con un prefisso x_studio_, lo aggiunge alla vista e gestisce la colonna del database. Non è necessario alcun passaggio di migrazione o distribuzione da parte tua. Il campo è immediatamente disponibile per l'inserimento dei dati in tutta l'istanza.

Utilizzare Python in un Modulo Personalizzato

Per gli sviluppatori che costruiscono moduli Odoo, i campi Html sono definiti nei file modello Python. Questo approccio è raccomandato per qualsiasi personalizzazione che deve essere controllata in versione e distribuita tra ambienti di staging e produzione:

from odoo import fields, models

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    x_delivery_instructions = fields.Html(
        string='Istruzioni di Consegna',
        sanitize=True,
        translate=True,
    )

Dopo aver definito il campo nel modello, aggiungilo al file XML della vista pertinente affinché appaia nell'interfaccia. Odoo gestisce automaticamente la creazione della colonna TEXT nel database quando installi o aggiorni il modulo. Il campo verrà visualizzato come un editor di testo ricco nella vista del modulo senza alcuna configurazione aggiuntiva del widget.

Utilizzare l'API XML-RPC

Se gestisci le personalizzazioni di Odoo in modo programmatico come parte di una pipeline di distribuzione o di uno script di configurazione remota, puoi creare campi Html tramite l'API XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_custom_notes',
        'field_description': 'Note Personalizzate',
        'model_id': model_id,
        'ttype': 'html',
        'state': 'manual',
    }]
)

Il valore ttype: html indica a Odoo di creare un campo Html. L'impostazione state: manual lo contrassegna come un campo creato dall'utente piuttosto che da un modulo. Questo è lo stesso approccio utilizzato da Dasolo per la creazione di campi remoti negli ambienti client, come parte di quaderni di configurazione automatizzati che possono essere eseguiti e tracciati senza accesso diretto al server.

Nota che le opzioni di sanitizzazione (sanitize, sanitize_tags, ecc.) non possono essere impostate tramite l'API su ir.model.fields nello stesso modo in cui lo sono in Python. Il comportamento di sanitizzazione predefinito si applica quando si creano campi tramite l'API.

Migliori pratiche

1. Mantieni la sanitizzazione abilitata a meno che tu non abbia un motivo valido per non farlo

Il comportamento di sanitizzazione predefinito esiste per proteggere la tua istanza Odoo da vulnerabilità di cross-site scripting. La maggior parte dei casi d'uso funziona perfettamente con la sanitizzazione attivata. Disabilitala solo quando stai memorizzando contenuti generati da un processo interno completamente fidato, come una pipeline di rendering lato server, e mai quando il contenuto proviene da input utente o fonti esterne.

2. Usa translate=True per contenuti di prodotto multilingue

Se la tua istanza Odoo supporta più lingue, i campi Html visualizzati sul sito web o nei documenti rivolti ai clienti dovrebbero avere translate=True. Questo consente al tuo team di mantenere contenuti HTML separati per ogni lingua, garantendo che i clienti vedano sempre descrizioni e termini nella propria lingua piuttosto che un fallback.

3. Evita di memorizzare contenuti dei campi Html che dipendono da risorse esterne

Incorporare immagini o script esterni all'interno di un campo Html crea dipendenze che possono rompersi silenziosamente quando quegli URL esterni cambiano o vanno offline. Utilizza il sistema di allegati di Odoo per ospitare immagini internamente e fai riferimento a esse con URL relativi. Questo mantiene il tuo contenuto portatile e resiliente durante le migrazioni del database e i cambiamenti del server.

4. Usa campi Html calcolati per contenuti dinamici dei documenti

Per contenuti che devono essere costruiti programmaticamente, come un riepilogo formattato delle righe d'ordine o una clausola di garanzia dinamica, un campo Html calcolato con store=True è una soluzione pulita. La logica di calcolo vive in un unico posto, l'output è memorizzato nel database per un accesso rapido e il campo si rende correttamente sia nell'interfaccia che nei report PDF.

5. Considera il contesto di rendering quando scegli Html vs Testo

Se il contenuto apparirà solo nel backend di Odoo in un contesto in cui gli utenti lo leggono come testo semplice, un campo Testo potrebbe essere sufficiente. Usa Html quando la formattazione è realmente importante per il lettore, come su una pagina web, un documento stampato o un'email. Aggiungere un campo Html dove un campo Testo sarebbe sufficiente introduce complessità non necessaria per gli utenti che devono interagire con un editor di testo ricco per semplici appunti.

Errori comuni

Disabilitare la sanitizzazione e dimenticarsene

Impostare sanitize=False su un campo che gli utenti possono modificare direttamente è un rischio per la sicurezza. È facile farlo durante lo sviluppo per sbloccare un requisito di formattazione e poi dimenticarsene prima di andare in produzione. Documenta sempre il motivo per cui la sanitizzazione è disabilitata e pianifica una revisione prima del deployment.

Incollare contenuti da fonti esterne con HTML rotto

Quando gli utenti incollano contenuti da documenti Word, Google Docs o siti web in un campo Html, il risultato spesso contiene HTML disordinato o non standard. Questo può portare a rendering incoerenti, caratteri invisibili che rompono le ricerche o valori di campo gonfiati che rallentano i caricamenti delle pagine. Incoraggia gli utenti a utilizzare prima l'opzione "Incolla come testo semplice" e poi riapplicare la formattazione all'interno dell'editor Odoo.

Confondere il campo Html con il contenuto del costruttore di siti web

Il costruttore di siti web di Odoo utilizza blocchi di costruzione e componenti Owl per costruire il contenuto delle pagine. L'HTML memorizzato dal costruttore di siti web nelle viste delle pagine non è lo stesso di quello che inseriresti in un campo Html standard. Cercare di copiare HTML complesso del costruttore di siti web in un campo Html su un modello di solito non verrà visualizzato correttamente e potrebbe essere rimosso dal sanitizzatore.

Dimenticare di tradurre nelle implementazioni multilingue

In un'istanza Odoo multilingue, un campo Html senza translate=True mostra lo stesso contenuto agli utenti di tutte le lingue. Questo va bene per i campi interni, ma diventa un problema per le descrizioni dei prodotti, i modelli di email e qualsiasi contenuto che raggiunge contatti esterni. Mancare questa impostazione è facile da trascurare durante la configurazione iniziale e difficile da correggere retroattivamente una volta che il contenuto è stato inserito in una sola lingua.

Utilizzare campi Html in luoghi in cui ci si aspetta testo semplice

Alcune parti di Odoo, come gli oggetti delle email, i titoli dei report o le risposte delle API esterne, si aspettano stringhe di testo semplice. Se memorizzi un valore di campo Html in un contesto in cui i tag HTML non vengono rimossi, i tuoi utenti vedranno markup grezzo come <p>Ciao</p> invece di testo pulito. Controlla sempre come e dove il valore del campo sarà consumato prima di scegliere Html rispetto a Char o Text.

Conclusione

Il campo Html è uno dei tipi di campo più potenti nel modello di dati di Odoo. Si trova silenziosamente dietro le descrizioni dei prodotti, i modelli di email, le offerte di lavoro e le note delle fatture, rendendo possibile contenuti formattati in tutto il sistema senza alcun strumento aggiuntivo.

Comprendere come funziona, in particolare il livello di sanitizzazione, il supporto alla traduzione e come si comporta nei diversi contesti di rendering, ti aiuta a prendere decisioni migliori quando progetti o personalizzi un'istanza Odoo. Che tu stia utilizzando Odoo Studio per aggiungere un campo di testo ricco a un modulo, definendolo in Python come parte di un modulo personalizzato, o creandolo da remoto tramite l'API, i principi trattati in questa guida si applicano a tutti e tre gli approcci.

Come la maggior parte delle cose in Odoo, il campo stesso è semplice una volta che sai cosa sta facendo sotto il cofano. Il valore deriva dall'utilizzarlo nei posti giusti, con le impostazioni giuste, per il tipo di contenuto giusto.

Da Dasolo, aiutiamo le aziende a implementare, personalizzare e ottimizzare Odoo in tutti i dipartimenti. Che tu abbia bisogno di aiuto per progettare un modello di dati pulito, aggiungere campi personalizzati ai tuoi flussi di lavoro o costruire moduli Odoo completi su misura per la tua azienda, il nostro team è qui. Contattaci e parliamo del tuo progetto Odoo.