Wprowadzenie
Kiedy przeglądasz opis produktu w sklepie opartym na Odoo i widzisz pogrubione nagłówki, listy punktowane i wstawione zdjęcia, za tym wszystkim stoi jeden typ pola: pole Html. To niezwykle elastyczne pole pojawia się w wielu miejscach systemu — często tam, gdzie użytkownicy potrzebują zapisać sformatowaną treść.
W przeciwieństwie do zwykłego pola tekstowego, które przechowuje prosty ciąg znaków, pole Html zapisuje bogaty markup z pełnym formatowaniem. Dlatego warto stosować je tam, gdzie treść ma mieć strukturę i styl: opisy produktów, szablony wiadomości, wewnętrzne notatki czy fragmenty strony internetowej.
W tym artykule wyjaśniamy, czym jest pole Html w kontekście ORM Odoo i bazy danych, jak działa w realnych procesach biznesowych oraz jak je dodać lub zmodyfikować za pomocą Odoo Studio i kodu Python. Omówimy też najczęstsze błędy, które popełniają użytkownicy podczas pracy z tym polem.
Czym jest pole Html w Odoo
W modelu danych Odoo pole Html przeznaczone jest do przechowywania sformatowanej treści HTML. Na poziomie bazy danych mapuje się na kolumnę typu TEXT w PostgreSQL — faktycznie zapisanym ciągiem jest kod HTML. Odoo zajmuje się renderowaniem i oczyszczaniem, dlatego w interfejsie użytkownik widzi edytor WYSIWYG, a nie surowy kod źródłowy.
Dla użytkownika pole Html działa jak edytor WYSIWYG. Można w nim zastosować pogrubienie, kursywę, nagłówki, listy, linki, tabele oraz osadzać obrazy. Cała zawartość zapisywana jest w postaci uporządkowanego HTML, dzięki czemu zachowuje wygląd przy wyświetlaniu i drukowaniu.
W modelu Python pole Html definiuje się podobnie do innych pól; przedstawimy przykładową deklarację jako ilustrację konwencji.
Przykładowa definicja pola Html w Pythonie wygląda tak:
from odoo import fields, models
class ProductTemplate(models.Model):
_inherit = 'product.template'
x_technical_specs = fields.Html(
string='Technical Specifications',
sanitize=True,
sanitize_tags=True,
)
Parametr string określa etykietę widoczną w interfejsie. Najważniejszy jest parametr sanitize — decyduje, czy Odoo przed zapisem usunie potencjalnie niebezpieczne fragmenty HTML. Dla bezpieczeństwa opcja ta jest domyślnie włączona.
W Odoo Studio ten typ pola występuje pod nazwą Html lub Rich Text. Studio automatycznie nadaje takiemu polu prefiks x_studio_. Jeśli pole definiujesz w module Python lub przez API XML-RPC, sam wybierasz jego nazwę techniczną.
Jak działa to pole
Przy dodawaniu pola Html framework tworzy w PostgreSQL kolumnę typu TEXT, bez ograniczeń długości — dlatego pole nadaje się do dłuższych treści. Warstwę sanitizacji Odoo uruchamia przed zapisaniem wartości do bazy, aby chronić system przed wstrzyknięciami i XSS.
Sanityzacja i bezpieczeństwo
Najważniejsza cecha pola Html w porównaniu z innymi typami to właśnie mechanizm oczyszczania treści. Domyślnie Odoo usuwa tagi i atrybuty, które mogłyby posłużyć do ataków XSS. Zachowanie to kontroluje kilka atrybutów pola.
- sanitize: gdy ustawione na True (domyślnie), Odoo wykonuje pełną procedurę sanitizacji przed zapisem. Wyłączaj tę opcję tylko wtedy, gdy masz pewność, że treść pochodzi ze zaufanego źródła i trzeba zachować surowy HTML.
- sanitize_tags: gdy True, Odoo usuwa tagi spoza listy dozwolonych. Wyłączenie tej opcji pozwala na dowolne tagi, ale zwiększa ryzyko, dlatego wymaga rozwagi.
- sanitize_attributes: kontroluje, czy atrybuty tagów HTML będą poddawane oczyszczaniu.
- sanitize_style: decyduje o oczyszczaniu wewnętrznych atrybutów style. Domyślnie pewne właściwości CSS są dozwolone, inne usuwane jako potencjalnie niebezpieczne.
- strip_style: gdy True, usuwa wszystkie atrybuty stylu inline.
- strip_classes: gdy True, usuwa atrybuty klas CSS z zapisywanej treści.
Dzięki mechanizmowi sanitizacji pole Html nadaje się do treści generowanych przez użytkowników, dlatego jest powszechnie stosowane w formularzach skierowanych do klientów oraz w szablonach mailowych w całym systemie.
Kluczowe atrybuty pola
Poza sanitizacją pole Html dzieli wiele standardowych właściwości z innymi polami w Odoo.
- translate: jeśli True, zawartość pola można tłumaczyć na różne języki. Odoo przechowuje osobne wersje HTML dla aktywnych języków, co jest kluczowe w sklepach wielojęzycznych.
- required: oznacza pole jako obowiązkowe. Trzeba pamiętać, że pole Html zawierające tylko puste tagi lub same spacje może być widoczne jako niepuste — walidacja najlepiej działa, gdy pole jest rzeczywiście puste.
- default: pozwala ustawić domyślną zawartość HTML dla nowych rekordów — przydatne do predefiniowanych szablonów maili czy opisów produktów.
- compute: powiązuje pole z metodą Python, która generuje treść HTML dynamicznie. Przy store=True wynik jest przechowywany w bazie.
- copy: kontroluje, czy zawartość ma być kopiowana przy duplikowaniu rekordu. Domyślnie True.
Wyświetlanie w widokach
W widokach formularzy pole Html renderowane jest jako edytor bogatego tekstu z paskiem narzędzi. W widokach listy Odoo zwykle pokazuje krótką, oczyszczoną zapowiedź bez tagów HTML, aby lista pozostała czytelna.
Atrybut widget w XML pozwala kontrolować prezentację. Domyślnie Html korzysta z edytora rich text. Możesz też użyć widgetu html do wyświetlania sformatowanej treści w trybie tylko do odczytu — przydatne w raportach PDF lub na stronach portalu, gdzie nie chcesz widocznego paska edycji.
Interakcja z ORM Odoo
Z punktu widzenia dewelopera czytanie pola Html zwraca ciąg znaków z surowym markupem HTML, a zapis oczekuje także stringa HTML. Sanitizacja odbywa się na poziomie ORM przed zapisem do bazy, więc wartości przesyłane przez XML-RPC również są oczyszczane, jeśli sanitize=True.
Praktyczna konsekwencja: jeśli musisz przechowywać niestandardowe tagi lub atrybuty, które nie znajdują się na liście dozwolonych, będziesz musiał ustawić sanitize=False lub zmienić flagi sanitizacji — to zaawansowane użycie, które wymaga ostrożności i analizy ryzyka.
Przykłady zastosowań w biznesie
Pole Html pojawia się w wielu miejscach wdrożenia Odoo. Poniżej pięć typowych zastosowań w codziennych procesach biznesowych.
Magazyn i e‑commerce: opisy produktów
Najczęściej wykorzystywanym polem Html jest description_sale na modelu product.template — to opis widoczny klientom w sklepie i na linii zamówienia. Dzięki Html zespoły merchandisingowe mogą tworzyć przejrzyste opisy z listami, nagłówkami i obrazami, co poprawia konwersję w sklepie. Jedno źródło danych zasila backend i frontend, więc nie ma duplikacji treści.
Email marketing: treści szablonów
Szablony e‑maili w Odoo bazują na polach Html. Pole body_html w mail.template przechowuje całą treść wiadomości razem z układem, obrazami i dynamicznymi placeholderami, które zastępowane są wartościami przy wysyłce. Dzięki temu zespoły marketingu projektują bogate wiadomości bez zewnętrznych narzędzi, a treści są wielokrotnego użytku w kampaniach i automatyzacjach.
CRM: notatki i opisy szans sprzedaży
Handlowcy często zapisują szczegółowe informacje o leadach czy szansach. Pola Html w CRM pozwalają na sformatowane notatki z listami i linkami do dokumentów lub ofert. To przydatne, gdy notatki mają być udostępniane w zespole lub drukowane — formatowanie pozostaje zachowane.
Księgowość: warunki na fakturach
Firmy umieszczają na fakturach warunki płatności, klauzule prawne czy gwarancje. Pole note na zleceniach sprzedaży i fakturach jest polem Html, dzięki czemu działy finansów mogą sformatować treść, a przy generowaniu PDFów łamanie linii i wyróżnienia są zachowane.
HR: opisy stanowisk
W rekrutacji opisy stanowisk przechowywane są w polach Html na modelach hr.job i hr.applicant. Pozwala to tworzyć czytelne ogłoszenia z oddzielnymi sekcjami dla obowiązków, wymagań i benefitów — wyglądają profesjonalnie na stronie karier i przyciągają właściwych kandydatów.
Tworzenie i dostosowywanie pola Html
Są trzy główne sposoby dodania pola Html do modelu Odoo, zależnie od posiadanego stosu technicznego i sposobu wdrożenia.
Za pomocą Odoo Studio (bez kodu)
Odoo Studio pozwala dodać pole Html do formularza bez programowania — to najszybsza metoda dla użytkowników biznesowych.
- Otwórz Odoo Studio z głównego menu.
- Przejdź do formularza, w którym chcesz dodać pole.
- Z paska wybierz pole Html lub Rich Text i przeciągnij je na formularz.
- W panelu właściwości ustaw etykietę i opcje pola.
- Zapisz i zamknij Studio.
Studio stworzy pole z prefiksem x_studio_, doda je do widoku i utworzy kolumnę w bazie — nie potrzebujesz dodatkowej migracji. Pole jest od razu dostępne do edycji w całej instancji.
W Pythonie w module niestandardowym
Dla deweloperów pole Html definiuje się w plikach modeli Pythona. Ta metoda jest zalecana, gdy potrzebujesz kontroli wersji i wdrożenia na staging/produkcji.
Przykład definicji w module:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_delivery_instructions = fields.Html(
string='Delivery Instructions',
sanitize=True,
translate=True,
)
Po dodaniu pola w modelu trzeba wstawić je do odpowiedniego widoku XML, by było widoczne w UI. Odoo automatycznie utworzy kolumnę TEXT przy instalacji lub aktualizacji modułu, a w formularzu pole będzie wyświetlane jako edytor bogatego tekstu bez dodatkowej konfiguracji widgetu.
Przez API XML-RPC
Jeżeli zarządzasz konfiguracją zdalnie lub w ramach pipeline'u wdrożeniowego, pola Html można tworzyć również przez XML-RPC.
Przykład tworzenia pola przez API:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_notes',
'field_description': 'Custom Notes',
'model_id': model_id,
'ttype': 'html',
'state': 'manual',
}]
)
Wartość ttype: 'html' instruuje Odoo, aby utworzyć pole Html. state: 'manual' oznacza pole stworzone przez użytkownika, a nie przez moduł. Taka metoda jest przydatna w zdalnych skryptach konfiguracyjnych, które można uruchamiać bez bezpośredniego dostępu do serwera.
Warto pamiętać, że opcje sanitizacji (sanitize, sanitize_tags itp.) nie są ustawiane w ten sam sposób przez API na ir.model.fields jak w Pythonie — tworzone pole przyjmuje domyślne ustawienia sanitizacji.
Dobre praktyki
1. Trzymaj sanitize włączone, chyba że masz mocny powód by je wyłączyć
Domyślna sanitizacja chroni przed atakami XSS. Dla większości zastosowań pozostaw ją aktywną. Wyłączaj tylko wtedy, gdy treść pochodzi z w pełni zaufanego procesu serwerowego i masz pewność, że nie ma ryzyka wprowadzenia złośliwego kodu.
2. Ustaw translate=True dla treści wielojęzycznych
Jeśli system obsługuje wiele języków, pola Html wyświetlane klientom lub na dokumentach powinny mieć translate=True. Dzięki temu możesz prowadzić osobne wersje opisów i warunków dla różnych języków, zamiast polegać na jednym tłumaczeniu zastępczym.
3. Nie osadzaj treści zależnych od zasobów zewnętrznych
Wstawianie obrazów czy skryptów z zewnętrznych serwisów tworzy zależności, które mogą się zerwać, gdy linki przestaną działać. Lepiej przechowywać pliki jako załączniki w Odoo i używać względnych odnośników — to zwiększa odporność treści przy migracjach i zmianach serwera.
4. Do treści generowanej programowo używaj pól obliczanych (computed Html)
Jeżeli treść ma powstawać dynamicznie, np. podsumowanie pozycji zamówienia czy klauzula gwarancyjna, warto wykorzystać computed Html ze store=True. Logika generowania jest scentralizowana, wynik zapisuje się w bazie, a pole jest szybko dostępne w UI i w raportach PDF.
5. Zastanów się nad kontekstem renderowania przy wyborze Html vs Text
Jeśli treść będzie jedynie czytana w backendzie bez potrzeby formatowania, zwykłe pole Text może wystarczyć. Html stosuj tam, gdzie format ma znaczenie — na stronach serwisu, w wydrukach czy mailach. Wprowadzenie pola Html tam, gdzie wystarcza Text, może niepotrzebnie utrudnić użytkownikom pracę z pełnym edytorem.
Częste pułapki
Wyłączenie sanitize i brak dalszej uwagi
Ustawienie sanitize=False dla pola edytowanego przez użytkowników stanowi ryzyko bezpieczeństwa. Łatwo zrobić to tymczasowo w trakcie rozwoju, a potem zapomnieć. Dokumentuj powody wyłączenia i planuj przegląd przed wdrożeniem produkcyjnym.
Wklejanie treści z zewnętrznych źródeł z uszkodzonym HTML
Kiedy użytkownicy kopiują treści z Worda, Google Docs czy stron WWW, wynikowy HTML często jest zanieczyszczony lub niestandardowy. Może to powodować niekonsekwentne renderowanie, niewidoczne znaki utrudniające wyszukiwanie czy nadmierne rozmiary, które spowalniają ładowanie. Zachęcaj użytkowników do używania opcji "Wklej jako zwykły tekst" i ponownego formatowania w edytorze Odoo.
Mylące oczekiwania względem treści z kreatora stron
Kreator stron Odoo używa bloków i komponentów Owl do budowy zawartości. HTML generowany przez kreator nie zawsze jest kompatybilny z prostym polem Html — próba wklejenia skomplikowanego markup z kreatora do pola modelu zwykle nie zadziała dobrze i może zostać usunięta przez sanitizator.
Zapominanie o translate w wdrożeniach wielojęzycznych
W instancji wielojęzycznej pole Html bez translate=True pokaże tę samą treść wszystkim użytkownikom. To w porządku dla pól wewnętrznych, ale problematyczne dla opisów produktów, szablonów mailowych i treści skierowanych do odbiorców zewnętrznych. Brak tej opcji łatwo umyka podczas konfiguracji i trudno to naprawić po wprowadzeniu treści w jednym języku.
Stosowanie Html tam, gdzie oczekuje się zwykłego tekstu
Niektóre elementy Odoo, jak temat maila, tytuły raportów czy odpowiedzi API, wymagają zwykłego tekstu. Jeżeli zapiszesz tam HTML i nie zostanie on odpowiednio oczyszczony, użytkownicy zobaczą surowe tagi zamiast czystego tekstu. Przed wyborem Html sprawdź, w jakim kontekście wartość będzie konsumowana.
Podsumowanie
Pole Html to jedno z najpotężniejszych pól w modelu danych Odoo. Pracuje w tle przy opisach produktów, szablonach mailowych, ofertach pracy i notkach na fakturach, umożliwiając sformatowaną treść bez konieczności stosowania dodatkowych narzędzi.
Zrozumienie jego działania — zwłaszcza warstwy sanitizacji, wsparcia tłumaczeń oraz zachowania w różnych kontekstach renderowania — pozwala podejmować lepsze decyzje podczas projektowania i dostosowywania instancji Odoo. Niezależnie od tego, czy używasz Studio, definiujesz pole w Pythonie, czy tworzysz je przez API, te zasady mają zastosowanie.
Jak wiele elementów w Odoo, samo pole jest proste, gdy wiesz, co się dzieje pod spodem. Rzeczywista wartość pojawia się wtedy, gdy pole użyjesz we właściwych miejscach, z odpowiednimi ustawieniami i dla właściwego rodzaju treści.
W Dasolo pomagamy firmom wdrażać, dostosowywać i optymalizować Odoo we wszystkich obszarach działalności. Jeśli potrzebujesz wsparcia przy projektowaniu logicznego modelu danych, dodawaniu pól dostosowanych do procesów czy tworzeniu pełnych modułów Odoo, nasz zespół jest do dyspozycji. Skontaktuj się z nami Porozmawiajmy o Twoim projekcie Odoo.