Module mẫu: MoreFieldContactPage

Submitted by thehong on Fri, 08/31/2007 - 11:58

Module mẫu hôm nay giới thiệu cách sử dụng hook_form_alter() và khóa #theme và #submit trong FormAPI.

Mục đích của module:
- (đương nhiên là làm module mẫu)
- Tạo thêm một field "Company" cho trang liên hệ (được cung cấp bởi module contact)

1. Cấu trúc tổ thức tập tin

./sites/all/modules/MoreFieldContactPage
./sites/all/modules/MoreFieldContactPage/MoreFieldContactPage.info
./sites/all/modules/MoreFieldContactPage/MoreFieldContactPage.module

2. Định nghĩa tập tin MoreFieldContactPage.info

Tập tin này sẽ định nghĩa:
- Tên trình bày của module: MoreFieldContactPage
- Nội dung mô tả: Add more fields to core contact page
- Module phụ thuộc: contact
- Phiên bản: 5.x-1.0-dev
- Nằm trong gói: ToiLa .net (giúp cho người điều hành dễ quản lý)

Nội dung cụ thể

name = MoreFieldContactPage
description = Add more fields to core contact page
dependencies = contact
version = 5.x-1.0-dev
package = ToiLa .net

3. Sử dụng hook_form_alter()

Trước khi một HTML Form được tạo ra, Drupal sẽ đi tìm tất cả các hàm có dạng {tên_module}_form_alter() để thay nổi cấu trúc mảng định nghĩa form. Ở module này của chúng ta, chúng ta sẽ định nghĩa hàm (trong tập tin MoreFieldContactPage:

<?php
function MoreFieldContactPage_form_alter($form_id, &$form) {
  print('['.$form_id.']');
}
?>

Khi bất cứ một HTML Form nào tạo ra, hàm của MoreFieldContactPage_form_alter() của chúng ta đều được gọi. Khi được gọi, hàm sẽ in ra màn hình mã số của form ($form_id)tương ứng. Đi vào trang ?q=contact, chúng ta sẽ biết được mã số của form liên hệ sẽ là contact_mail_page. Dựa vào $form_id này, chúng ta tiếp tục cải tiến hàm MoreFieldContactPage_form_alter() để khi, mỗi khi form liên hệ được tạo ra, chúng ta sẽ thêm vào một field (trường) có khóa là company, có tiêu đề là Your compapy name, có phần mô tả là This field is generated using MoreFieldContactedPage module. và nội dung không được rỗng:

<?php
function MoreFieldContactPage_form_alter($form_id, &$form) {
  if ($form_id == 'contact_mail_page') {
    $form['company'] = array(
      '#type' => 'textfield',
      '#title' => 'Your company name',
      '#description' => 'This field is generated using MoreFieldContactedPage module.',
      '#required' => true
    );
  }
}
?>

3. Sử dụng khóa #theme của FormAPI

Chúng ta có thể sử dụng khóa #theme của FormAPI để có thể thay đổi cách trình bày của HTML Form được xuất ra. Chúng ta sẽ tiếp tục cải tiến hàm MoreFieldContactPage_form_alter(), để trước khi form liên hệ được xuất ra, nó sẽ được hàm theme_ContactForm thay đổi cách trình bày ra giao diện người dùng:

<?php
function MoreFieldContactPage_form_alter($form_id, &$form) {
  if ($form_id == 'contact_mail_page') {
    $form['#theme'] = 'ContactForm';
    $form['company'] = array(
      '#type' => 'textfield',
      '#title' => 'Your company name',
      '#description' => 'This field is generated using MoreFieldContactedPage module.',
      '#required' => true
    );
  }
}
?>

Và đương nhiên, chúng ta sẽ phải định nghĩa hàm theme_ContactForm():

<?php
function theme_ContactForm($form) {
  $output = '';
  $output .= drupal_render($form['contact_information']);
  $output .= drupal_render($form['company']);
  $output .= drupal_render($form);
  return $output;
}
?>

Ý nghĩa của hàm,
- Dòng 2: chúng ta sử dụng biến $output để lưu giữ chuỗi HTML của Form liên hệ.
- Dòng 3: Bắt đầu form liên hệ sẽ là thông tin của form
- Dòng 4: Tiếp đến là field 'Your company'
- Dòng 5: Tiếp sau là các thành phần còn lại của form
- Dòng 6: Trả về chuỗi HTML của Form liên hệ.

4. Sử dụng khóa #submit của FormAPI

Khi đã thêm (các) field cần thiết vào form liên hệ, chúng ta cần thêm phải thay đổi một chút cách xử lý khi form được đệ trình (người dùng nhấp vào nút Submit).
3.1. Khai báo hàm sẽ xử lý form
Nếu hàm xử lý form không được khai báo, mặc định, FormAPI sẽ hiểu hàm {form_id}_submit() sẽ là hàm xử lý khi form được đệ trình. Chúng ta một lần nữa cải tiến hàm MoreFieldContactPage_form_alter(), định nghĩa hàm xử lý form sẽ là MoreFieldContactPage_submit():

<?php
function MoreFieldContactPage_form_alter($form_id, &$form) {
  if ($form_id == 'contact_mail_page') {
    $form['#theme'] = 'ContactForm';
    $form['company'] = array(
      '#type' => 'textfield',
      '#title' => 'Your company name',
      '#description' => 'This field is generated using MoreFieldContactedPage module.',
      '#required' => true
    );
    $form['#submit'] = array('MoreFieldContactPage_submit' => array());
  }
}
?>

Và hàm MoreFieldContactPage_submit() của chúng ta sẽ được định nghĩa đại khái như sau (chèn thêm tên công ty của người dùng vào nội dung chính của thông điệp):

<?php
function MoreFieldContactPage_submit ($form_id, $form_values) {
  $form_values['message'] = "Contact's company: ".$form['company']."\r\n\r\n"
  contact_mail_page_submit($form_id, $form_values);
}
?>

5. Tham khảo

- Module contact (trong bản phân phối chính của Drupal)
- Form API

Thế Hồng

Unsigned version