API /ezyarticle/api/v1/convert-content dùng để chuyển đổi nội dung sang HTML trong môi trường admin trước khi preview, render thử, hoặc tái sử dụng nội dung ở module khác. API nhận nội dung thô cùng contentType, chạy qua bộ chuyển đổi tương ứng, rồi trả về nội dung sau chuyển đổi trong trường content.

Tổng quan

Endpoint:
POST /ezyarticle/api/v1/convert-content
Content-Type: application/json
API này thuộc admin API, yêu cầu người gọi đã đăng nhập admin và có quyền/feature quản lý bài viết tương ứng. Thông thường API được gọi từ giao diện admin bằng session hiện tại, ví dụ qua $.ajax.
API không lưu nội dung vào database. Nó chỉ nhận input, chuyển đổi/decorate, rồi trả kết quả.

Request

{
  "content": "<nội dung cần chuyển đổi>",
  "contentType": "THYMELEAF",
  "parameters": {
    "name": "EzyArticle",
    "year": 2026
  },
  "languageCode": "vi"
}
Các trường:
TrườngKiểuBắt buộcMô tả
contentstringKhôngNội dung đầu vào. Nếu không truyền, hệ thống dùng chuỗi rỗng.
contentTypestringKhôngKiểu nội dung cần chuyển đổi. Nếu rỗng, mặc định là HTML.
parametersobjectKhôngMap biến truyền vào bộ chuyển đổi. Nếu không truyền, dùng object rỗng.
languageCodestringKhôngMã ngôn ngữ dùng để tạo Locale, ví dụ vi, en. Nếu rỗng hoặc không hợp lệ, hệ thống fallback về English.

Response

{
  "content": "<nội dung sau chuyển đổi>"
}

Luồng xử lý

sequenceDiagram
    participant UI as Giao diện admin
    participant API as /ezyarticle/api/v1/convert-content
    participant Manager as Bộ điều phối decorator
    participant Decorator as Decorator theo contentType

    UI->>API: POST content, contentType, parameters, languageCode
    API->>Manager: decorateContent(...)
    Manager->>Manager: Nếu contentType rỗng thì dùng HTML
    Manager->>Decorator: Chạy các decorator đã đăng ký theo contentType
    Decorator-->>Manager: Nội dung đã chuyển đổi
    Manager-->>API: content
    API-->>UI: { "content": content }

Các contentType thường dùng

HTML: nếu không có decorator riêng được đăng ký cho HTML, nội dung được trả về như cũ.
EDITOR_JS_JSON: nhận JSON theo cấu trúc Editor.js và chuyển các block hỗ trợ sang HTML. Một số block được hỗ trợ gồm paragraph, header, image, list, quote, code, table, embed, raw, delimiter, linkTool, media.
THYMELEAF: render nội dung như một template Thymeleaf, truyền parameters vào template variables và dùng languageCode cho locale.
JAVASCRIPT: thực thi nội dung như JavaScript trong admin runtime, truyền parameters làm dữ liệu đầu vào, rồi lấy kết quả trả về dưới dạng chuỗi.

Ví dụ gọi bằng JavaScript

async function convertDataContent(data) {
  return new Promise((resolve, reject) => {
    $.ajax({
      type: 'POST',
      url: '/ezyarticle/api/v1/convert-content',
      data: JSON.stringify({
        content: data.content,
        contentType: data.contentType,
        parameters: data.parameters,
        languageCode: ezyadmin.lang
      }),
      contentType: 'application/json'
    }).done(function (response) {
      resolve(response.content);
    }).fail(function (error) {
      reject(error);
      ezyadmin.processUpdateApiErrors({}, error);
    });
  });
}

Ví dụ với Thymeleaf

Request:
{
  "content": "<p>Xin chào <span th:text=""></span></p>",
  "contentType": "THYMELEAF",
  "parameters": {
    "name": "EzyArticle"
  },
  "languageCode": "vi"
}
Response:
{
  "content": "<p>Xin chào <span>EzyArticle</span></p>"
}

Lưu ý

API chỉ chuyển đổi nội dung, không validate toàn bộ bài viết và không tự upload media.
Với API này, parameters không tự lấy từ cấu hình value map mặc định nếu bạn không truyền vào; khi bỏ trống, nó là object rỗng.
Nếu không tìm thấy decorator phù hợp với contentType, nội dung sẽ được trả về như input ban đầu. Với một số lỗi trong quá trình decorate, hệ thống cũng ưu tiên trả lại nội dung gốc thay vì làm hỏng luồng preview/chuyển đổi.