3.2.2.2.1. Cấu trúc thư mục và các tập tin cơ bản cho module.
Một module Drupal cần phải được đặt trong một thư mục cụ thể trong cài đặt Drupal và nó cần phải có một số file cơ bản để nó có thể được xác định như là một module của hệ thống Drupal.
Tạo một thư mục có tên của module cần tạo (tạm đặt là <modulename>). Thư mục đó sẽ được lưu giữ tại sites\all\modules. Trong thư mục này nhất thiết phải có hai tập tin là <modulename>.info và <modulename>.module.
Tập tin .info
Tập tin .info cung cấp các thông tin chung về module. Một số thành phần của Drupal sẽ sử dụng các thông tin trong file này cho việc quản lý module.
Nội dung của tập tin .info có dạng như sau: name = oauthfacebook
description = OAuth with Facebook.com core = 7.x
Trường name: khai báo tên của module, tên này sẽ hiển thị trong danh sách các module có ở khu vực cho người quản trị
Trường description: chứa thông tin thêm về module, mô tả chức năng, nhiệm vụ mà module sẽ thực hiện.
Name và description là hai trường bắt buộc phải có trong file .info. Trường core: Chỉ rõ module sẽ hoạt động tốt trên phiên bản nào của Drupal Ngoài ra, các module phức tạp hơn còn có thêm một số trường thông tin trong file .info như:
- php: Cho biết phiên bản tối thiểu của PHP mà module yêu cầu.
- package: nhóm các chức năng của module, nếu không khai báo
package thì module được đưa vào nhóm “other”.
- dependencies: các module phụ thuộc, cách nhau bằng khoảng
trống. Nếu module được yêu cầu chưa được bật trên hệ thống thì module này không thể bật được.
Khi có tập tin .info ta sẽ nhìn thấy tên module trong danh sách module và ta có thể kích hoạt module này.
Tập tin .module
Tập tin .module chứa các đoạn mã PHP thực hiện chức năng của module. Đây là tập tin quan trọng nhất trong một module.
Nội dung file .module bắt đầu bằng thẻ <?php, sau đó là mã nguồn. Theo quy ước của Drupal, file này sẽ không chứa dấu đóng ?>. Việc này giúp tránh in những ký tự trống trong đầu ra của mã kịch bản trong một số trường hợp.
3.2.2.2.2. Tạo chú thích trong mã nguồn
Các module đóng góp cho drupal.org tuân theo các tiêu chuẩn viết mã và tài liệu một cách chặt chẽ. Chú thích cho biết module và các khối mã hoạt động như thế nào. Drupal sử dụng chương trình phân thích tài liệu như Doxygen để trích các chú thích làm tài liệu cho người dùng.
Mở đầu các module và hàm trong đó, lập trình viên phải chú thích rõ ràng và đầy đủ chức năng của khối mã tiếp theo đó. Ví dụ, dưới đây là chú thích đầu tiên của tập tin .module :
/** * @file
* A block module that displays recent blog and forum posts.
*/
Phần này chính là tài liệu cho API, khối chú thích bắt đầu bằng /** và kết thúc với */. Tất cả các dòng nằm trong cặp dấu này đều được coi là tài liệu và sẽ không được trình biên dịch xử lý.
Định danh @file cho biết khối này sẽ chú thích cho toàn bộ file, không phải cho riêng một hàm hay biến ở trong file. Ngoài ra, còn một số định danh khác như:
Định danh @see chỉ dẫn bộ xử lý tài liệu liên kết file này đến thông tin ở các nguồn khác. Ví dụ, nguồn dẫn là một địa chỉ URL, hàm, hằng số và biến ...
Định danh @param được dùng để mô tả về các tham số mà hàm này sử dụng, bao gồm thông tin về loại dữ liệu. Khai báo theo định dạng: @param <tên_biến> <mô tả>.
Định danh @return cho biết giá trị mà hàm sẽ trả về.
Dưới đây là ví dụ về sử dụng các định danh trong viết chú thích cho module: /**
* Implements hook_help(). *
* Displays help and module information. *
* @param path
* Which path of the site we're using to display help * @param arg
* Array that holds the current path as returned from arg() function
* @return
* String containing the bookshelf. */
3.2.2.2.3. Tạo các hook Drupal
Các hook cơ bản
Drupal đã định nghĩa sẵn rất nhiều hook để làm mọi thứ, từ khai báo block mới đến thay đổi nội dung và hành vi của block đã có. Sau đây là một số hook cơ bản trong Drupal 7:
Hook_help()
Hook đầu tiên cần xây dựng là hook_help. Hook này được khuyến khích đưa vào tất cả các module đã đóng góp. Hook_help cung cấp sự trợ giúp và bổ sung thông tin về các module cho người dùng.
Ví dụ, để thực hiện hook_help() trong module shownodes, ta tạo ra một chức năng gọi là shownodes_help() trong file shownodes.module.
hook_help() nhận hai tham số:
- Tham số $path : chứa một đoạn URI cho biết trang trợ giúp nào được gọi. Giá trị của $path có thể tuân theo định dạng admin/help#<module name>, trong đó <module name> được thay bằng tên của module tương ứng .
- Tham số $arg: chứa một số thông tin thêm.
Khi đã tạo và viết mã nguồn cho hook_help(). Ta xem lại danh sách module bằng cách nhấn vào module trên thanh công cụ trong cài đặt Drupal. Kích hoạt tính năng module và nhấp vào 'Save configuration'. Đóng và mở lại trang Modules, sẽ thấy một liên kết "Help" ở bên phải. Click vào nó để xem nội dung giúp đỡ trả về bởi hook_help.
Ví dụ:
function current_posts_help($path, $arg) { switch ($path) {
case "admin/help#current_posts":
return '<p>' . t("Displays links to nodes created
on this date") . '</p>'; break;
} }
Hook_block_info()
Tất cả các block của module đều được định nghĩa trong hook này. Mỗi block phải được đặt một định danh duy nhất (ví dụ $delta) và được sử dụng trong một số trường hợp:
- Được chuyển vào hook block khác trong module như một tham số.
- Được sử dụng để xây dựng các ID HTML mặc định của block. ID này sau đó có thể được sử dụng cho CSS hoặc lập trình JavaScript.
- Được sử dụng để định nghĩa một theme mẫu - Được sử dụng bởi các module khác.
Mỗi block được định nghĩa bởi một mảng có chứa các giá trị mô tả block như: - info: Bắt buộc phải có. Chứa giá trị là tên block. Được sử dụng để xác định block trên màn hình. Không hiển thị cho người dùng không phải quản trị viên.
- region: Tùy chọn. Có giá trị là tên khu vực chứa block.
- pages: Tùy chọn. Chứa một dãy đường dẫn nơi block sẽ xuất hiện.
- cache: Tùy chọn. Chứa một bitmask mô tả những loại bộ nhớ đệm là thích hợp cho block.
- weight: Tùy chọn. Cho biết thứ tự block trong khu vực hiển thị.
Ngoài ra, block còn có thêm một số cặp giá trị khác như: properties, status... Các cặp giá trị tùy chọn sau này có thể được thay đổi bởi người có quyền.
Ví dụ:
function node_block_info() {
// This example comes from node.module. $blocks['syndicate'] = array(
'info' => t('Syndicate'), 'cache' => DRUPAL_NO_CACHE, );
$blocks['recent'] = array(
'info' => t('Recent content'),
// DRUPAL_CACHE_PER_ROLE will be assumed. );
return $blocks; }
Hook_block_view()
Những gì người dùng xem và nhìn thấy nội dung của block trên trang web có thể được viết trong hook này.
Hook này có dạng: hook_block_view($delta = ''). Tham số
$delta là định danh của block trong module, đã được định nghĩa trong
hook_block_info()
Mảng hiển thị block chứa các thành phần sau:
- Subjects: Tiêu đề mặc định cục bộ của block. Nếu block không có tiêu đề mặc định thì sẽ được thiết lập giá trị NULL.
- Content: Chứa nội dung của block. Có thể là mảng hoặc một chuỗi chứa nội dung HTML. Nếu phần này rỗng thì block sẽ không được hiển thị.
Ví dụ:
function node_block_view($delta = '') {
// This example is adapted from node.module. $block = array(); switch ($delta) { case 'syndicate': $block['subject'] = t('Syndicate'); $block['content'] = array( '#theme' => 'feed_icon', '#url' => 'rss.xml', '#title' => t('Syndicate'), ); break; case 'recent': if (user_access('access content')) {
$block['subject'] = t('Recent content'); if ($nodes =
node_get_recent(variable_get('node_recent_block_count', 10))) {
$block['content'] = array( '#theme' => 'node_recent_block', '#nodes' => $nodes, ); } else {
$block['content'] = t('No content available.'); } } break; } return $block; } Hook_menu()
Hook này dùng để định nghĩa một Menu Item hoặc một Page Callback trong module Drupal.
Hook_menu() cho phép module đăng ký một URI nhất định (hoặc một đường dẫn URL tương đối) và ánh xạ URI đó tới một hàm xử lý hoặc đăng ký một liên kết được đặt trong một Menu (thường là Menu Navigaiton)
Bản triển khai của hook_menu() trả về một mảng Menu Item. Mỗi Menu
Item có khóa tương ứng với đường dẫn Drupal đã đăng ký. Giá trị tương ứng với
mảng là một mảng kết hợp mà có thể chứa các cặp giá trị quan trọng như: title, decription, page callback, access callback...
Ví dụ:
function node_menu() {
$items['example'] = array( 'title' => 'Example Page',
'page callback' => 'example_page',
'access arguments' => array('access content'), 'type' => MENU_SUGGESTED_ITEM,
);
$items['example/feed'] = array( 'title' => 'Example RSS feed', 'page callback' => 'example_feed',
'access arguments' => array('access content'), 'type' => MENU_CALLBACK,
);
return $items; }
Hook_permission()
- Định nghĩa quyền của người dùng.
- Hook này có thể cung cấp quyền truy cập module, được sử dụng để cấp hoặc hạn chế quyền truy cập vào các hành động thực hiện trong module.
Ví dụ:
function system_permission() {
return array(
'administer my module' => array(
'title' => t('Administer my module'),
'description' => t('Perform administration tasks
for my module.'),
), ); }
Định nghĩa hook mới và cách sử dụng
Định nghĩa một hook mới để cho những người phát triển sử dụng thuận tiện hơn về sau. Có một số cách để làm cho hook mới trở nên dễ sử dụng và triển khai. Cách thứ nhất là thêm các thông tin chi tiết về hook vào trong block tài liệu của đoạn mã. Cách thứ hai là tạo ra một hàm hook trong mã nguồn, hàm này sẽ không được gọi đến mà chỉ đóng vai trò làm mẫu.
Ví dụ: /**
* Use this hook to build content for a sitenews message.
*
* This should return an array of items: * <code>array('item_name' => $item)</code>
* An item is an associative array with the following * fields set:
*
* - #weight: An integer from -10 to 10 * - #content: Text content
*
* Weight and content are required. If #title * is set, then it will be added as a title. * * @return * A content array. */ function hook_sitenews() { $content['report'] = array( '#weight' => 0,
'#title' => t('Sample Title'), '#body' => t('Sample content') );
$content['another report'] = array( '#weight' => 0,
'#title' => t('Another Sample Title'), '#body' => t('More sample content') );
return $content; }
Hàm này dùng làm mẫu để hướng dẫn người dùng sử dụng hook_sitenews(). Nó sẽ không được gọi trong mọi trường hợp, kể cả khi hệ thống nhận lời gọi hàm module_invoke() hay module_invoke_all() vì tên hàm không tuân theo quy tắc. Phần tài liệu trong khối chú thích mô tả một cách chi tiết chức năng của hook cho người phát triển. Phần mã nguồn được thiết kế để thể hiện cách tạo một bản triển khai mà người phát triển nên tuân theo.
Việc sử dụng hook tự định nghĩa vào trong module cũng giống như đối với các hook có sẵn của Drupal. Bản triển khai của một hook phải được đặt theo quy tắc và có các tham số trùng với phần khai báo của hook.
Ví dụ:
function biography_sitenews() { //code goes here
}
Các hook được định nghĩa trong một module có thể được triển khai trong module khác và module chứa khai báo hook phải được bật.