Hướng dẫn sử dụng

Dùng thử hoặc cài đặt EzyPlatform

Để có thể sử dụng được plugin này bạn sẽ cần phải có EzyPlatform.

Dùng thử

Nếu bạn không muốn cài EzyPlatform bạn có thể truy cập vào https://freestyle-admin.ezyplatform.com (Tên đăng nhập editor, mật khẩu là adminTrial123456$). Sau đó bạn có thể truy cập vào https://freestyle-admin.ezyplatform.com/admins/me nhập mật khẩu adminTrial123456$ để lấy access token.
Lưu ý rằng sẽ có nhiều người dùng thử nên nội dung của bạn có thể bị ghi đè bất cứ lúc nào.

Cài đặt EzyPlatform

Tốt hơn hết là bạn nên cài đặt EzyPlatform của riêng mình để có thể sử dụng và phát triển các sản phẩm cũng như thương hiệu của riêng mình.
Nếu bạn chỉ muốn cài đặt EzyPlatform trên môi trường localhost, bạn có thể, tham khảo hướng dẫn Cài đặt EzyPlatform.
Nếu bạn muốn triển khai EzyPlatform trên môi trường máy chủ với tên miền, bạn có thể tham khảo hướng dẫn Triển khai EzyPlatform.

Cài đặt theme Freestyle

Sau khi đã cài đặt EzyPlatform bạn có thể cài đặt theme freestyle. Nếu bạn chưa biết cách cài đặt theme, hãy tham khảo hướng dẫn này.

Cài đặt Visual Studio Code

Bạn có thể tải xuống tại đây và cài đặt

Cài đặt EzyArticle visual studio code extension

Sau khi cài đặt Visual Studio Code bạn có thể cài đặt EzyArticle extension bằng cách truy cập vào menu extensions của Visual Studio Code, tìm kiếm bằng từ khoá ezyarticle bạn sẽ thấy EzyArticle extension hiện ra, hãy cài đặt nó.

Khởi tạo dự án

Từ Visual Studio Code bạn hãy mở đến một thư mục trống sau đó chuột phải vào Explorer, một menu item Create EzyArticle Project sẽ hiện ra, bạn hãy click vào nó để khởi tạo dự án.
Khi dự án được khởi tạo bạn sẽ thấy các tập tin environment.json, README.md và AGENTS.md xuất hiện, đây là các tập tin môi trường, hướng dẫn sử dụng và hướng dẫn AI code.

Cài đặt môi trường

Trước tiên bạn sẽ cần thiết lập môi trường trong tập tin environment.json. Môi trường được sử dụng sẽ có thuộc tính "default": true.
Bạn sẽ cần truyền các giá trị:
  • admin_url: Là đường dẫn đến trang ezyplatform admin của bạn, ví dụ https://admin.example.com.
  • admin_access_token: Là access token của bạn đối với trang ezyplatform admin, bạn có thể truy cập vào page profile <admin_url>/admins/me ví dụ https://admin.example.com/admins/me sau đó tìm đến thuộc tính Access Token nhấn hiển thị, điền mật khẩu sau đó sao chép access token vào thuộc tính admin_access_token.
Nếu bạn không cần môi trường nào bạn có thể xoá nó đi, nhưng bắt buộc phải giữ lại ít nhất một môi trường có thuộc tính "default": true.

Đồng bộ page fragment

Lấy toàn bộ page fragment

Bạn có thể chuột phải vào explorer panel sau đó nhấn vào Sync Page Fragment menu item đồng bộ tất cả các page fragment có trên server xuống.

Lấy nội dung một page fragment

Sau khi đã đồng bộ toàn bộ page fragment bạn có thể đồng bộ nội dung từng page fragment bằng cách chuột phải vào thư mục fragment_name, ví dụ thư mục page fragment của bạn là page-fragments/common/header bạn hãy chuột phải vào thư mục header, một menu item Sync Page Fragment Folder sẽ hiện lên, bạn hãy click vào menu item đó để lấy tất cả nội dung page fragment từ server về.

Lấy từng thành phần của page fragment

Sau khi đã lấy nội dung một page fragment, sau này bạn có thể lấy nội dung của từng thành phần tương ứng với các tập tin content.html, foot.html, head.html, meta.json, bằng cách chuột phải vào từng tập tin, bạn sẽ thấy menu item Refresh Page Fragment File xuất hiện, hãy click vào menu item đó để lấy nội dung của thành phần từ từ server về.

Tạo một page fragment

Bạn có thể tạo một page fragment bằng cách tạo tạo thư mục page_name sau đó là thư mục fragment-name và các tập tin content.html, foot.html, head.html, meta.json.
Ví dụ:
page-fragments
    common
        header
            content.html
            foot.html
            head.html
            meta.json
