Hướng dẫn sử dụng Shortcode Blog trong Init Manga – Đầy đủ & chi tiết

Nguyên tắc chung

• Định danh truyện: Tất cả shortcode đều hỗ trợ 3 cách định danh: id="123" (ID của post truyện), slug="ten-truyen" (Slug URL), title="Tên Truyện" (Tiêu đề chính xác)
• An toàn: Nếu không tìm thấy truyện, shortcode sẽ trả về rỗng hoặc nội dung từ tham số empty. Có thể override qua filter init_manga_empty_html.
• Hiệu năng: Các số liệu như lượt xem, đánh giá được cache 1 giờ với key manga_stats_{ID} trong group init_manga.
• Validation: style/layout/size dùng whitelist; columns/limit bị giới hạn để tránh vỡ layout.
• Accessibility: HTML ngữ nghĩa, ARIA labels, tương thích UIkit.

1. [manga_info] – Thẻ truyện

Hiển thị card truyện với đầy đủ thông tin: ảnh bìa (hỗ trợ che mờ + nút hiện ảnh), tiêu đề, mô tả ngắn, lượt xem, số chương, nhãn 18+, dấu hoàn thành.

[manga_info id="123"]
[manga_info slug="ten-truyen" show_all_genres="true"]
[manga_info title="Tên Truyện" empty="<p>Không tìm thấy truyện</p>"]

Tham số:

• show_all_genres="true" – Hiển thị tối đa 3 thể loại (mặc định chỉ 1)
• empty – HTML thay thế khi không có dữ liệu

Lưu ý kỹ thuật:

• Đổi size thumbnail qua filter init_manga_card_thumb_size
• Trạng thái map sang label + class UIkit tự động
• Chuẩn hoá tuổi: adult/r18/nsfw → 18+

2. [manga_details] – Thông tin chi tiết

Hiển thị danh sách thông tin: tên khác, số chương (có pluralization), tình trạng, tác giả (Author Mode hoặc taxonomy author_tax), nhóm dịch, thể loại.

[manga_details id="123"]
[manga_details slug="ten-truyen" empty="<div>Chưa có dữ liệu</div>"]

Tham số:

• empty – HTML thay thế khi không có dữ liệu. Không hỗ trợ fields/layout.

3. [manga_stats] – Thống kê

Hiển thị lượt xem, lượt theo dõi, điểm đánh giá (kèm số lượt), bình luận với 3 kiểu giao diện. Cache 1 giờ.

[manga_stats id="123"]
[manga_stats slug="ten-truyen" style="cards"]
[manga_stats title="Tên Truyện" style="badges"]

Tham số:

• style – Kiểu hiển thị: inline (mặc định), cards (dạng thẻ), badges (dạng nhãn)
• empty – HTML thay thế khi không có dữ liệu

Hook: init_manga_stats_output để tuỳ chỉnh HTML output (thêm tooltip, đổi icon…).

4. [manga_read_button] – Nút đọc truyện

Tạo nút CTA dẫn đến permalink truyện (không xử lý first/latest/continue).

[manga_read_button id="123"]
[manga_read_button slug="ten-truyen" text="Đọc ngay" style="primary" size="large"]
[manga_read_button title="Tên Truyện" class="uk-width-1-1 uk-text-center"]

Tham số:

• text – Nhãn nút (mặc định: Đọc %manga_title%)
• style – Style UIkit: primary, secondary, danger…
• size – Kích thước: small, large (mặc định: bình thường)
• class – CSS class bổ sung
• empty – HTML thay thế khi không có dữ liệu

5. [manga_list] – Danh sách truyện

Tạo danh sách từ nhiều truyện theo ID hoặc slug. Hỗ trợ 3 layout, sử dụng template parts cho reusability.

[manga_list ids="123,456,789" layout="grid" columns="3" limit="9"]
[manga_list slugs="truyen-a,truyen-b" layout="list" limit="10"]
[manga_list ids="1,2,3,4,5" layout="carousel" show_chapters="true" show_stats="true"]

Tham số:

• ids hoặc slugs – Danh sách định danh (ngăn cách bằng dấu phẩy). Chọn một kiểu định danh.
• layout – Kiểu hiển thị: grid, list, carousel
• columns – Số cột (1-6, chỉ áp dụng cho grid)
• limit – Giới hạn số lượng (1-50)
• show_chapters – Hiển thị thông tin chương (nếu có init_manga_get_chapters)
• show_stats – Hiển thị thống kê trong item template
• empty – HTML thay thế khi không có dữ liệu

