Campo HTML no Odoo: Guia Completo

Introdução

Quando você olha para uma descrição de produto em uma loja de e-commerce Odoo, o texto formatado com títulos em negrito, listas com marcadores e imagens é alimentado por um único tipo de campo: o campo Html. É um dos campos mais versáteis no modelo de dados do Odoo e aparece em mais lugares do que a maioria dos usuários percebe.

Diferente de um campo de texto simples que armazena strings simples, o campo Html armazena conteúdo rico com formatação completa. Isso o torna essencial em qualquer lugar onde os usuários precisem escrever texto estruturado ou estilizado, seja uma descrição de produto, um modelo de e-mail, uma nota interna ou uma seção de website.

Este guia cobre o que é o campo Html, como ele funciona no ORM e banco de dados do Odoo, onde é utilizado em fluxos de trabalho empresariais reais e como criá-lo ou personalizá-lo usando o Odoo Studio ou código Python. Também abordamos os erros mais comuns que as pessoas cometem ao trabalhar com este tipo de campo.

O que é o campo Html no Odoo

No ORM do Odoo, o campo Html é projetado para armazenar conteúdo HTML formatado. Ele mapeia para uma coluna TEXT no PostgreSQL, e o valor armazenado é uma string HTML. O Odoo lida com a renderização e sanitização automaticamente, então o que os usuários veem na interface é um editor de texto rico totalmente formatado, não código HTML bruto.

Do ponto de vista do utilizador, um campo Html aparece como um editor WYSIWYG (O Que Você Vê É O Que Você Obtém). Os utilizadores podem aplicar negrito, itálico, cabeçalhos, listas, links, tabelas e até inserir imagens diretamente no campo. O resultado é guardado como HTML estruturado nos bastidores.

Aqui está como o campo aparece numa definição de modelo Python:

from odoo import fields, models

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

    x_technical_specs = fields.Html(
        string='Especificações Técnicas',
        sanitize=True,
        sanitize_tags=True,
    )

O parâmetro string define o rótulo visível. O parâmetro sanitize controla se o Odoo remove HTML potencialmente perigoso antes de guardar o valor. Isso é importante por razões de segurança e está ativado por padrão.

No Odoo Studio, este tipo de campo é chamado de Html ou Texto Rico. Quando criado através do Studio, recebe um prefixo x_studio_. Quando definido em Python ou através da API XML-RPC, você escolhe o nome técnico você mesmo.

Como o campo funciona

Quando você define um campo Html no Odoo, o framework cria uma coluna TEXT na base de dados PostgreSQL. Não há restrição de comprimento a nível de base de dados, o que o torna adequado para conteúdo longo. O framework Odoo gerencia a camada de sanitização antes que o valor seja escrito na base de dados.

Sanitização e Segurança

O comportamento mais distintivo do campo Html em comparação com outros tipos de campo é a sua camada de sanitização. Por padrão, o Odoo remove quaisquer tags ou atributos HTML que possam ser usados para ataques de cross-site scripting (XSS). Isso é controlado por um conjunto de atributos de campo:

• sanitize: Quando True (o padrão), o Odoo aplica o processo completo de sanitização antes de guardar o valor. Defina como False apenas quando tiver certeza de que o conteúdo vem de uma fonte confiável e deve preservar HTML bruto.
• sanitize_tags: Quando True, o Odoo remove quaisquer tags HTML que não estão na lista permitida. Desativar isso permite tags arbitrárias, mas deve ser feito com cautela.
• sanitize_attributes: Controla se os atributos nas tags HTML também são sanitizados.
• sanitize_style: Controla se os atributos de estilo inline são sanitizados. Por padrão, certas propriedades CSS são permitidas enquanto as potencialmente perigosas são removidas.
• strip_style: Quando True, remove todos os atributos de estilo inline completamente.
• strip_classes: Quando True, remove todos os atributos de classe CSS do conteúdo armazenado.

Esta sanitização torna o campo Html seguro para uso em conteúdo gerado pelo usuário, razão pela qual aparece em formulários voltados para o cliente e modelos de email em todo o Odoo.

Atributos de Campo Chave

Além da sanitização, o campo Html compartilha muitos dos atributos padrão dos campos do Odoo:

