how to write a drupal module

一个module的基本构成：
一个module_name的文件夹，一个module_name.info，一个module_name.module

我的开发环境是lamp，所以drupal文件夹是在/var/www/drupal下，也就是说，需要root权限才能修改这个文件夹下的内容。如果在这个目录下直接进行开发，每次都要root权限是相当不实际的……
书上给的方法是（使用连接～linux下的连接和win下的连接是完全不同的两个概念哦。）
如：ln -s /home/mbutcher/modules/modules_name  /var/www/drupal/sites/all/modules/modules_name


1)，module_name文件夹的目录是：drupal/sites/all/module/

2)，module_name.info文件（a php ini file）
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
;$Id$
name = "module_name"
description = "XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
core = 6.x
php = 5.1
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第一行的;$Id$，按照书中的说法是it is a placeholder for Drupal's CVS server.
CVS ＝ Concurrent Version System
drupal运行的时候会把这个Id替换成相应的值。总之，这是给drupal自己看的，无视它的存在吧

3)，module_name.module（标准的php文件）
===================================================================================
<?php
// $Id$
/**
* @file
* Module for fetching data from Goodreads.com.
* This module provides block content retrieved from a
* Goodreads.com bookshelf.
* @see http://www.goodreads.com
*/
===================================================================================

注意：有 <?php  开头 但是不能有 end ?>

@file 
The @file identifier tells the documentation processor that this comment describes the entire file, not a particular function or variable inside the file. The first comment in every Drupal PHP file
should, by convention, be a file-level comment.
@see keyword
This instructs the documentation processor to attempt to link this file to some other piece of information. In this case, that piece of information is a URL.


接着，就是开始编写你的模块的真正内容啦。

1）首先，你要确定你要编写的module是要做什么的，它要调用的hook(钩子)是什么。
这是小菜的初步理解，可能意思有点偏了。
比如，你要创建弄一个新的block来显示一些最新的消息，什么的，那么，你就需要一个hook_block的钩子。
在一个模块中调用钩子的方法是：modulename_hookname();
比如我要在一个叫goodreads的模块中调用block的钩子，那就是:
function goodreads_block($op='list' , $delta=0, $edit=array())
里面的参数的为什么要这样赋值小菜现在还不知道。先这样吧。
$op :可以有4个取值，
list(passed when the module should provide information about itself. For example   administration screen, the $op parameter is set to list.
view: provide content for displaying to the user.
configure: when configure the block
save: This value is passed when configuration information from the form

$delta: contains extra information about what content should be displayed.(当$op被设置为view时，这个值会被调用，也就是说，这个$delta是用在display的时候的。）

$edit: configuration 的时候会用到

2）解释了这么多，开始写代码吧。
接着刚才的module_name.module文件继续写
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
/**
* Implementation of hook_block()
*/
function goodreads_block($op='list', $delta=0, $edit=array()) {
switch ($op) {
case 'list':
$blocks[0]['info'] = t('Goodreads Bookshelf');
return $blocks;
case 'view':
$blocks['subject'] = t('On the Bookshelf');
$blocks['content'] = t('Temporary content');
return $blocks;
}
}
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

＊关于t('XXXXX');我觉得可以把它的把它当printf()看，或者说，其实它返回的就是一个字符串拉。
t()除了上面那种简单的用法以外，还可以这样用，如下：
1），t('Trying to access !url.', array('!url'=>'http://example.com'));
输出结果：Trying to access http://example.com.
2），t('Italics tag: @tag', array( '@tag', '<i>'))
输出结果： 'Italics tag: &lt;i&gt;'
3），t('Replacing %value.', array('%value=>'test')
输出结果：'Replacing <em>test</em>'
（这里题外话地说一下em与strong的区别，前者用于强调文本的意思，而后者着强调让人注意，它强调的不是strong标签里的文字内容，而是强调这一点，让人一目了然。orz……还是没明白的话，看看这篇文章吧，http://hi.baidu.com/disweb/blog/item/9d02bf5d62118b44fbf2c03f.html）
这里还要说明一点，如果t()中引用的值来自用户，最好用＠或％的形式，从安全角度来说。

3）好了，写了这么多，不想看看成果吗？
保存所有修改过的文件。到site building里面启动模块吧。
启动完模块后，再从site building->block中，就能看到你的模块啦。在disabled里面找到你写的新模块，把region的值从none改成你喜欢的，比如我选择了right sidebar。记得保存设置哦。接着，就可以在右边看到你的新模块了。

4）不过这样一个静态的模块太没有挑战性了，我们来继续修改一下这个模块，让它能够动态显示一些信息吧。我们要在模块上显示更多的信息，因此，要修改的是view的部分：
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
case 'view':
$blocks['subject'] = t('On the Bookshelf');
$blocks['content'] = t('Temporary content');
return $blocks;
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
我们需要让这个模块能够动态地显示点信息，所以，要修改的是
$blocks['content'] = t('Temporary content');这句
内容修改如下
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
case 'view':
$url = 'http://www.goodreads.com/review/list_rss/'
.'398385'
.'?shelf='
.'history-of-philosophy';
$blocks['subject'] = t('On the Bookshelf');
$blocks['content'] = _goodreads_fetch_bookshelf($url);
return $blocks;
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

5）动手开始写_goodreads_fetch_bookshelf()这个function吧。
还是<module_name>.module文件
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
function _goodreads_fetch_bookshelf($url, $number=3)
{
//其实，这里面的代码要怎么写，就看你的需要了。这已经不是drupal的问题了，而是一个单纯的动态页面开发了。记得return $out就对了。 $out吗？字符窜就对了，不管你是调用了数据库，还是其他应用。把结果输出就对了
}
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

6），最后，书里告诉我们，要养成良好的习惯，写一个hock_help()，以便别人在使用你写的模块的时候，能够通过Adminstrator｜help找到一些关于模块的帮助信息。
还是<module_name>.module文件
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
function goodreads_help($section)
{
if($section == 'admin/help')
return 'The description of your module help info.';
}
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝或者＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝ function good_help($path, $arg){ if($path == 'admin/help#good'){ //同上 } }