Giới Thiệu

Nếu bạn đã từng phải dành hàng giờ vật lộn với API Cài Đặt của WordPress, bạn sẽ hiểu nỗi đau này. Mặc dù rất mạnh mẽ, nhưng API này có thể rất dài dòng, khó hiểu và khó bảo trì. Việc xây dựng một trang tùy chọn đơn giản có thể liên quan đến hàng chục callback, hook và mã boilerplate. Vậy nếu bạn có thể làm tất cả trong một tệp duy nhất, dễ đọc với API sạch sẽ và lưu loát thì sao?

Giới thiệu WP Settings Builder, một framework mã nguồn mở của WPTechnix giúp đơn giản hóa việc tạo các trang cài đặt cho các plugin và chủ đề của bạn.

Bài viết này sẽ không chỉ dạy bạn cách sử dụng nó, mà còn tại sao đây là một cách tiếp cận tốt hơn. Chúng ta sẽ bắt đầu từ một ví dụ "Hello World" đơn giản đến một trang cài đặt đầy đủ chức năng với các tab, logic điều kiện và các trường nâng cao.

Tại Sao Nên Sử Dụng WP Settings Builder?

Trước khi đi vào mã, hãy cùng tìm hiểu vấn đề. API Cài Đặt của WordPress yêu cầu bạn:

Phân tán mã của bạn: Logic được phân tán qua các lệnh add_menu_page, register_setting, add_settings_section, và add_settings_field.
Viết nhiều mã boilerplate: Mỗi trường yêu cầu một hàm callback riêng chỉ để hiển thị HTML của nó.
Xử lý việc làm sạch thủ công: Bạn phải tạo một hàm làm sạch cho mỗi cài đặt.
Gặp khó khăn với các trường phức tạp: Tạo các thứ như trình chọn ngày, tải tài liệu đa phương tiện, hoặc trình chọn bài viết có hỗ trợ AJAX yêu cầu mã tùy chỉnh và enqueuing tài sản đáng kể.

WP Settings Builder giải quyết các vấn đề này bằng cách cung cấp một giao diện thống nhất, hướng đối tượng. Tất cả cấu hình cho một trang—tiêu đề, phần, trường và tab—được định nghĩa ở một nơi duy nhất bằng cách sử dụng một API lưu loát, có thể xâu chuỗi.

Bước 1: Cài Đặt và Thiết Lập

Điều đầu tiên, hãy đưa framework vào dự án của bạn. Cách được khuyến nghị là qua Composer.

Điều hướng đến thư mục plugin hoặc chủ đề của bạn và chạy:

Copy

composer require wptechnix/wp-settings-builder

Tiếp theo, hãy chắc chắn rằng bạn đã bao gồm autoloader của Composer trong tệp plugin chính hoặc functions.php của chủ đề bạn.

Copy

<?php
// plugins/my-awesome-plugin/my-awesome-plugin.php

// Nhúng autoloader của Composer.
require_once __DIR__ . '/vendor/autoload.php';

// Mã plugin của bạn bắt đầu từ đây...

Vậy là xong! Framework giờ đã sẵn sàng để sử dụng.

Bước 2: Quy Trình 3 Bước — Trang Cài Đặt Đầu Tiên của Bạn

Framework được xây dựng xung quanh một mô hình 3 bước đơn giản và dễ nhớ: tạo, cấu hình, và khởi tạo.

create(): Lấy một instance builder và tạo một trang.
configure(): Sử dụng các phương thức lưu loát để định nghĩa cấu trúc và các trường của trang.
init(): Đăng ký trang và tất cả các hook của nó với WordPress.

Hãy xây dựng một trang cài đặt cơ bản dưới menu chính "Cài Đặt".

Copy

<?php
use WPTechnix\WP_Settings_Builder\Settings_Builder;