• translate: Quando definido como True, o conteúdo do campo pode ser traduzido por idioma. O Odoo armazena uma versão separada do HTML para cada idioma ativo no banco de dados.
• required: Torna o campo obrigatório. Note que um campo Html contendo apenas espaços em branco ou tags vazias ainda aparecerá não vazio para a interface, portanto, a validação obrigatória funciona melhor em valores realmente em branco.
• default: Define um valor HTML padrão para novos registros. Útil para pré-preencher modelos de email ou descrições de produtos com texto padrão.
• compute: Liga um método Python que constrói o conteúdo HTML dinamicamente. Com store=True, o resultado é persistido no banco de dados.
• copy: Controla se o conteúdo HTML é duplicado ao copiar um registro. O padrão é True.

Como Aparece nas Visualizações

Em visualizações de formulário, um campo Html é renderizado como o editor de texto rico do Odoo. Os usuários recebem uma barra de ferramentas com opções de formatação e a área de conteúdo lida com texto estilizado, imagens e links. Em visualizações de lista, o Odoo normalmente exibe uma pré-visualização de texto simples com as tags HTML removidas, para manter a lista legível.

O atributo widget nas vistas XML permite controlar a renderização. O widget padrão para campos Html é o editor de texto rico. Você também pode renderizar um campo Html como saída HTML somente leitura usando o html widget, que é útil em vistas de relatórios ou em páginas de portal onde você deseja exibir conteúdo formatado sem uma barra de ferramentas editável.

Interação com o Odoo ORM

Do ponto de vista do desenvolvimento, ler um campo Html retorna uma string contendo a marcação HTML bruta. Escrever nele espera uma string HTML também. A sanitização acontece no nível do ORM antes que a escrita chegue ao banco de dados, então mesmo os valores escritos via a API XML-RPC passam pelo mesmo processo de limpeza quando sanitize=True.

Uma implicação prática: se você precisar armazenar e recuperar conteúdo que inclua tags ou atributos HTML personalizados que não estão na lista permitida do Odoo, você precisará definir sanitize=False ou ajustar as flags de sanitização na definição do campo. Este é um caso de uso avançado que requer consideração cuidadosa das implicações de segurança na sua implementação.

Casos de uso empresarial

O campo Html aparece em muitas áreas de uma implementação do Odoo. Aqui estão cinco exemplos do mundo real de fluxos de trabalho empresariais comuns.

Inventário e E-commerce: Descrições de Produtos

O campo Html mais amplamente utilizado no Odoo é o campo description_sale em product.template. Esta é a descrição do produto que os clientes veem na loja do website e nas linhas de pedidos de venda. Usar um campo Html aqui permite que as equipes de merchandising escrevam conteúdo estruturado do produto com marcadores, cabeçalhos e imagens incorporadas, tudo isso se traduz diretamente em melhores conversões de e-commerce. O mesmo registro de produto alimenta tanto o back-office quanto a vitrine, portanto, não há duplicação de conteúdo entre os sistemas.

Email Marketing: Corpos de Template

Os templates de email do Odoo dependem fortemente de campos Html. O campo body_html em mail.template armazena todo o corpo do email como HTML, incluindo layout, imagens e espaços reservados dinâmicos que são substituídos por valores reais no momento do envio. As equipes de marketing podem projetar conteúdo rico de email diretamente no Odoo sem precisar de uma ferramenta externa de design de email. O conteúdo é versionado e reutilizável em campanhas, cotações e fluxos de trabalho automatizados.

CRM: Notas e Descrições de Oportunidades

As equipes de vendas muitas vezes precisam capturar um contexto detalhado sobre um prospecto ou negócio. Campos Html em leads e oportunidades de CRM permitem que os representantes escrevam notas estruturadas com formatação, listas e links incorporados para documentos ou propostas externas. Isso é mais útil do que campos de texto simples quando as notas precisam ser compartilhadas entre uma equipe ou incluídas em relatórios impressos, uma vez que a formatação sobrevive em todos esses contextos.

Contabilidade: Termos e Condições da Fatura

Muitas empresas incluem termos de pagamento, cláusulas legais ou informações de garantia na parte inferior das faturas e ordens de venda. O campo note nas ordens de venda e faturas é um campo Html, permitindo que as equipes de finanças e operações formatem esses termos com a estrutura adequada. O conteúdo aparece de forma limpa em documentos PDF impressos, com quebras de linha e ênfase preservadas exatamente como foram inseridas.

RH: Descrições de Cargos