Đối với tập tin meta.json bạn cần tạo với nội dung ví dụ như sau:
{
  "title": "Common header fragment",
  "contentType": "HTML",
  "status": "DRAFT"
}
Nếu page fragment đã tồn tại ở server rồi thì bạn cũng có thể đồng bộ nội dung như ở các phần trên đã mô tả.
Để biết thêm ý nghĩa các tập tin bạn có thể tham khảo tập tin AGENTS.md.

Tạo một trang

Bạn có thể tạo một trang bằng cách tạo thư mục page sau đó là các tập tin content.html, foot.html, head.html, meta.json, ví dụ:
pages
    home
        content.html
        foot.html
        head.html
        meta.json
Đối với tập tin meta.json bạn cần tạo với nội dung ví dụ như sau:
{
  "slug": "example-page",
  "title": "Example Page",
  "summary": "",
  "featuredImageId": 0,
  "pageType": "PAGE",
  "contentType": "HTML",
  "status": "DRAFT",
  "metadata": {}
}
Để biết thêm ý nghĩa các tập tin bạn có thể tham khảo tập tin AGENTS.md.

Đồng bộ nội dung trang

Sau khi đã tạo trang, bạn có thể chuột phải vào thư mục của trang, ví dụ home, menu item Sync Page Folder sẽ hiện ra, bạn hãy click vào menu item này để đồng bộ toàn bộ nội dung của trang.

Đồng bộ từng thành phần của trang

Sau khi đã lấy nội dung một trang, sau này bạn có thể lấy nội dung của từng thành phần tương ứng với các tập tin content.html, foot.html, head.html, meta.json, bằng cách chuột phải vào từng tập tin, bạn sẽ thấy menu item Refresh Page File xuất hiện, hãy click vào menu item đó để lấy nội dung của thành phần từ từ server về.

Các loại trang

Nó bao gồm:
  1. PAGE: Là dạng trang dùng chung phần header và footer với các trang khác.
  2. STANDALONE_PAGE: Là dạng trang động lập, trắng tinh, không dùng chung header và footer với trang khác, có nghĩa bạn sẽ cần cung cấp mã nguồn html, css, javascript cho nó.
  3. TEMPLATED_PAGE: Là dạng trang dùng chung phần header và footer với các trang khác nhưng cho phép bạn tự thiết lập tiêu đề trang, ví dụ:
<th:block
  th:with="slug=')}, pageTitle=')}">
  <title>[[]]</title>
  <meta name="title" th:content="" />
  <meta property="og:title" th:content="" />
  <meta property="og:site_name" th:content="" />
</th:block>

Media

Lưu ý: Tên media phải thoả mãn biểu thức ^[a-zA-Z0-9_-]+(.[a-zA-Z0-9_-]+)*$ nghĩa là phải là tiếng anh hoặc số hoặc các ký tự dấu chấm, gạch ngang, gạch dưới, ví dụ: hello-world.png. Nếu có bất ký tự nào không thoả mãn điều kiện nó sẽ tự động chuyển thành một ký tự ngẫu nhiên.

Xem trước

Để xem trước 1 trang bạn cần lưu lại nội dung trang sau đó chuột phải vào editor hoặc vào folder của trang hoặc bất kỳ file nào của trang sẽ có menu item Preview Page xuất hiện, bạn có thể nhấn vào menu item đó và trang xem trước sẽ hiển thị trên trình duyệt mặc định của bạn.
Lưu ý rằng việc lưu file của page fragment và trang trên editor chỉ lưu vào lịch sử chứ không làm ảnh hưởng đến nội dung đang được public trên server.

Xuất bản

Khi đã hài lòng với kết quả xem trước, bạn có thể xuất bản trang.
Đối với page fragment: Bạn có thể chuột phải vào editor hoặc vào folder của page fragment hoặc bất kỳ file nào của page fragment sẽ có menu item Publish Content To Server xuất hiện, bạn hãy nhấn vào menu item đó, lúc này nội dung sẽ được xuất bản và người dùng cuối sẽ thấy trang được thay đổi.
Đối với trang: Bạn có thể chuột phải vào editor hoặc vào folder của trang hoặc bất kỳ file nào của trang sẽ có menu item Publish Content To Server xuất hiện, bạn hãy nhấn vào menu item đó, lúc này nội dung sẽ được xuất bản và người dùng cuối sẽ thấy trang được thay đổi.

Đề xuất

Bạn hãy tạo một git repository để quản lý phiên bản các tập tin song song với việc lưu trữ trên EzyPlatform server của bạn để tận dụng được thêm sức mạnh của git.