Lưu ý: Query tối ưu với no_found_rows, bật cache meta/tax. Tuỳ biến query qua filter init_manga_list_query_args.

6. [manga_team] – Thông tin nhóm dịch

Hiển thị thông tin nhóm dịch, lấy trực tiếp từ team_id hoặc từ truyện. Hỗ trợ enhanced team data (avatar, banner, social links, stats).

[manga_team id="123"]
[manga_team slug="ten-truyen" style="card" show_social="true" show_stats="true"]
[manga_team team_id="45" style="inline" empty="<span>Không có nhóm dịch</span>"]

Tham số:

• id / slug / title – Nguồn là truyện
• team_id – ID term nhóm dịch (chỉ định trực tiếp)
• style – Kiểu hiển thị: card, badge, inline (mặc định)
• show_social – Hiển thị link mạng xã hội
• show_stats – Hiển thị thống kê nhóm
• empty – HTML thay thế khi không có dữ liệu

7. [team_manga] – Truyện theo nhóm

Liệt kê các truyện của một nhóm dịch cụ thể với header thông tin nhóm.

[team_manga team_id="45" layout="grid" columns="3" limit="6"]
[team_manga team_slug="ten-nhom" layout="list" limit="10" show_chapters="true"]

Tham số:

• team_id hoặc team_slug – Định danh nhóm dịch (bắt buộc một trong hai)
• layout – Kiểu hiển thị: grid, list
• columns – Số cột (1-6, áp dụng cho grid)
• limit – Giới hạn số lượng (1-50)
• show_chapters, show_stats – Hiển thị thông tin bổ sung
• empty – HTML thay thế khi không có dữ liệu

8. [manga_compare] – So sánh truyện

So sánh chi tiết 2 truyện với nhau theo các tiêu chí: tình trạng, số chương, điểm đánh giá, lượt xem, thể loại, tác giả. Hiển thị dạng bảng với nút CTA.

[manga_compare ids="123,456"]

Quy tắc:

• Bắt buộc truyền đúng 2 ID hợp lệ. Không hỗ trợ slugs.
• ID sai hoặc khác 2 → cảnh báo UIkit.

9. [manga_highlight] – Block nổi bật

Tạo block trích dẫn hoặc nổi bật cho truyện. Lấy từ text hoặc fallback sang excerpt/nội dung.

[manga_highlight id="123"]
[manga_highlight slug="ten-truyen" style="card" text="Câu trích dẫn hay"]
[manga_highlight title="Tên Truyện" style="banner" chapter="12"]

Tham số:

• style – Kiểu hiển thị: quote (mặc định), card, banner
• text – Nội dung tùy chỉnh (nếu không có sẽ lấy excerpt)
• chapter – Hiển thị nhãn “Chapter N”
• empty – HTML thay thế khi không có nội dung/dữ liệu

10. [manga_author] – Tác giả

Hiển thị thông tin tác giả với avatar, mô tả ngắn và các liên kết mạng xã hội (nếu có).

[manga_author id="123"]
[manga_author slug="ten-truyen"]
[manga_author author_slug="ten-tac-gia" show_social="true"]

Tham số:

• id / slug – Định danh từ manga để lấy ra tác giả
• author_id / author_slug – Định danh trực tiếp tác giả
• show_social – Hiển thị liên kết mạng xã hội (mặc định: false)
• style – Kiểu hiển thị: inline, badge, card (mặc định: inline)
• empty – HTML thay thế khi không có dữ liệu

11. [author_manga] – Manga theo tác giả

Liệt kê các manga của một tác giả với layout dạng grid/list.

[author_manga author_id="12" layout="grid" columns="3" limit="6"]
[author_manga author_slug="ten-tac-gia" layout="list" limit="10" show_stats="true"]

Tham số:

• author_id hoặc author_slug – Định danh tác giả (bắt buộc một trong hai)
• layout – Kiểu hiển thị: grid, list
• columns – Số cột (1-6, chỉ áp dụng cho grid)
• limit – Giới hạn số lượng manga hiển thị (1-50)
• show_stats – Hiển thị thống kê cơ bản (views, follows, rating)
• empty – HTML thay thế khi không có dữ liệu