Quando as equipes de RH publicam vagas de emprego através do Odoo Recruitment, a descrição do trabalho é armazenada em um campo Html nos modelos hr.job e hr.applicant. Isso permite postagens de trabalho estruturadas com seções claras para responsabilidades, requisitos e benefícios, exatamente o tipo de conteúdo formatado que parece profissional em uma página de carreiras e ajuda a atrair os candidatos certos.

Criando ou personalizando o campo Html

Existem três maneiras principais de adicionar um campo Html a um modelo Odoo, dependendo da sua configuração técnica e abordagem de implantação.

Usando Odoo Studio (Sem Código)

O Odoo Studio torna simples adicionar um campo Html a qualquer formulário existente sem escrever código:

1. Abra o Odoo Studio a partir do menu principal.
2. Navegue até o formulário onde você deseja o campo.
3. Na barra lateral, arraste um campo Html ou Rich Text para o formulário.
4. Defina o rótulo e quaisquer outras opções no painel de propriedades do campo.
5. Salve e feche o Studio.

O Studio cria automaticamente o campo com um prefixo x_studio_, adiciona-o à visualização e gerencia a coluna do banco de dados. Nenhum passo de migração ou implantação é necessário da sua parte. O campo está imediatamente disponível para entrada de dados em toda a instância.

Usando Python em um Módulo Personalizado

Para desenvolvedores que estão construindo módulos Odoo, campos Html são definidos em arquivos de modelo Python. Esta abordagem é recomendada para qualquer personalização que precise ser controlada por versão e implantada em ambientes de teste e produção:

from odoo import fields, models

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

    x_delivery_instructions = fields.Html(
        string='Instruções de Entrega',
        sanitize=True,
        translate=True,
    )

Após definir o campo no modelo, adicione-o ao arquivo XML da visualização relevante para que apareça na interface. O Odoo cuida da criação da coluna TEXT no banco de dados automaticamente quando você instala ou atualiza o módulo. O campo será renderizado como um editor de texto rico na visualização do formulário sem qualquer configuração adicional de widget.

Usando a API XML-RPC

Se você gerenciar personalizações do Odoo programaticamente como parte de um pipeline de implantação ou um script de configuração remota, pode criar campos Html via API XML-RPC:

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

O valor ttype: html informa ao Odoo para criar um campo Html. A configuração state: manual marca-o como um campo criado pelo usuário, em vez de um definido por um módulo. Esta é a mesma abordagem que a Dasolo usa para a criação de campos remotos em ambientes de clientes, como parte de cadernos de configuração automatizados que podem ser executados e rastreados sem acesso direto ao servidor.

Observe que as opções de sanitização (sanitize, sanitize_tags, etc.) não podem ser definidas via API em ir.model.fields da mesma forma que são em Python. O comportamento padrão de sanitização se aplica ao criar campos através da API.

Melhores práticas

1. Mantenha a sanitização ativada, a menos que você tenha um forte motivo para não fazê-lo

O comportamento padrão de sanitização existe para proteger sua instância Odoo de vulnerabilidades de script entre sites. A maioria dos casos de uso funciona perfeitamente com a sanitização ativada. Desative-a apenas quando você estiver armazenando conteúdo gerado por um processo interno totalmente confiável, como um pipeline de renderização do lado do servidor, e nunca quando o conteúdo vier de entrada do usuário ou fontes externas.

2. Use translate=True para conteúdo de produto multilíngue

Se a sua instância do Odoo suportar múltiplas línguas, os campos Html exibidos no site ou em documentos voltados para o cliente devem ter translate=True. Isso permite que sua equipe mantenha conteúdo HTML separado para cada idioma, garantindo que os clientes vejam sempre descrições e termos em sua própria língua, em vez de uma alternativa.

3. Evite armazenar conteúdo de campo Html que dependa de recursos externos

Incorporar imagens ou scripts externos dentro de um campo Html cria dependências que podem falhar silenciosamente quando essas URLs externas mudam ou ficam offline. Use o sistema de anexos do Odoo para hospedar imagens internamente e referenciá-las com URLs relativas. Isso mantém seu conteúdo portátil e resiliente durante migrações de banco de dados e mudanças de servidor.

4. Use campos Html computados para conteúdo dinâmico de documentos

