====== Lập trình Modules cho NukeViet 4.x ====== ===== Tổng quan về Module của NukeViet ===== Các module của NukeViet được đặt trong thư mục ''modules/''. Tên mỗi module bao gồm chữ cái, chữ số và dấu gạch ngang. Cấu trúc cơ bản của một module bao gồm các file và thư mục: * admin * admin/main.php * admin.functions.php * admin.menu.php * action_mysql.php * action_oci.php * blocks * funcs * funcs/main.php * funcs/rss.php * funcs/search.php * comment.php * notification.php * functions.php * global.functions.php * language * language/admin_ngonngu.php (ví dụ ngôn ngữ tiếng viêt : admin_vi.php) * langguage/ngonngu.php (ví dụ ngôn ngữ tiếng viêt : vi.php) * menu.php * rssdata.php * search.php * siteinfo.php * theme.php * version.php Chức năng của các file như sau: * File version.php: file này có chức năng khai báo tiêu đề module, các funcs có block, tác giả module, thông tin phiên bản, cấu trúc thư mục trong thư mục uploads. * File admin.functions.php: File này thường chứa các function, hằng dùng trong admin * File admin.menu.php: File này thường chứa biến submenu của module và allow_func của module * File function.php: File này thường chứa các function, hằng dùng cho ngoài site * File global.function.php: File này thường chứa các function, hằng dùng cho ngoài site * Admin/main.php: File này sẽ thể hiện nội dung của module phần admin * Funcs/main.php: FIle này sẽ thể hiện nội dung (trang chính) của module bên ngoài site. * File action_mysql.php chứa các lệnh cài đặt CSDL ban đầu cho module. Áp dụng cho CSDL là mysql * File action_oci.php chứa các lệnh cài đặt CSDL ban đầu cho module. Áp dụng cho các CSDL khác * File theme.php chứa các hàm xử lý giao diện của khu vực ngoài site * File siteinfo.php chứa thông tin module trong admin * File comment.php file này không bắt buộc có, nếu có nó dùng để cập nhật lại số comment của đối tượng được bình luận khi module có dùng chức năng bình luận của hệ thống. * File notification.php file này không bắt buộc có, nếu có nó dùng để xác định tiêu đề và đường dẫn liên kết của chức năng thông báo trong admin. Thứ tự khởi động một module như sau: Khi module được chạy thì tùy theo admin hay ngoài site mà file ''admin.functions.php'' hay ''file function.php'' được chạy trước sau đó là các file trong thư mục admin hay funcs được chạy tiếp theo mặc định sẽ là ''file main.php''. Ta thường thấy url trang web nukeviet (chưa bật rewrite) có dạng http://yourdomain/index.php?lang=vi&nv=qlhs&op=main Trong đó ''lang'' chính là ngôn ngữ của site, ''nv'' là module đang chạy, ''op'' chính là funcs đang chạy (ở đây là main). Giá trị ''op'' này chính là tên của funcs trong thư mục funcs hay admin. Nếu trên url mà khuyết phần ''op='' có nghĩa funcs ''main.php'' đang được chạy. ===== Danh sách các Biến hằng số trong module ===== * NV_ADMIN : trạng thái admin đăng nhập * NV_MAINFILE : khai báo file module là file của hệ thống Nukeviet * NV_SYSTEM : file của hệ thống * NV_IS_FILE_MODULES : file của module * NV_START_TIME: Thời gian bắt đầu phiên làm việc. * NV_ROOTDIR: Thư mục gốc website ví dụ: D:/Web/www/nukeviet * NV_IS_USER_FORUM: Có giá trị true nếu site có tích hợp diễn đàn. * NV_IS_USERS: Có phải là thành viên không. * NV_IS_SPADMIN: Có phải là admin tối cao hoặc người điều hành chung không. * NV_IS_GODADMIN: Có phải là admin tối cao không. * NV_ALLOW_FILES_TYPE: Các kiểu file được tải lên. * NV_ALLOW_UPLOAD_FILES: Cho phép tải file lên. * NV_LANG_DATA: Ngôn ngữ data. * NV_LANG_INTERFACE: Ngôn ngữ giao diện. * [[programming4:other_constants|Xem Thêm]] ===== Quy tắc đặt tên phiên bản module ===== Quy tắc đặt tên phiên bản module tương tự quy tắc đặt tên phiên bản chính của NukeViet (nhưng không liên quan đến phiên bản NukeViet đang có). Theo quy tắc này, phiên bản của module có dạng: X.Y.ZZ Trong đó: * X: Chuỗi phiên bản chính, 1 chữ số; sẽ tăng khi có sự thay đổi lớn trong module mà theo đó hệ thống mới có thể khác 1 phần hay hoàn toàn hệ thống cũ. * Y: Chuỗi phiên bản phụ, 1 chữ số; sẽ tăng khi có sự thay đổi module mà không làm mất tính tương thích trong cùng phiên bản chính. * ZZ: Chuỗi phiên bản cấu tạo. Đánh dấu sự khác nhau trong cùng 1 phiên bản của module, 2 chữ số; sẽ tăng khi có đóng gói nhằm các mục đích phát hành, thử nghiệm... Ví dụ: ^ Sai quy tắc ^ => ^ Đúng quy tắc ^ | 1.0.1 | => | 1.0.01 | | 1.0 | => | 1.0.00 hoặc 0.1.00 | | 1 | => | 1.0.00 hoặc 0.1.00 hoặc 0.0.01 | ===== Viết module đơn giản ===== Để viết một module đơn giản việc đầu tiên là tạo thư mục trong thư mục modules/ sau đó tiếp tục tạo các file và thư mục bên trong như sau: * admin.functions.php * admin.menu.php * version.php * funcs * funcs/main.php * admin * admin/main.php * functions.php ==== version.php ==== 'QLHS', // Tieu de module 'modfuncs' => 'main,viewcat,topic,groups,detail,search,content,tag,rss', // Cac function co block 'change_alias' => 'topic,groups,content,rss', 'submenu' => 'content,rss,search', 'is_sysmod' => 0, // 1:0 => Co phai la module he thong hay khong 'virtual' => 1, // 1:0 => Co cho phep ao hao module hay khong 'version' => '4.0.00', // Phien ban cua modle 'date' => 'Wed, 8 Oct 2014 00:00:00 GMT', // Ngay phat hanh phien ban 'author' => 'Webvang.vn (hoang.nguyen@webvang.vn)', // Tac gia 'note' => '', // Ghi chu 'uploads_dir' => array( $module_name, $module_name . '/source', $module_name . '/temp_pic', $module_name . '/topics' ), 'files_dir' => array($module_name . '/topics') ); Trong đó: * Name: Tiêu đề của module. * Modfuncs: Các funcs được sử dụng * is_sysmod: Có phải module hệ thống hay không. * Virtual: Cho phép ảo hóa hay không. * Version: Phiên bản của module. * Date: Ngày xuất bản module. * Author: Tác giả module. * uploads_dir: Các thư mục tải lên của module. ==== admin.functions.php ==== Trong đó cần chú ý đến : define('NV_IS_QLHS_ADMIN', true) : Khai báo biến hằng xác nhận file func của module trong admin. ==== admin.menu.php ==== $submenu : là danh sách các menu con của module $allow_func : xác nhận các file func của module được phép hoạt động ==== functions.php ==== File này thường chứa các hàm sử dụng bên ngoài site, nếu module không có dùng các hàm, có thể để trống file này (như trên), tuy nhiên không được xóa nó. Thư mục language chứa các file ngôn ngữ. Các file ngôn ngữ trong admin có dạng admin_ngon-ngu.php, các file ngôn ngữ ngoài site có dạng ngon-ngu.php. ==== Cấu trúc cơ bản của file ngôn ngữ: ==== === admin_ngon-ngu.php === === ngon-ngu.php === Biến ''$lang_module'' là biến lưu ngôn ngữ của module. Thư mục js gồm hai file user.js và admin.js. File user.js chứa các câu lệnh javascript (nếu có) ngoài site, admin.js chứa javascript (nếu có) trong admin. ==== main.php ==== Lưu ý: Để xuất nội dung của module và kết thúc ta thực hiện thao tác: * Đối với admin: include (NV_ROOTDIR . "/includes/header.php"); echo nv_admin_theme($contents); include (NV_ROOTDIR . "/includes/footer.php"); biến $contents là toàn bộ nội dung hiển thị của module. * Đối với khu vực site: include (NV_ROOTDIR . "/includes/header.php"); echo nv_site_theme($contents); include (NV_ROOTDIR . "/includes/footer.php"); biến ''$contents'' là toàn bộ nội dung hiển thị của module. ===== Viết module nâng cao ===== * Để hợp chuẩn với hệ thống, một module cần phải đảm bảo các yêu cầu sau: * Sử dụng Xtemplate, điều này đồng nghĩa với việc tách biệt hoàn toàn giữa PHP và HTML, các file PHP không được chứa mã HTML. * Các funcs ngoài site cần chuyển toàn bộ các đoạn mã xử lý việc hiển thị nội dung module vào một function trong file theme.php trong thư mục chứa module (ngang hàng với file version.php), điều này sẽ giúp cho việc thay đổi cấu trúc giao diện cho mỗi theme một cách dễ dàng. ==== Tạo CSDL ban đầu của module ==== thêm file action_mysql.php ngang hàng với file version.php của module Cần chú ý đến biến ''$sql_drop_module'' và ''$sql_create_module''. Biến ''$sql_drop_module'' sẽ được dùng khi xóa một module và biến ''$sql_create_module'' sẽ được dùng khi cài lại module và thiết lập module mới. Lưu ý : trong file action_mysql.php, khi thiết kế CSDL tránh các khóa này của mysql: add, all, alter, analyze, and, as, asc, before, between, bigint, binary, both, by, call, cascade, case, change, char, character, check, collate, column, comment, condition, constraint, continue, convert, create, cross, current_user, cursor, database, databases, date, day_hour, day_minute, day_second, dec, decimal, declare, default, delayed, delete, desc, describe, distinct, distinctrow, drop, dual, else, elseif, enclosed, escaped, exists, exit, explain, false, fetch, file, float4, float8, for, force, foreign, from, fulltext, get, grant, group, having, high_priority, hour_minute, hour_second, identified, if, ignore, ignore_server_ids, in, index, infile, inner, insert, int1, int2, int3, int4, int8, integer, interval, into, is, iterate, join, key, keys, kill, leading, leave, left, level, like, limit, lines, load, lock, long, loop, low_priority, master_bind, master_heartbeat_period, master_ssl_verify_server_cert, match, middleint, minute_second, mod, mode, modify, natural, no_write_to_binlog, not, null, number, numeric, on, optimize, option, optionally, or, order, outer, outfile, partition, precision, primary, privileges, procedure, public, purge, read, real, references, release, rename, repeat, replace, require, resignal, restrict, return, revoke, right, rlike, rows, schema, schemas, select, separator, session, set, share, show, signal, spatial, sql_after_gtids, sql_before_gtids, sql_big_result, sql_calc_found_rows, sql_small_result, sqlstate, ssl, start, starting, straight_join, table, terminated, then, to, trailing, trigger, true, undo, union, unique, unlock, unsigned, update, usage, use, user, using, values, varcharacter, varying, view, when, where, while, with, write, year_month, zerofill ==== Giao diện trong Admin ==== Để tách html và php ra thì cần khai báo file html (*.tpl) trong thư mục themes/' . $global_config['module_theme'] . '/modules/' . $module_file vd: func admin/main.php assign('LANG', $lang_module); $xtpl->assign('GLANG', $lang_global); $xtpl->parse('main'); $contents = $xtpl->text('main'); include (NV_ROOTDIR . "/includes/header.php"); echo nv_admin_theme($contents); include (NV_ROOTDIR . "/includes/footer.php"); * NV_ROOTDIR: thư mục gốc chứa mã nguồn nukeviet * $global_config['module_theme']: giao diện của admin đang sử dụng * $module_file: tên module * $xtpl: [[programming:class#xtpl| xem chi tiết biến giao diện Nukeviet]] Trong file func sử dụng file main.tpl, để sử dụng template này thì trong thư mục themes/' . $global_config['module_theme'] . '/modules/' . $module_file tạo file main.tpl ==== Giao diện đối với khu vực ngoài site ==== Để tách html và php ra thì cần khai báo file html (*.tpl) trong thư mục themes/' . $global_config['module_theme'] . '/modules/' . $module_file vd: func func/main.php * NV_ROOTDIR: thư mục gốc chứa mã nguồn nukeviet * nv_page_main_list(): Hàm giao diện do người dùng định nghĩa trong file theme.php( nằm cùng cấp với version.php) assign('LANG', $lang_module); $xtpl->assign('GLANG', $lang_global); $xtpl->parse('main'); return $xtpl->text('main'); } * NV_ROOTDIR: thư mục gốc chứa mã nguồn nukeviet * nv_page_main_list(): Hàm giao diện do người dùng định nghĩa trong file theme.php( nằm cùng cấp với version.php) * $array_data1, $array_data2, ... là các tham số truyền vào function php để xử lý giao diện. * $module_info['template']: tên giao diện module sử dụng ngoài site * $module_file: Tên module * $xtpl: biến class xử lý giao diện * $xtpl->assign( 'LANG', $lang_module ): gán giá trị biến php vào biến giao diện, để sử dụng trong file template *.tpl * return $xtpl->text( 'main' ): Trả kết quả về cho biến đã gọi ngoài function, trong ví dụ này là trả về $contents trong file func/main.php Trong file func sử dụng file main.tpl, để sử dụng template này thì trong thư mục themes/' . $template . '/modules/' . $module_file tạo file main.tpl ==== Nếu module có chức năng RSS ==== Xem [[programming4:module:rss|Hướng dẫn chức năng RSS của module]] ==== Nếu module có chức năng tìm kiếm ==== * Thêm file ''search.php'' vào thư mục funcs. File này được viết tương tự các funcs khác. * Thêm file search.php vào thư mục gốc của module. File này sẽ được gọi ra khi module search làm việc. Cần xử lý để file này trả về một mảng: $result_array[] = array( // 'link' => $link, // 'title' => BoldKeywordInStr($tilte, $key, $logic), // 'content' => BoldKeywordInStr($content, $key, $logic) // ); Là các kết quả tìm kiếm. Cần chú ý biến ''$module_info'' trong file này không được sử dụng, thay vào đó cần dùng biến ''$m_values''. ==== Để hiển thị thông tin về module ==== Để hiển thị thông tin về module ngay tại khu vực quản trị website, thêm file siteinfo.php vào thư mục gốc của module. Để lấy ngôn ngữ admin của module: $lang_siteinfo = nv_get_lang_module($mod); Cần đảm bảo file này xuất ra biến ''$siteinfo''. Ví dụ: $siteinfo[] = array('key' => $lang_siteinfo['siteinfo_expired'], 'value' => $number); ==== Xuất thông tin cho module menu ==== Xem [[programming4:module:menu|Hướng dẫn xuất thông tin cho module menu]] ==== Module hỗ trợ notification ==== Xem [[programming4:module:notification|Hướng dẫn notification cho module]] ==== Module hỗ trợ sitemap ==== Xem [[programming4:module:sitemap|Hướng dẫn tạo sitemap cho module]] ==== Có kết nối với chức năng comment của hệ thống ==== Xem [[programming4:module:comment|Hướng dẫn lập trình chức năng comment của hệ thống cho module]] ===== Các chức năng cần có, cách lập trình và kiểm tra của 1 function hiển thị trong module ===== Xem [[programming4:module:funcs-required|Các chức năng cần có, cách lập trình và kiểm tra của 1 function hiển thị trong module]] ===== Lấy giá trị của biến khi submit form ===== * [[programming4:module:submit_form_nukeviet| Xem chi tiết]] ===== Gán giá trị php vào template ===== ====Trường hợp biến php là 1 giá trị cụ thể. ==== $lang_global = 'hoang.nguyen@webvang.vn'; $xtpl->assign('GLANG', $lang_global); vd : này là gán biến $lang_global của php vào template (*.tpl), trong file tpl muốn in giá trị biến $lang_global ta chỉ cần gọi {GLANG} ====Trường hợp biến php là 1 giá trị mảng. ==== $lang_global = array(); $lang_global['main'] = 'trang chính'; $lang_global['submain'] = 'trang phụ'; $xtpl->assign('GLANG', $lang_global); Ví dụ này là gán biến $lang_global của php vào template (*.tpl), trong file tpl muốn in giá trị mãng con(main) trong biến mảng $lang_global ta chỉ cần gọi {GLANG.main} ===== Hướng dẫn đổi tên module NukeViet 4 ===== Hướng dẫn đổi tên module NukeViet 4, Hướng dẫn thêm chức năng trong quản trị và ngoài site cho module Xem chi tiết tại: https://www.youtube.com/watch?v=f2IScB_nEH0 ===== Xem thêm ===== * [[nukeviet4:concepts:module|Khái niệm module trong hệ thống NukeViet]] * [[nukeviet4:admin:modules|Quản lý modules]]