12. [manga_publisher] – Nhà xuất bản của truyện

Hiển thị thông tin Publisher (NXB) của một truyện, hoặc từ một term publisher chỉ định. Kế thừa giao diện của [manga_team], dùng chung metabox với team (ưu tiên key team_*, fallback publisher_*).

[manga_publisher id="123"]
[manga_publisher slug="ten-truyen" style="card" show_social="true" show_stats="true"]
[manga_publisher publisher_id="45" style="inline" empty="<span>Chưa có NXB</span>"]

Tham số:

• id / slug / title – Lấy NXB từ truyện
• publisher_id – ID term publisher (chỉ định trực tiếp)
• style – card, badge, inline (mặc định: inline)
• show_social – Hiển thị social (Facebook/Discord/…)
• show_stats – Hiển thị thống kê (số manga, thành viên, since…)
• empty – HTML thay thế khi không có dữ liệu

Lưu ý kỹ thuật:

• Ảnh banner/avatar đọc từ team_banner/team_avatar (fallback publisher_banner/publisher_avatar).
• Social đọc từ team_social_{provider} (fallback publisher_social_{provider}).
• Chuỗi i18n mới: "Published by", "Published by %s", "%d manga published" (text-domain init-manga).

13. [publisher_manga] – Truyện theo nhà xuất bản

Liệt kê các truyện thuộc một publisher cụ thể. Giao diện & tham số tương tự [team_manga].

[publisher_manga publisher_id="45" layout="grid" columns="3" limit="6" show_stats="true"]
[publisher_manga publisher_slug="shueisha" layout="list" limit="10" show_chapters="true"]

Tham số:

• publisher_id hoặc publisher_slug – Định danh NXB (bắt buộc một trong hai)
• layout – grid, list
• columns – Số cột (1–6, chỉ áp dụng cho grid)
• limit – Số lượng truyện (1–50)
• show_chapters – Hiển thị chương mới (nếu có init_manga_get_chapters)
• show_stats – Hiển thị thống kê trong item
• empty – HTML thay thế khi không có dữ liệu

Hook:

• init_publisher_manga_query_args – Can thiệp query (thêm sort, meta_query…).

Giới hạn & Validation

• style: inline, cards, badge, badges, card, quote, banner, grid, list, carousel
• layout: grid, list, carousel
• size: small, large (hoặc để trống)
• columns: 1–6 (tự động giới hạn); limit: 1–50 (tự động giới hạn)

Cache hiệu năng: Thống kê manga (views, rating, chapters…) được cache 1 giờ với key manga_stats_{ID}, group cache: init_manga.

Hooks mở rộng

• init_manga_empty_html – Tùy chỉnh HTML rỗng cho từng shortcode
• init_manga_card_thumb_size – Thay đổi kích thước thumbnail cho [manga_info] và danh sách
• init_manga_list_query_args – Can thiệp query [manga_list]
• init_team_manga_query_args – Can thiệp query [team_manga]
• init_manga_stats_output – Tùy chỉnh HTML [manga_stats]

Ví dụ tổng hợp

[manga_info slug="one-piece" show_all_genres="true"]
[manga_details slug="one-piece"]
[manga_stats slug="one-piece" style="badges"]
[manga_read_button slug="one-piece" style="primary" size="large"]
[manga_list ids="1,2,3,4,5,6" layout="grid" columns="3" show_stats="true"]
[manga_team slug="one-piece" style="card" show_social="true"]
[team_manga team_id="45" layout="list" limit="5"]
[manga_compare ids="123,456"]
[manga_highlight slug="one-piece" style="banner" text="Cuộc phiêu lưu tìm kho báu huyền thoại!"]

Tips sử dụng

• Hiệu quả: Sử dụng [manga_list] với danh sách ID/slug có sẵn thay vì query phức tạp.
• Giao diện: Chọn layout và số cột phù hợp với thiết kế trang, tương thích UIkit grid.
• Trải nghiệm: Luôn thiết lập empty với thông báo thân thiện khi không có dữ liệu.
• Nhất quán: Sử dụng cùng một style cho các shortcode trong cùng trang để đồng bộ giao diện.
• i18n: Tất cả text đều hỗ trợ đa ngôn ngữ với text-domain init-manga và pluralization.