Para conteúdo que precisa ser gerado programaticamente, como um resumo formatado de linhas de pedido ou uma cláusula de garantia dinâmica, um campo Html computado com store=True é uma solução limpa. A lógica de computação reside em um só lugar, a saída é armazenada no banco de dados para acesso rápido, e o campo é renderizado corretamente tanto na interface quanto em relatórios PDF.

5. Considere o contexto de renderização ao escolher Html vs Texto

Se o conteúdo aparecer apenas no backend do Odoo em um contexto onde os usuários o leem como texto simples, um campo Texto pode ser suficiente. Use Html quando a formatação realmente importa para o leitor, como em uma página da web, um documento impresso ou um e-mail. Adicionar um campo Html onde um campo Texto simples seria suficiente introduz complexidade desnecessária para os usuários que precisam interagir com um editor de texto rico para anotações simples.

Erros comuns

Desativando a sanitização e esquecendo-se disso

Definir sanitize=False em um campo que os usuários podem editar diretamente é um risco de segurança. É fácil fazer isso durante o desenvolvimento para desbloquear um requisito de formatação e depois esquecer de revisá-lo antes de ir para a produção. Sempre documente por que a sanitização está desativada e planeje uma revisão antes da implantação.

Colando conteúdo de fontes externas com HTML quebrado

Quando os usuários colam conteúdo de documentos do Word, Google Docs ou sites em um campo Html, o resultado muitas vezes contém HTML bagunçado ou não padrão. Isso pode levar a renderizações inconsistentes, caracteres invisíveis que quebram buscas ou valores de campo inchados que desaceleram o carregamento das páginas. Incentive os usuários a usar a opção "Colar como texto simples" primeiro e depois reaplicar a formatação dentro do editor do Odoo.

Confundindo campo Html com o conteúdo do construtor de sites

O construtor de sites do Odoo utiliza blocos de construção e componentes Owl para construir o conteúdo das páginas. O HTML armazenado pelo construtor de sites nas visualizações de página não é o mesmo que você colocaria em um campo Html padrão. Tentar copiar HTML complexo do construtor de sites para um campo Html em um modelo geralmente não renderiza corretamente e pode ser removido pelo sanitizador.

Esquecendo de traduzir em implementações multilíngues

Em uma instância Odoo multilíngue, um campo Html sem translate=True mostra o mesmo conteúdo para usuários de todos os idiomas. Isso é aceitável para campos internos, mas se torna um problema para descrições de produtos, modelos de e-mail e qualquer conteúdo que chegue a contatos externos. Perder essa configuração é fácil de passar despercebido durante a configuração inicial e difícil de corrigir retroativamente uma vez que o conteúdo tenha sido inserido em apenas um idioma.

Usando campos Html em lugares onde texto simples é esperado

Algumas partes do Odoo, como assuntos de e-mail, títulos de relatórios ou respostas de API externas, esperam strings de texto simples. Se você armazenar um valor de campo Html em um contexto onde as tags HTML não são removidas, seus usuários verão marcação bruta como <p>Olá</p> em vez de texto limpo. Sempre verifique como e onde o valor do campo será consumido antes de escolher Html em vez de Char ou Text.

Conclusão

O campo Html é um dos tipos de campo mais poderosos no modelo de dados do Odoo. Ele fica silenciosamente por trás de descrições de produtos, modelos de e-mail, anúncios de emprego e notas de fatura, tornando o conteúdo formatado possível em todo o sistema sem nenhuma ferramenta adicional.

Entender como funciona, particularmente a camada de sanitização, o suporte à tradução e como se comporta em diferentes contextos de renderização, ajuda você a tomar melhores decisões ao projetar ou personalizar uma instância Odoo. Quer você esteja usando o Odoo Studio para adicionar um campo de texto rico a um formulário, definindo-o em Python como parte de um módulo personalizado, ou criando-o remotamente via API, os princípios abordados neste guia se aplicam a todas as três abordagens.

Como a maioria das coisas no Odoo, o campo em si é simples uma vez que você sabe o que está fazendo por trás das cenas. O valor vem de usá-lo nos lugares certos, com as configurações certas, para o tipo certo de conteúdo.

Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Quer você precise de ajuda para projetar um modelo de dados limpo, adicionar campos personalizados aos seus fluxos de trabalho, ou construir módulos Odoo completos adaptados ao seu negócio, nossa equipe está aqui. Entre em contato conosco e vamos conversar sobre o seu projeto Odoo.