add_action( 'admin_init', function() {
    // 1. TẠO: Lấy một builder và tạo một trang.
    $page = ( new Settings_Builder() )->create( 'my_plugin_settings_group', 'my_plugin_options' );

    // 2. CẤU HÌNH: Thiết lập trang và thêm các trường.
    $page->set_page_title( 'Plugin Tuyệt Vời Của Tôi' )
         ->set_menu_title( 'Plugin Của Tôi' )
         ->set_parent_slug( 'options-general.php' ); // Dưới 'Cài Đặt'

    // Thêm một phần để nhóm các trường
    $page->add_section( 'general_section', 'Cài Đặt Chung' );

    // Thêm một trường văn bản đơn giản
    $page->add_field(
        'license_key',           // ID Trường
        'general_section',       // ID Phần
        'text',                  // Loại Trường
        'Khóa Bản Quyền',        // Nhãn Trường
        [ 'description' => 'Nhập khóa bản quyền của bạn để nhận cập nhật.' ] // Tham số Trường
    );

    // Thêm một trường chuyển đổi
    $page->add_field(
        'enable_awesome_mode',
        'general_section',
        'switch',
        'Kích Hoạt Chế Độ Tuyệt Vời',
        [
            'description' => 'Bật chế độ này để làm cho plugin trở nên tuyệt vời hơn 110%.',
            'default'     => true,
        ]
    );

    // 3. KHỞI TẠO: Xây dựng trang.
    $page->init();
});

Thêm mã này vào plugin của bạn, và bạn sẽ có một trang cài đặt hoàn toàn chức năng. Chú ý cách nó dễ đọc? Mọi thứ nằm trong một nơi, và các phương thức lưu loát, có thể xâu chuỗi (->set_page_title()->...) làm cho cấu hình sạch sẽ và hợp lý.

Bước 3: Tăng Cường Với Các Trường Nâng Cao và Các Tab

Các trường văn bản đơn giản là tuyệt vời, nhưng các plugin hiện đại cần nhiều hơn thế. Hãy tạo một trang cài đặt phức tạp hơn, có tab cho một plugin thương mại điện tử giả định.

Tổ Chức Với Các Tab

Khi bạn có nhiều cài đặt, các tab là cần thiết cho trải nghiệm người dùng tốt.

Copy

// Trong chuỗi cấu hình của bạn:
$page->add_tab( 'general_tab', 'Chung', 'dashicons-admin-generic' );
$page->add_tab( 'api_tab', 'Cài Đặt API', 'dashicons-admin-network' );

// Khi thêm một phần, chỉ cần chỉ định tab mà nó thuộc về.
$page->add_section( 'general_section', 'Chi Tiết Cửa Hàng', 'general_tab' );
$page->add_section( 'api_section', 'API Cổng Thanh Toán', 'api_tab' );

Sử Dụng Các Trường Mạnh Mẽ

Bây giờ hãy thêm một số trường nâng cao vào các phần mới của chúng ta. WP Settings Builder có hơn 30 loại trường, bao gồm:

color: Một trình chọn màu của WordPress.
media: Một trình tải lên thư viện đa phương tiện.
post: Một trường tìm kiếm có hỗ trợ AJAX để chọn một bài viết, trang, hoặc loại bài viết tùy chỉnh.
wysiwyg: Trình soạn thảo TinyMCE đầy đủ của WordPress.

Copy

// Thêm một Trình Tải Lên Hình Ảnh cho logo cửa hàng
$page->add_field( 'store_logo', 'general_section', 'media', 'Logo Cửa Hàng' );

// Thêm một Trình Chọn Bài Viết để chọn trang "Điều Khoản Dịch Vụ"
$page->add_field(
    'terms_page',
    'general_section',
    'post',
    'Trang Điều Khoản Dịch Vụ',
    [
        'description' => 'Chọn trang chứa điều khoản và điều kiện của bạn.',
        'query_args'  => [ 'post_type' => 'page' ], // Chỉ tìm kiếm các trang
    ]
);

// Thêm một trường Mật Khẩu an toàn cho khóa API
$page->add_field( 'api_key', 'api_section', 'password', 'Khóa Bí Mật API' );

Một trong những tính năng tốt nhất là tài sản (CSS/JS) cho các trường này chỉ được tải nếu bạn thực sự sử dụng trường. Sử dụng một trình chọn color, và script trình chọn màu sẽ được enqueued. Nếu không, nó sẽ không được tải. Điều này giữ cho các trang quản trị của bạn nhanh chóng và nhẹ nhàng.

Bước 4: Thực Hiện Logic Điều Kiện

Logic điều kiện là điều phân tách các mẫu tĩnh khỏi các trải nghiệm động. WP Settings Builder đã tích hợp sẵn điều này—không cần JavaScript.

Hãy thêm một trường chỉ xuất hiện nếu một tùy chọn cụ thể được kích hoạt.

Copy

