Cấu trúc thư mục


nedka

nedka

Quản trị viên
27/08/2016 16:29

Trước khi bắt đầu, xin lưu ý với bạn rằng đây là tài liệu hướng dẫn sử dụng thành phần giao diện và biến giao diện trong quá trình viết gói mở rộng, chứ không phải tài liệu thiết kế giao diện cho phpBB.


Cấu trúc thư mục

  • styles
    • tên_giao_diện
      • template: Chứa các tập tin giao diện (.html).
        • event: Chứa các tập tin chèn vào các sự kiện giao diện (tên tập tin cũng là tên sự kiện).
      • theme: Chứa hình ảnh, CSS, JS, phông chữ...

Quy tắc thay thế
  • Các quy tắc bên dưới chỉ áp dụng cho tập tin giao diện .html.
  • Nếu tập tin trong thư mục tên_giao_diện từ gói mở rộng trùng tên với thư mục styles/tên_giao_diện/ từ bộ nhân phpBB, tập tin trong gói mở rộng sẽ thay thế tập tin gốc chỉ trong phạm vi gói mở rộng (các liên kết thông qua app.php), còn lại các trang gốc trong phpBB sẽ vẫn dùng tập tin cũ có sẵn.
  • Tập tin trong thư mục tên_giao_diện từ gói mở rộng cũng được dùng cho các giao diện khác tên nếu giao diện đó kế thừa khuôn mẫu từ tên_giao_diện. Bạn có thể tìm thấy thiết lập này trong tập tin style.cfg của mỗi giao diện.
    Chép
    parent = prosilver
  • Nếu bạn đổi tên_giao_diện thành all, các thành phần bên trong sẽ áp dụng cho tất cả giao diện tìm thấy.
  • Nếu vừa có alltên_giao_diện thì all chỉ dùng cho các giao diện còn lại.


Đường dẫn trong giao diện


nedka

nedka

Quản trị viên
27/08/2016 16:30

Các biến giao diện mang giá trị đường dẫn đôi khi cái thì có dấu / ở cuối, cái thì không. Vì thế, nên bạn cần chú ý khi dùng. Các đường dẫn màu xanh lá dưới đây là có dấu / ở cuối, còn màu đỏ thì không. Biến giao diện nào gạch chân nghĩa là có thể thay đổi trong bảng quản trị.

  • ROOT_PATH: Trả về thư mục gốc cài đặt phpBB.
  • BOARD_URL: Trả về địa chỉ truy cập trang phpBB của bạn, ví dụ http://vinabb.vn/forum/.
  • T_THEME_PATH: Trả về thư mục styles/tên_giao_diện/theme.
  • T_TEMPLATE_PATH: Trả về thư mục styles/tên_giao_diện/template.
  • T_SUPER_TEMPLATE_PATH: Nếu giao diện kế thừa khuôn mẫu từ giao diện khác, trả về thư mục styles/tên_giao_diện_cha/template. Nếu không có, thì trả về giống với T_TEMPLATE_PATH.
  • T_ASSETS_PATH: Trả về thư mục assets chứa các tập tin Javascript sử dụng chung giữa các giao diện.
  • T_IMAGES_PATH: Trả về thư mục images/ chứa các loại hình ảnh khác nhau.
  • T_SMILIES_PATH: Trả về thư mục images/smilies/ chứa biểu tượng vui. Đường dẫn này có thể thay đổi trong bảng quản trị.
  • T_AVATAR_PATH: Trả về thư mục images/avatars/upload/ chứa các hình đại diện do thành viên tải lên.
  • T_AVATAR_GALLERY_PATH: Trả về thư mục images/avatars/gallery/ chứa các hình đại diện có sẵn của bạn cho thành viên lựa chọn.
  • T_ICONS_PATH: Trả về thư mục images/icons/ chứa biểu tượng bài viết.
  • T_RANKS_PATH: Trả về thư mục images/ranks/ chứa hình cấp bậc.
  • T_UPLOAD_PATH: Trả về thư mục files/ chứa các tập tin đính kèm.
