Field Picker sidebar

Field Picker sidebar

Sidebar bên phải OnlyOffice editor — cho phép chèn Jinja placeholder vào template bằng click 1 lần thay vì gõ tay {{ record.customer_id.name }}.

Motivation

Trước sidebar (v1):

• Pháp chế gõ tay {{ record.project_id.investor_id.x_legal_representative }}
• Dài, dễ typo, không nhớ hết field name
• Field chain 3-hop khó nhớ

Sau sidebar (v2):

• Sidebar list 5 groups × 8-12 fields curated
• Click field → auto insert Jinja code tại vị trí cursor
• Preview label VN + Jinja code

5 Groups curated

Chủ đầu tư (Bên A)

Fields của record.project_id.investor_id — pháp nhân sở hữu KCN.

Label VN	Jinja snippet
Tên đầy đủ	{{ record.project_id.investor_id.name }}
Mã số thuế	{{ record.project_id.investor_id.vat }}
Địa chỉ	{{ record.project_id.investor_id.street }}, {{ record.project_id.investor_id.city }}
Điện thoại	{{ record.project_id.investor_id.phone }}
Fax	{{ record.project_id.investor_id.x_fax }}
Website	{{ record.project_id.investor_id.website }}
Người đại diện	{{ record.project_id.investor_id.x_legal_representative }}
Chức vụ	{{ record.project_id.investor_id.x_legal_rep_position }}
TK ngân hàng VN	{{ record.project_id.investor_id.bank_acc_vnd_id.acc_number }}
Ngân hàng VN	{{ record.project_id.investor_id.bank_acc_vnd_id.bank_id.name }}
TK ngân hàng USD	{{ record.project_id.investor_id.x_bank_acc_us }}
Swift Code	{{ record.project_id.investor_id.x_swift_code }}

Khách hàng (Bên B)

Fields của record.customer_id — pháp nhân thuê KCN.

Label VN	Jinja snippet
Tên công ty	{{ record.customer_id.name }}
Mã số thuế	{{ record.customer_id.vat }}
Địa chỉ	{{ record.customer_id.street }}, {{ record.customer_id.city }}
Điện thoại	{{ record.customer_id.phone }}
Fax	{{ record.customer_id.x_fax }}
Email	{{ record.customer_id.email }}
Website	{{ record.customer_id.website }}
Người đại diện	{{ record.customer_id.x_legal_representative }}
Chức vụ	{{ record.customer_id.x_legal_rep_position }}
TK ngân hàng VN	{{ record.customer_id.bank_acc_vnd_id.acc_number }}
TK ngân hàng USD	{{ record.customer_id.x_bank_acc_us }}
Swift Code	{{ record.customer_id.x_swift_code }}
Loại hình đầu tư	{{ record.customer_id.x_company_type_label }}
Ngành sản xuất	{{ record.customer_id.x_industry_classification }}

Hợp đồng

Fields của record (zone.contract / sale.order / zone.deposit.agreement).

Label VN	Jinja snippet
Số HĐ	{{ record.name }}
Ngày bắt đầu	{{ record.date_start | date_format }}
Ngày kết thúc	{{ record.date_end | date_format }}
Thời hạn (tháng)	{{ record.duration_months }}
Thời hạn (năm)	{{ (record.duration_months / 12) | round(0) }}
Tổng giá trị	{{ record.total_amount }}
Tổng giá trị (chữ)	{{ record.total_amount | to_vietnamese_words }}
Tiền thuê tháng	{{ record.monthly_rent }}
Currency	{{ record.currency_id.name }}

Lô đất / Kho

Fields của record.lot_id và record.warehouse_id.

Label VN	Jinja snippet
KCN	{{ record.project_id.name }}
Mã lô	{{ record.lot_id.code }}
Tên lô	{{ record.lot_id.name }}
Diện tích (m²)	{{ record.lot_id.area_sqm }}
Loại lô	{{ record.lot_id.lot_type_label }}
Vị trí (block)	{{ record.lot_id.location }}
Kho (nếu có)	{{ record.warehouse_id.name }}
Diện tích kho	{{ record.warehouse_id.area_sqm }}