// Đầu tiên, thêm một switch để bật/tắt chế độ thử nghiệm
$page->add_field( 'enable_test_mode', 'api_section', 'switch', 'Kích Hoạt Chế Độ Thử Nghiệm' );

// Tiếp theo, thêm một trường văn bản chỉ hiển thị khi chế độ thử nghiệm BẬT
$page->add_field(
    'test_api_key',
    'api_section',
    'text',
    'Khóa API Thử Nghiệm',
    [
        'description' => 'Khóa này sẽ được sử dụng cho các giao dịch sandbox.',
        'condition' => [
            'field'    => 'enable_test_mode', // ID của trường điều khiển
            'operator' => '==',               // Toán tử so sánh
            'value'    => true,               // Giá trị để kiểm tra
        ],
    ]
);

Giờ đây, trường "Khóa API Thử Nghiệm" sẽ xuất hiện và biến mất khi bạn bật hoặc tắt switch "Kích Hoạt Chế Độ Thử Nghiệm".

Bước 5: Truy Xuất và Sử Dụng Các Cài Đặt của Bạn

Định nghĩa các cài đặt chỉ là một nửa cuộc chiến. Bạn cũng cần một cách dễ dàng để truy xuất chúng trong mã frontend của chủ đề hoặc plugin của bạn.

Framework cung cấp một phương thức trợ giúp tĩnh để lấy instance trang và các cài đặt của nó.

Copy

use WPTechnix\WP_Settings_Builder\Settings_Builder;

function get_my_plugin_option( $key, $default = null ) {
    // Lấy instance trang bằng ID duy nhất của nó ($option_name)
    $page = Settings_Builder::get_instance( 'my_plugin_options' );

    // Nếu trang tồn tại, lấy cài đặt
    if ( $page ) {
        return $page->get_setting( $key, $default );
    }

    return $default;
}

// --- Ví dụ Sử Dụng ---

// Lấy ID logo cửa hàng (trả về ID đính kèm)
$logo_id = get_my_plugin_option( 'store_logo' );
if ( $logo_id ) {
    echo wp_get_attachment_image( $logo_id, 'medium' );
}

// Kiểm tra xem chế độ tuyệt vời có bật không (trả về true/false)
if ( get_my_plugin_option( 'enable_awesome_mode' ) ) {
    // Làm điều gì đó tuyệt vời!
}

Kết Luận: Xây Dựng Tốt Hơn, Nhanh Hơn

WP Settings Builder không chỉ là một công cụ; nó là một quy trình làm việc tốt hơn. Nó khuyến khích mã sạch, có tổ chức và dễ bảo trì, cho phép bạn xây dựng các trang cài đặt chuyên nghiệp trong một phần nhỏ thời gian. Bạn có thể tập trung vào các tính năng của plugin của mình, không phải là vật lộn với mã boilerplate.

Bạn đã học cách cài đặt framework, tạo một trang cơ bản, tổ chức nó với các tab, thêm các trường nâng cao, thực hiện logic điều kiện và truy xuất các cài đặt của bạn. Bạn đã sẵn sàng để xây dựng các trang tùy chọn mạnh mẽ cho dự án tiếp theo của mình.

Sẵn sàng khám phá sâu hơn?

Tài liệu chính thức là nơi tốt nhất để tìm hiểu tất cả các trường và tính năng nâng cao có sẵn.

Kiểm tra gói trên kho lưu trữ GitHub của WPTechnix.
Khám phá tài liệu chi tiết trong Wiki của GitHub.

Hãy thử nghiệm trên dự án tiếp theo của bạn. Bạn sẽ không bao giờ muốn quay lại cách cũ nữa.

Hướng Dẫn Tối Ưu Xây Dựng Trang Quản Trị WordPress với WP Settings Builder

Giới Thiệu

Tại Sao Nên Sử Dụng WP Settings Builder?

Bước 1: Cài Đặt và Thiết Lập

Bước 2: Quy Trình 3 Bước — Trang Cài Đặt Đầu Tiên của Bạn

Bước 3: Tăng Cường Với Các Trường Nâng Cao và Các Tab

Tổ Chức Với Các Tab

Sử Dụng Các Trường Mạnh Mẽ

Bước 4: Thực Hiện Logic Điều Kiện

Bước 5: Truy Xuất và Sử Dụng Các Cài Đặt của Bạn

Kết Luận: Xây Dựng Tốt Hơn, Nhanh Hơn

Bình luận