BOARD_URL khác tất cả các biến giao diện đường dẫn còn lại, vì nó không phải đường dẫn trong hệ thống tập tin trên máy chủ, mà là một liên kết có thể truy cập từ bên ngoài. Ta có thể dùng nó trong trường hợp gọi một tập tin hình ảnh, CSS hay JS đặc biệt nào đó không theo thư mục chỉ định của phpBB.


Các biến giao diện có sẵn


nedka

nedka

Quản trị viên
27/08/2016 16:30

Liên kết
Không phải liên kết nào cũng dành cho mọi người dùng, ví dụ tin nhắn chỉ dành cho thành viên đã đăng ký tài khoản. Vì vậy, bạn cần kết hợp với kiểm tra điều kiện thông qua Twig trong mã HTML:

Chép
{% if S_REGISTERED_USER %}<a href="{{ U_PRIVATEMSGS }}>{{ lang('PRIVATE_MESSAGES') }}</a>"{% endif %}
Xem lại bài Kiểm tra cấp phép với các lệnh kiểm tra trong HTML.

Và đôi khi việc hiển thị một liên kết, ta phải xét xem chức năng liên quan có đang bật hay không. Như với tin nhắn vừa ví dụ ở trên, ta phải kết hợp với biến kiểm tra điều kiện S_DISPLAY_PM:
Chép
{% if S_REGISTERED_USER and S_DISPLAY_PM %}<a href="{{ U_PRIVATEMSGS }}>{{ lang('PRIVATE_MESSAGES') }}</a>"{% endif %}
Danh sách các biến kiểm tra điều kiện này có ở bên dưới.
  • U_PRIVATEMSGS: Tin nhắn.
  • U_RETURN_INBOX: Tin nhắn (tương tự U_PRIVATEMSGS).
  • U_MEMBERLIST: Danh sách thành viên.
  • U_LOGIN_LOGOUT: "Đăng nhập" nếu chưa đăng nhập và "Thoát" nếu đã đăng nhập rồi.
  • U_INDEX: Trang chủ diễn đàn (cũng là trang chủ chính nếu không thiết lập U_SITE_HOME bên dưới).
  • U_SITE_HOME: Trang chủ (thiết lập liên kết trong bảng quản trị).
  • U_SEARCH: Tìm kiếm.
  • U_REGISTER: Đăng ký.
  • U_PROFILE: Bảng thiết lập của người dùng.
  • U_USER_PROFILE: Trang cá nhân của người dùng.
  • U_MODCP: Bảng điều hành.
  • U_FAQ: Trợ giúp.
  • U_SEARCH_SELF: Tìm bài viết của chính mình.
  • U_SEARCH_NEW: Tìm bài viết mới.
  • U_SEARCH_UNANSWERED: Tìm bài viết chưa có ai trả lời.
  • U_SEARCH_UNREAD: Tìm bài viết chưa xem (có thể là bài viết cũ nhưng người dùng chưa từng xem qua).
  • U_SEARCH_ACTIVE_TOPICS: Tìm chủ đề gần đây.
  • U_DELETE_COOKIES: Xóa dữ liệu trình duyệt.
  • U_TERMS_USE: Điều khoản sử dụng.
  • U_PRIVACY: Chính sách riêng tư.
  • U_FEED: Trang phát tin RSS.
  • U_VIEW_ALL_NOTIFICATIONS: Thông báo tương tác.
  • U_MARK_ALL_NOTIFICATIONS: Đánh dấu đã xem hết thông báo tương tác.
  • U_NOTIFICATION_SETTINGS: Thiết lập thông báo tương tác.

Liên kết có điều kiện
Loại liên kết này có kiểm tra điều kiện khi tạo ra biến giao diện, vì thế nếu điều kiện sai (giá trị false) thì biến giao diện này trả về rỗng, do đó ta phải luôn dùng:
Chép
{% if U_ABC %}<a href="{{ U_ABC }}">{{ lang('ABC') }}</a>{% endif %}
  • U_VIEWONLINE: Danh sách trực tuyến.
  • U_CONTACT_US: Liên hệ.
  • U_TEAM: Ban quản trị.
  • U_RESTORE_PERMISSIONS: Phục hồi cấp phép (dành cho người quản trị quay về trạng thái ban đầu khi dùng thử cấp phép của người dùng khác).
  • U_ACP: Bảng quản trị.

