Khi xây dựng ứng dụng Oracle APEX, chúng ta thường cần hiển thị nội dung khác nhau tùy theo dữ liệu.
Ví dụ: nếu bản ghi đã hoàn thành thì hiển thị badge màu xanh, nếu quá hạn thì hiển thị cảnh báo,
nếu không có ảnh thì hiển thị placeholder, hoặc nếu danh sách tag có nhiều giá trị thì lặp qua từng tag.
Cách làm quen thuộc là xử lý phần này trong SQL bằng case when, nối chuỗi HTML,
hoặc tạo thêm nhiều cột phụ để phục vụ giao diện. Cách đó chạy được, nhưng sau một thời gian
query sẽ trở nên khó đọc vì SQL bị trộn lẫn với logic trình bày.
Oracle APEX cung cấp một cơ chế rất hữu ích tên là Template Directives.
Đây là các chỉ thị đặt trong template hoặc HTML expression, giúp bạn điều khiển cách nội dung động
được render ngay trong phần giao diện, thay vì phải nhồi quá nhiều HTML và điều kiện hiển thị vào SQL.
Template Directives là gì?
Template Directives là các token đặc biệt được viết bên trong template text.
Khi APEX render component, các directive này được xử lý để quyết định phần nội dung nào sẽ được hiển thị.
Một số nhóm directive thường dùng gồm:
{if/}, {elseif/}, {else/}, {endif/}: hiển thị nội dung theo điều kiện.{case/}, {when/}, {otherwise/}, {endcase/}: xử lý nhiều trạng thái khác nhau.{loop/}, {endloop/}: lặp qua danh sách giá trị.{with/} và {apply/}: tái sử dụng template hoặc truyền tham số vào template.
Bạn có thể gặp Template Directives trong các thành phần như Cards, Reports, Interactive Grid,
Template Components, Email Templates hoặc các thuộc tính có hỗ trợ template.
Làm sao biết thuộc tính nào hỗ trợ Template Directives?
Trong Page Designer, không phải mọi thuộc tính đều hỗ trợ Template Directives.
Cách kiểm tra là mở phần help của thuộc tính đó. Nếu thấy dòng như
Supports Client-side Template Directives hoặc
Supports Server-side Template Directives, nghĩa là thuộc tính đó có thể dùng directive.
Ví dụ, trong Cards Region, bạn có thể dùng directive trong các phần như Title, Subtitle,
Body, Secondary Body hoặc HTML Expression tùy cấu hình của component.
Ví dụ vị trí cấu hình HTML Expression hoặc template content trong APEX Cards.
Vì sao nên dùng Template Directives?
Lợi ích lớn nhất là tách bớt logic giao diện ra khỏi SQL. SQL nên tập trung lấy dữ liệu,
còn template nên quyết định dữ liệu đó được hiển thị như thế nào.
Ví dụ, thay vì viết SQL như sau:
select task_name,
case
when status = 'DONE' then '<span class="badge done">Done</span>'
when status = 'OPEN' then '<span class="badge open">Open</span>'
else '<span class="badge other">Other</span>'
end as status_html
from tasks;
Bạn có thể để SQL đơn giản hơn:
select task_name,
status
from tasks;
Sau đó xử lý cách hiển thị trong template bằng directive. Kết quả là SQL dễ đọc hơn,
dễ bảo trì hơn và phần UI cũng linh hoạt hơn.
Dùng IF Directive để hiển thị có điều kiện
{if/} là directive dễ dùng nhất. Nó giúp hiển thị một đoạn nội dung nếu item,
column hoặc attribute có giá trị phù hợp.
{if STATUS/}
<span class="status-badge">&STATUS.</span>
{else/}
<span class="status-badge is-empty">Chưa có trạng thái</span>
{endif/}
Ví dụ trên có thể dùng trong HTML Expression của Cards hoặc Report column.
Nếu STATUS có giá trị, APEX hiển thị badge trạng thái.
Nếu không có giá trị, APEX hiển thị nội dung thay thế.
IF Directive rất phù hợp cho các trường hợp:
- Ẩn/hiện ảnh đại diện nếu có URL ảnh.
- Ẩn/hiện ngày hoàn thành nếu task đã hoàn thành.
- Hiển thị cảnh báo nếu dữ liệu thiếu.
- Hiển thị nút hoặc badge phụ nếu column có giá trị.
Dùng CASE Directive cho nhiều trạng thái
Khi dữ liệu có nhiều trạng thái, {case/} thường dễ đọc hơn nhiều đoạn
{if/} lồng nhau.
{case STATUS/}
{when DONE/}
<span class="dk-badge dk-badge-success">Hoàn thành</span>
{when OPEN/}
<span class="dk-badge dk-badge-info">Đang mở</span>
{when OVERDUE/}
<span class="dk-badge dk-badge-danger">Quá hạn</span>
{otherwise/}
<span class="dk-badge dk-badge-muted">Khác</span>
{endcase/}
Cách này rất hữu ích khi bạn muốn hiển thị badge, icon, class CSS hoặc text khác nhau
theo từng trạng thái nghiệp vụ.
Thay vì để SQL tạo sẵn HTML, SQL chỉ cần trả về STATUS.
Phần template sẽ quyết định trạng thái đó được render thành màu sắc và nội dung nào.
Dùng LOOP Directive để lặp danh sách
{loop/} dùng khi bạn có một danh sách giá trị và muốn render nhiều phần tử HTML.
Ví dụ, một bài viết có nhiều tag, một sản phẩm có nhiều thuộc tính, hoặc một task có nhiều nhãn.
{loop TAGS/}
<span class="dk-tag">&APEX$ITEM.</span>
{endloop/}
Tùy cách bạn chuẩn bị dữ liệu và component đang dùng, danh sách có thể được xử lý để render thành
nhiều tag nhỏ trong giao diện. Đây là cách rất tiện để làm UI gọn mà không phải nối chuỗi HTML phức tạp trong SQL.
Dùng WITH và APPLY để tái sử dụng template
Khi UI bắt đầu có nhiều đoạn lặp lại, bạn có thể dùng {with/} và {apply/}
để áp dụng một template có tham số. Cách này giúp template gọn hơn, đặc biệt khi làm Template Components
hoặc các đoạn UI có cùng cấu trúc.
{with LABEL:=Trạng thái/}
{with VALUE:=&STATUS./}
{apply MY_BADGE_TEMPLATE/}
{endwith/}
{endwith/}
Trong thực tế, bạn sẽ dùng cách này khi muốn chuẩn hóa một kiểu hiển thị, ví dụ badge,
summary block, card nhỏ hoặc status line.
Ví dụ thực tế: Card bài viết có category và trạng thái
Giả sử bạn có danh sách bài viết trong Oracle APEX với các cột:
TITLE: tiêu đề bài viết.CATEGORY_NAME: tên danh mục.STATUS: trạng thái xuất bản.SUMMARY: mô tả ngắn.
SQL nên giữ đơn giản:
select title,
category_name,
status,
summary,
published_at
from blog_posts
order by published_at desc;
Trong template hoặc HTML Expression, bạn có thể dùng directive:
<div class="blog-card">
<div class="blog-card-meta">
<span>&CATEGORY_NAME.</span>
{case STATUS/}
{when PUBLISHED/}
<span class="status published">Đã xuất bản</span>
{when DRAFT/}
<span class="status draft">Bản nháp</span>
{otherwise/}
<span class="status muted">Khác</span>
{endcase/}
</div>
<h2>&TITLE.</h2>
{if SUMMARY/}
<p>&SUMMARY.</p>
{endif/}
</div>
Cách này giúp code dễ hiểu: SQL lấy dữ liệu, template lo hiển thị.
Kết quả mong muốn: card gọn, trạng thái rõ ràng, SQL không bị trộn quá nhiều HTML.
Template Directives và escaping
Khi làm giao diện động, escaping là vấn đề rất quan trọng. Nếu bạn nối HTML trong SQL rồi dùng raw output,
bạn cần cực kỳ cẩn thận để tránh XSS, đặc biệt khi dữ liệu có thể đến từ người dùng.
Template Directives giúp giảm nhu cầu tạo HTML trực tiếp trong SQL.
Bạn vẫn cần hiểu rõ context escaping của APEX, nhưng cách tiếp cận này thường giúp code sạch hơn
và dễ kiểm soát hơn so với việc trả về nhiều cột HTML raw từ query.
Nguyên tắc thực tế:
- Dữ liệu người dùng nhập vào nên được escape đúng context.
- Không dùng
!RAW nếu không thật sự cần.
- Không đưa HTML do người dùng nhập trực tiếp ra giao diện.
- Chỉ render HTML từ nguồn bạn kiểm soát.
Khi nào không nên dùng Template Directives?
Template Directives rất hữu ích, nhưng không phải logic nào cũng nên đưa vào template.
Những logic nghiệp vụ quan trọng vẫn nên nằm ở SQL hoặc PL/SQL.
Không nên dùng directive để thay thế:
- Kiểm tra quyền truy cập.
- Business rule quan trọng.
- Tính toán dữ liệu phức tạp.
- Validation trước khi ghi dữ liệu.
- Logic ảnh hưởng đến bảo mật hoặc giao dịch.
Hãy xem Template Directives là công cụ cho phần trình bày, không phải nơi xử lý nghiệp vụ cốt lõi.
Kết luận
Template Directives là một tính năng nhỏ nhưng rất đáng học trong Oracle APEX.
Nó giúp bạn viết giao diện động gọn hơn, giảm HTML trong SQL và làm cho component như Cards,
Reports, Interactive Grid hoặc Email Templates trở nên linh hoạt hơn.
Cách dùng tốt nhất là để SQL tập trung vào dữ liệu, còn template tập trung vào cách hiển thị.
Khi phân tách rõ hai phần này, ứng dụng APEX của bạn sẽ dễ bảo trì hơn, dễ mở rộng hơn
và chuyên nghiệp hơn.