Thời gian

Auxiliary date/time fields.

Label VN	Jinja snippet
Hôm nay (DD/MM/YYYY)	{{ today | date_format }}
Hôm nay (đầy đủ VN)	{{ today | date_format_vn_long }}
Ngày ký	{{ record.date_signed | date_format }}
Ngày duyệt	{{ record.date_approved | date_format }}
Thứ trong tuần	{{ today | weekday_vn }}
Tháng hiện tại	{{ today.month }}
Năm hiện tại	{{ today.year }}

Cách dùng

1. Mở template trong OnlyOffice editor

Cấu hình → Mẫu tài liệu → chọn template → 🖊️ Edit inline

2. Sidebar tự hiện bên phải

Nếu không thấy → click icon “Parkone Fields” trong toolbar → sidebar show.

3. Chọn group tab

Click 1 trong 5 tabs (Chủ đầu tư / KH / HĐ / Lô / Thời gian).

4. Đặt cursor tại chỗ muốn chèn

Vd trong đoạn “Bên A: ______” → click vào chỗ ______ để đặt cursor.

5. Click field trong sidebar

Vd click “Tên đầy đủ” của Chủ đầu tư → Jinja code {{ record.project_id.investor_id.name }} chèn vào cursor location.

6. Verify

Text {{ record.project_id.investor_id.name }} xuất hiện màu tím (highlighted như Word field code).

7. Save

Ctrl+S → template updated.

Single-click filter

Click chỉ 1 lần — không double-click. Nếu double-click:

• Browser fire 2 click events + 1 dblclick
• v1 có bug: chèn 2 lần
• v2 fixed: e.detail !== 1 filter + 500ms debounce (mọi click sau chỉ trigger 1 lần)

Preview snippet trước khi chèn

Hover vào field trong sidebar → tooltip show:

• Label VN
• Jinja code
• Value preview (nếu đang edit HĐ thực — show data cụ thể)

Vd hover “Tên đầy đủ” của KH → tooltip: “{{ record.customer_id.name }} → Cty TNHH Hoa Biết”

Customize snippets

Admin có thể thêm/sửa/xoá field trong sidebar:

1. Dev mode → Cấu hình → Technical → Parkone Doc Engine → Curated Fields

2. List config theo group

3. Add / Edit:

   • Group: chọn 1 trong 5
   • Label VN: hiển thị trong sidebar
   • Jinja snippet: code chèn khi click
   • Model: zone.contract / sale.order / all
   • Sort order

4. Save → sidebar reload

Custom fields Đại thêm sẽ xuất hiện cùng list default.

Sidebar không hiện

1. Verify OnlyOffice plugin parkone-fields được install (khi setup OnlyOffice container)
2. Refresh browser (Ctrl+Shift+R)
3. Check console errors — plugin có thể fail load
4. Verify JWT secret shared correctly

Chi tiết: Troubleshoot.

Best practices

Mẹo

• Đặt cursor CHÍNH XÁC trước click — snippet chèn ngay vị trí cursor, chèn nhầm chỗ → mất công di chuyển
• Verify snippet đúng field sau chèn — có thể sidebar caching cũ → chèn field sai
• Không chèn snippet vào bảng cell đã có formatting — có thể break format, chèn ngoài rồi cut vào
• Chèn xong nên preview render ngay để catch typo sớm

FAQ

Sidebar quá dài, cuộn không thấy field

• Search box top sidebar → gõ keyword filter
• Vd “MST” → show fields liên quan MST của cả 2 bên

Muốn thêm 1 group thứ 6 (vd “Milestones”)

Custom qua Dev mode (xem trên) — Admin add group mới với snippets.

Đang có 5 groups default. Có thể tăng lên 8-10 tối đa (UI limit).

Snippet chèn nhưng render không ra data

• Field không tồn tại trên record → check console log render
• Related field is empty → data thực chưa nhập vào record

Vd x_fax on partner — nếu partner chưa nhập fax → render empty. Cần user data thực trong Parkone trước khi render.

Liên kết liên quan

• OnlyOffice editor
• Snippet insert single-click
• Jinja placeholders
• Troubleshoot