Biến kiểm tra điều kiện
  • S_USER_LOGGED_IN: Người dùng đã đăng nhập hay chưa? (Lưu ý: Máy tìm kiếm cũng được tính là đã đăng nhập, vì thế bạn phải dùng S_REGISTERED_USER nếu muốn loại bỏ máy tìm kiếm).
  • S_AUTOLOGIN_ENABLED: Thiết lập cho phép nhớ đăng nhập có bật hay không?
  • S_BOARD_DISABLED: Hệ thống có đang bảo trì hay không?
  • S_REGISTERED_USER: Có phải là thành viên (đã đăng ký và đã đăng nhập) hay không?
  • S_IS_BOT: Có phải là máy tìm kiếm hay không?
  • S_DISPLAY_ONLINE_LIST: Thiết lập hiện danh sách trực tuyến có bật hay không?
  • S_DISPLAY_SEARCH: Thiết lập cho phép tìm kiếm có bật hay không? Người dùng có được phép tìm kiếm hay không?
  • S_DISPLAY_PM: Thiết lập cho phép nhắn tin có bật hay không? Người dùng có được phép xem và gửi tin nhắn hay không?
  • S_DISPLAY_MEMBERLIST: Người dùng có được phép xem danh sách thành viên hay không?
  • S_NEW_PM: Có tin nhắn mới hay không?
  • S_REGISTER_ENABLED: Thiết lập cho phép đăng ký có bật hay không?
  • S_ENABLE_FEEDS: Thiết lập RSS có bật hay không?
    • S_ENABLE_FEEDS_OVERALL: Có bật RSS cho bài viết mới từ tất cả chuyên mục hay không?
    • S_ENABLE_FEEDS_FORUMS: Có bật RSS cho chuyên mục hay không?
    • S_ENABLE_FEEDS_TOPICS: Có bật RSS cho chủ đề hay không?
    • S_ENABLE_FEEDS_TOPICS_ACTIVE: Có bật RSS cho chủ đề gần đây hay không?
    • S_ENABLE_FEEDS_NEWS: Có bật RSS cho chuyên mục xác định làm tin tức hay không?
  • S_LOAD_UNREADS: Thiết lập cho phép tìm bài viết chưa xem có bật hay không?
  • S_NOTIFICATIONS_DISPLAY: Thiết lập hiển thị thông báo tương tác có bật hay không?
  • S_USER_NEW_PRIVMSG: Có tin nhắn mới hay không?
  • S_USER_UNREAD_PRIVMSG: Còn tin nhắn chưa xem hay không?
  • S_USER_NEW: Người dùng vẫn còn nằm trong nhóm "Thành viên mới" hay không?
  • S_ALLOW_CDN: Thiết lập tải jQuery và phông chữ Open Sans trực tuyến từ nguồn có bật hay không?

Các biến dữ liệu khác
  • SITENAME: Tên trang web (thiết lập trong bảng quản trị).
  • SITE_DESCRIPTION: Giới thiệu trang web (thiết lập trong bảng quản trị).
  • PAGE_TITLE: Tiêu đề trang hiện tại.
  • SCRIPT_NAME: Tên tập tin PHP của trang hiện tại (đã bỏ đi phần đuôi .php).
  • PRIVATE_MESSAGE_COUNT: Số tin nhắn chưa xem.
  • CURRENT_USER_AVATAR: Hình đại diện của người dùng.
  • CURRENT_USERNAME_SIMPLE: Tên người dùng.
  • CURRENT_USERNAME_FULL: Tên người dùng với màu của nhóm chính và liên kết đến trang cá nhân.
  • UNREAD_NOTIFICATIONS_COUNT: Số thông báo tương tác chưa xem.
  • NOTIFICATIONS_COUNT: Tương tự UNREAD_NOTIFICATIONS_COUNT.
  • SESSION_ID: Mã phiên đăng nhập của người dùng.
  • DEBUG_OUTPUT: Thông tin dò lỗi (bật từ tập tin config.php).
  • TRANSLATION_INFO: Thông tin người phiên dịch từ gói ngôn ngữ đang dùng.
  • CREDIT_LINE: Dòng bản quyền của phpBB.


