Hướng dẫn tạo Custom Dojo Property Editor Optimizely CMS 12

Optimizely CMS 12 cung cấp một bộ công cụ chỉnh sửa thuộc tính tích hợp sẵn rất phong phú, nhưng đôi khi mô hình nội dung của bạn yêu cầu một trải nghiệm chỉnh sửa tùy chỉnh. Giao diện người dùng (UI) của CMS được xây dựng trên Dojo Toolkit, và việc hiểu cách tạo các Dojo widget tùy chỉnh sẽ mở ra khả năng tùy biến mạnh mẽ.

Trong hướng dẫn này, bạn sẽ học cách tạo một trình chỉnh sửa thuộc tính tùy chỉnh với một Dojo TextBox duy nhất — bao gồm ba lỗi 404 thực tế mà chúng tôi đã gặp phải và cách giải quyết chúng.

Bước 1: Tạo cấu trúc Module

Trong Optimizely CMS 12, các module Dojo tùy chỉnh phải nằm trong modules/_protected/. Hãy tạo cấu trúc thư mục sau trong project web của bạn:

CmsIv.Web/
  modules/_protected/
    CmsIv.Web/
      module.config
      Scripts/
        Editors/
          SimpleTextBoxEditor.js

Tạo file module.config tại đường dẫn CmsIv.Web/modules/_protected/CmsIv.Web/module.config:

<?xml version="1.0" encoding="utf-8"?>
<module>
  <dojo>
    <paths>
      <add name="app" path="Scripts" />
    </paths>
  </dojo>
</module>

File này đăng ký một Dojo path tên là app trỏ đến thư mục Scripts bên trong module của bạn.

Bước 2: Tạo Dojo Widget

Tạo widget tại CmsIv.Web/modules/_protected/CmsIv.Web/Scripts/Editors/SimpleTextBoxEditor.js. File JavaScript này định nghĩa hành vi của trình chỉnh sửa trên trình duyệt.

define([
    "dojo/_base/declare",
    "dojo/_base/lang",
    "dijit/_Widget",
    "dijit/_TemplatedMixin",
    "dijit/_WidgetsInTemplateMixin",
    "dijit/form/TextBox",
    "epi/shell/widget/_ValueRequiredMixin"
], function (
    declare, lang, _Widget, _TemplatedMixin,
    _WidgetsInTemplateMixin, TextBox, _ValueRequiredMixin
) {
    return declare("app/Editors/SimpleTextBoxEditor",
        [_Widget, _TemplatedMixin, _WidgetsInTemplateMixin, _ValueRequiredMixin], {

        templateString:
            '<div class="dijitInline">' +
                '<div data-dojo-type="dijit/form/TextBox" ' +
                    'data-dojo-attach-point="textBox" ' +
                    'data-dojo-attach-event="onChange:_onTextBoxChanged" ' +
                    'style="width: 100%;">' +
                '</div>' +
            '</div>',

        value: null,

        _setReadOnlyAttr: function (value) {
            this._set("readOnly", value);
            if (this.textBox) this.textBox.set("readOnly", value);
        },

        _setValueAttr: function (value) {
            this._set("value", value);
            if (this.textBox) this.textBox.set("value", value || "");
        },

        _getValueAttr: function () {
            return this.textBox ? this.textBox.get("value") : this.value;
        },

        _onTextBoxChanged: function (newValue) {
            this._set("value", newValue);
            this.onChange(newValue);
        },

        onChange: function (value) { /* CMS kết nối vào đây */ }
    });
});

Bước 3: Tạo EditorDescriptor

EditorDescriptor thông báo cho Optimizely biết widget Dojo nào sẽ được sử dụng cho một UIHint cụ thể.

using EPiServer.Shell.ObjectEditing;
using EPiServer.Shell.ObjectEditing.EditorDescriptors;

namespace CmsIv.Web.Business.EditorDescriptors
{
    [EditorDescriptorRegistration(TargetType = typeof(string), UIHint = UIHintValue)]
    public class SimpleTextBoxEditorDescriptor : EditorDescriptor
    {
        public const string UIHintValue = "SimpleTextBox";

        public SimpleTextBoxEditorDescriptor()
        {
            ClientEditingClass = "app/Editors/SimpleTextBoxEditor";
        }
    }
}

Bước 4: Đăng ký Module và sử dụng Property

Trong Optimizely CMS 12 (ASP.NET Core), bạn phải đăng ký module bảo mật trong Startup.cs:

using EPiServer.Shell.Modules;

// Bên trong ConfigureServices()
services.Configure<ProtectedModuleOptions>(options =>
{
    if (!options.Items.Any(m => m.Name == "CmsIv.Web"))
    {
        options.Items.Add(new ModuleDetails { Name = "CmsIv.Web" });
    }
});

Giải quyết các lỗi thường gặp (404)

Lỗi 1: Trùng lặp đường dẫn ClientResources

Triệu chứng: Trình duyệt yêu cầu file tại /ClientResources/ClientResources/Scripts/...

Nguyên nhân: Đặt module.config ở gốc dự án web với path="ClientResources/Scripts". Trong CMS 12, hệ thống có thể tự động thêm tiền tố đường dẫn tùy vào vị trí file.

Khắc phục: Luôn đặt module.config bên trong modules/_protected/{ModuleName}/ và sử dụng đường dẫn tương đối như path="Scripts".

Lỗi 2: Fallback về Shell Module

Triệu chứng: Trình duyệt yêu cầu file từ /EPiServer/Shell/... thay vì module của bạn.

Nguyên nhân: CMS không nhận diện được module tùy chỉnh, dẫn đến Dojo quay về đường dẫn mặc định của Shell. Thường do thiếu cấu hình ProtectedModuleOptions trong Startup.cs.

Kết luận

Việc tạo trình chỉnh sửa thuộc tính Dojo tùy chỉnh đòi hỏi sự phối hợp chính xác giữa code C# và các module JavaScript AMD. Bằng cách tuân thủ quy ước thư mục _protected và đảm bảo đăng ký module trong Startup.cs, bạn có thể mở rộng giao diện CMS một cách ổn định.