Tạo trang mới với các thành phần giao diện


nedka

nedka

Quản trị viên
27/08/2016 16:30

Để gán tập tin giao diện cho một tập tin mã PHP ta đang viết, ta cần đến đối tượng helper của phpBB. Hãy thêm nó vào phương thức khởi tạo __construct() cũng như khai báo trong config/services.yml.

Chép
protected $helper;

public function __construct(\phpbb\controller\helper $helper)
{
	$this->helper = $helper;
}
Chép
        arguments:
            - '@controller.helper'
Và trong phương thức hiển thị của trang tạo mới, ví dụ tên là display_page(), hãy để kết quả trả về chính là nội dung tập tin giao diện:
Chép
public function display_page($mode)
{
	// Mã xử lý trước khi xuất ra HTML...

	return $this->helper->render('abc.html', 'PAGE_ABC');
}
Trong đó, abc.html là tên tập tin giao diện của chúng ta và PAGE_ABC chính là biến ngôn ngữ tên trang.


Tạo mới biến giao diện


nedka

nedka

Quản trị viên
27/08/2016 16:31

Để xuất biến giao diện ra dùng trong mã HTML, ta cần đến đối tượng template của phpBB. Hãy chắc chắn bạn đã có nó trong phương thức khởi tạo __construct() cũng như tập tin config/services.yml.

Chép
protected $template;

public function __construct(\phpbb\template\template $template)
{
	$this->template = $template;
}
Chép
        arguments:
            - '@template'
Ta có 2 phương thức gán biến giao diện, $this->template->assign_var() cho một biến giao diện đơn và $this->template->assign_vars() cho nhiều biến giao diện cùng lúc, dạng mảng PHP. Thực tế lúc nào cũng cần nhiều biến giao diện, cho nên bạn chỉ cần luôn dùng dạng số nhiều $this->template->assign_vars() cho tiện.
Chép
$this->template->assign_vars(array(
	'VAR_1' => $abc,
	'VAR_2' => 'abc',
	'VAR_3' => 123,
));
Vậy là ta đã có thể dùng những biến giao diện này trong mã HTML:
Chép
{% if VAR_3 > 100 %}
	{{ VAR_1 }}
{% else %}
	{{ lang('ABC', VAR_2) }}
{% endif %}


Tạo danh sách dữ liệu trong giao diện


nedka

nedka

Quản trị viên
27/08/2016 16:31

Danh sách dữ liệu thật ra chính là các vòng lặp Twig trong giao diện, trả về từng dòng trong mảng PHP chứa dữ liệu.

Đầu tiên, ta cần tạo ra vòng lặp từ mã PHP. Ví dụ, hãy lấy danh sách các thành viên có trên 10 bài viết, gồm các mục tên tài khoản, hộp thư và số bài viết. Tên vòng lặp này có tên là users:

Chép
$sql = 'SELECT username, user_email, user_posts
	FROM ' . USERS_TABLE . '
	WHERE user_posts > 10
	ORDER BY user_posts DESC';
$result = $this->db->sql_query($sql);

while ($row = $this->db->sql_fetchrow($result))
{
	$this->template->assign_block_vars('users', array(
		'USERNAME' => $row['username'],
		'EMAIL' => $row['user_email'],
		'POSTS' => $row['user_posts'],
	));
}
$this->db->sql_freeresult($result);
Và hiển thị vòng lặp này trên mã HTML:
Chép
{% for row in users %}
	{{ row.USERNAME }} ({{ row.EMAIL }}) có {{ row.POSTS }} bài viết<br>
{% endfor %}
Kết quả xuất ra:
Chép
admin (admin@abc.vn) có 120 bài viết
user1 (user1@abc.vn) có 50 bài viết
user2 (user2@abc.vn) có 20 bài viết


Lập trình trong giao diện với Twig


nedka

nedka

Quản trị viên
27/08/2016 16:33

Vui lòng xem cách sử dụng Twig tại đây.


Các vấn đề với giao diện


nedka

nedka

Quản trị viên
27/08/2016 16:36

Gọi thêm tập tin CSS/JS
Bạn không thể dùng mã trực tiếp như vậy:

Chép
<link href="{{ T_THEME_PATH }}/abc.css" rel="stylesheet">
<script src="{{ T_THEME_PATH }}/abc.js"></script>
Vì nó sẽ trả về thư mục giao diện chính của phpBB, không phải vị trí cùa thư mục gói mở rộng. Thay vào đó, hãy dùng 2 câu lệnh INCLUDECSS INCLUDEJS:
Chép
<!-- INCLUDECSS @vinabb_demo/abc.css -->
<!-- INCLUDEJS @vinabb_demo/abc.js -->
Trong đó, vinabb_demo là tên định danh gói mở rộng của bạn, lúc này đã thay ký tự / như thường lệ thành _ và đặt sau dấu @. Các tập tin này vẫn nằm trong thư mục ext/vinabb/demo/styles/tên_giao_diện/theme/.

Nếu bạn đặt CSS/JS ở một thư mục khác, tức không dùng đến biến giao diện đường dẫn quy ước là T_THEME_PATH thì việc dùng mã HTML trực tiếp không vấn đề gì.


Luôn đính kèm T_ASSETS_VERSION sau đường dẫn CSS/JS
Bạn thường thấy trong giao diện prosilver mặc định, đường dẫn CSS/JS hay có dạng sau:
Chép
<link href="{T_THEME_PATH}/tweaks.css?assets_version={T_ASSETS_VERSION}" rel="stylesheet">
Và khi xuất ra trình duyệt:
Chép
<link href="./styles/prosilver/theme/tweaks.css?assets_version=17" rel="stylesheet">
Thật ra, cả 2 đường dẫn này:
Chép
./styles/prosilver/theme/tweaks.css
./styles/prosilver/theme/tweaks.css?assets_version=17
Cũng đều trỏ về tập tin styles/prosilver/theme/tweaks.css mà thôi. Tuy nhiên, khi bạn cập nhật phpBB hay một gói mở rộng, giá trị của T_ASSETS_VERSION sẽ lại tăng thêm 1, tạo ra một đường dẫn thay đổi để 'đánh lừa' trình duyệt cần lấy lại dữ liệu mới trong này chứ không dùng bộ đệm cũ.

Ta không cần thêm vào T_ASSETS_VERSION khi dùng với INCLUDECSSINCLUDEJS ở trên, vì phpBB sẽ tự làm điều này. Bạn chỉ cần thêm khi dùng mã HTML trực tiếp.


Re: Phát triển gói mở rộng: Giao diện


tct

tct

Nhóm hỗ trợ
04/02/2017 01:57

đang làm site tùy biến giao diện chút ít không biết nên edit theme hay dùng ext cho update dễ @@


tct đã viết:
28/07/2016 19:31
Nickname: TCT ( biệt danh Tũn)
Blog: http://dosx.net/
Thích mò Ubuntu, phpBB cở 2007, 08 gì đó và biết tới VinaBB
-------
Lên đây học hỏi, xin chân làm support chủ yếu hâm lại kiến thức :D

Quan điểm

  • Không đề cập chính trị, tôn giáo, nội dung đồi trụy.
  • Giữ gìn sự trong sáng của Tiếng Việt.
  • Không chia sẻ phần mềm vi phạm bản quyền.
  • Không rao vặt và không nhận đặt quảng cáo.
  • Dù trong túi hết tiền thì diễn đàn phpBB của anh cũng phải ngay ngắn.

Chuyện tình VinaBB

17/07/2004: Yêu phpBB từ phiên bản 2.0.10.
22/10/2006: Cất tiếng cười chào đời.
11/06/2007: Chính thức định cư trên Olympus, Sao Hỏa.
11/06/2009: Mất liên lạc với Trái Đất. [ Phiên bản 2007 ]
28/07/2016: Trôi dạt đến mặt trăng Rhea, Sao Thổ.
12/12/2016: Cuộc hành trình mới lại bắt đầu…

Code in Viet Nam

Cống hiến hết mình vì Tổ Quốc Việt Nam Xã Hội Chủ Nghĩa

Quản trị viên

nedka

VinaBB

NEDKA Solutions

Đơn vị chủ quản

Chúng tôi chịu trách nhiệm toàn bộ nội dung có trên VinaBB.vn trước pháp luật.