万源之源之drupal7
（注：学习交流用）
学习joomla的时候，看过一位前辈写的万源之源的帖子，让我记忆深刻，最新工作需要用到了drupal，所以把学习笔记整理出来，借用了一下“万源之源”的标题。
对于程序的认识每个人都有可能不同，特别是一套相对成熟的框架，但是不管怎么理解或者怎么解释一段程序，唯一不变的就是研究对象（代码），所以需一切从代码开始。
drupal的强大毋庸置疑，本章内容对于整个drupal仅仅是最小的一部分，由于本人也是初学，有错误的地方请大家理解，并且在您方便的时候帮忙指正一下，万分感激
<?php
//定义drupal的根目录
define('DRUPAL_ROOT', getcwd());
//引入引导文件
require_once DRUPAL_ROOT . '/includes/bootstrap.inc';
//加载drupal，在这里定义drupal全部加载。其他的方式可以具体查看这个函数的执行过程。
//这个过程就像是计算机的操作系统，如果要使用一台计算机，那么这台计算机一定要先运行
//操作系统，然后才能正常使用，我们可以选择这台计算机的启动方式
drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);
//drupal系统已经准备好了，现在开始执行网站程序。
menu_execute_active_handler();
//按照页面的执行逻辑，解释下面的参数
function menu_execute_active_handler($path = NULL, $deliver = TRUE){
// Check if site is offline.
//判断网站是否是offline
$page_callback_result = _menu_site_is_offline() ? MENU_SITE_OFFLINE : MENU_SITE_ONLINE;
// Allow other modules to change the site status but not the path because that
// would not change the global variable. hook_url_inbound_alter() can be used
// to change the path. Code later will not use the $read_only_path variable.
$read_only_path = !empty($path) ? $path : $_GET['q'];
//触发 menu_site_status_alter hook, 可以让module根据当前的路径修改网站的状态
drupal_alter('menu_site_status', $page_callback_result, $read_only_path);
/** Only continue if the site status is not set.
只有在网站正常运行的时候，才执这段代码，这段代码的左右是根据 $path(现在这里是$_GET)在数据库menu_router
表里找到路由参数，在参数中，page_callback代表可以得到本页面的主要信息内容的函数，page_arguments代表所
需要的参数。
menu_router 表的更新工作是在 menu_rebuild() 的函数执行的，这个函数只有在需要的时候执行，比如第一次网站
被访问的时候或是clearn cache的时候
在得到menu_get_item函数中， 查到相应的路由参数后，执行了
drupal_alter('menu_get_item', $router_item, $path, $original_map);
可以使module修改这个路由参数。*/
if ($page_callback_result == MENU_SITE_ONLINE) {
if ($router_item = menu_get_item($path)) {
if ($router_item['access']) {
if ($router_item['include_file']) {
require_once DRUPAL_ROOT . '/' . $router_item['include_file'];
}
$page_callback_result = call_user_func_array($router_item['page_callback'], $router_item['page_arguments']);
}
else {
$page_callback_result = MENU_ACCESS_DENIED;
}
}
else {
$page_callback_result = MENU_NOT_FOUND;
}
}
// Deliver the result of the page callback to the browser, or if requested,
// return it raw, so calling code can do more processing.
//是否返回浏览器所需要的整体HTML结构，还是仅仅返回页面的主要内容，这里要是返回给浏览器输出的
if ($deliver) {
$default_delivery_callback = (isset($router_item) && $router_item) ? $router_item['delivery_callback'] : NULL;
//这句可以理解成，drupal 交付页面
drupal_deliver_page($page_callback_result, $default_delivery_callback);
}
else {
return $page_callback_result;
}
}
/**
* Delivers a page callback result to the browser in the appropriate format.
*
* This function is most commonly called by menu_execute_active_handler(), but
* can also be called by error conditions such as drupal_not_found(),
* drupal_access_denied(), and drupal_site_offline().
*
* 这个函数的功能就是生成交付给浏览器的最终的HTML。
*
* 在这个函数中用运行了一次$router_item = menu_get_item();别担心，因为在上个函数中已经运行过
* 这个函数了，已经把所需要的路由参数放到cache中了，所以这次得到的是cache中的路由参数
*
* 在得到交付函数后，执行了
* drupal_alter('page_delivery_callback', $delivery_callback);
* 代表可以在module里改变交付函数，作用是我们可以在不改变源代码的情况下修改它。
*/
function drupal_deliver_page($page_callback_result, $default_delivery_callback = NULL){
if (!isset($default_delivery_callback) && ($router_item = menu_get_item())) {
$default_delivery_callback = $router_item['delivery_callback'];
}
$delivery_callback = !empty($default_delivery_callback) ? $default_delivery_callback : 'drupal_deliver_html_page';
// Give modules a chance to alter the delivery callback used, based on
// request-time context (e.g., HTTP request headers).
drupal_alter('page_delivery_callback', $delivery_callback);
if (function_exists($delivery_callback)) {
//这里是默认的 drupal_deliver_html_page() 函数。
$delivery_callback($page_callback_result);
}
else {
// If a delivery callback is specified, but doesn't exist as a function,
// something is wrong, but don't print anything, since it's not known
// what format the response needs to be in.
watchdog('delivery callback not found', 'callback %callback not found: %q.', array('%callback' => $delivery_callback, '%q' => $_GET['q']), WATCHDOG_ERROR);
}
}
/**
* Packages and sends the result of a page callback to the browser as HTML.
*
* 默认的交付函数，根据页面回调函数结果得到的最终的HTML。
*/
function drupal_deliver_html_page($page_callback_result){
// Emit the correct charset HTTP header, but not if the page callback
// result is NULL, since that likely indicates that it printed something
// in which case, no further headers may be sent, and not if code running
// for this page request has already set the content type header.
/**
*如果有返回结果，并且还没有 Content-Type 则添加默认的 Content-Type
*/
if (isset($page_callback_result) && is_null(drupal_get_http_header('Content-Type'))) {
drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');
}
// Send appropriate HTTP-Header for browsers and search engines.
/**
*添加页面的当前语言
*/
global $language;
drupal_add_http_header('Content-Language', $language->language);
// Menu status constants are integers; page content is a string or array.
/**
*如果没有页面的主要内容，则执行错误处理，以为每个页面都有一个主要内容，如果没有
*找到这个需要的内容，则代表页面无效。
*
*@$page_callback_result 正常情况下是一个字符串或者数组，如果是数字，则代表
*是一个错误代号，根据这个错误代码执行相应的处理方法
*/
if (is_int($page_callback_result)) {
/*。。。。。。。*/
}elseif (isset($page_callback_result)) {
// Print anything besides a menu constant, assuming it's not NULL or
// undefined.
/**
*渲染渲染整个页面。
*/
print drupal_render_page($page_callback_result);
}
// Perform end-of-request tasks.
drupal_page_footer();
}
/**
* Renders the page, including all theming.
*
* 渲染整个页面，包括所有的主题内容
*/
function drupal_render_page($page) {
//如果看了代码的引导阶段的话，你会发现很多地方用到了 drupal_static 函数，这个函数的功能可以
//理解成扩展的static 变量，他可以让其他的函数访问并修改本函数定义的静态变量，从而实现了对象
//属性的功能。
$main_content_display = &drupal_static('system_main_content_added', FALSE);
// Allow menu callbacks to return strings or arbitrary arrays to render.
// If the array returned is not of #type page directly, we need to fill
// in the page with defaults.
if (is_string($page) || (is_array($page) && (!isset($page['#type']) || ($page['#type'] != 'page')))) {
/**
* 这个函数的作用是设置页面的主要内容，经过这个函数，我们可以在以后通过
* drupal_set_page_content()//注意是不带参数的
* 得到这里设置的主要内容，但是得到以后，system_main_content_added就会自动设置等TRUE，
* 代表我们已经提取过页面的主要内容了
*/
drupal_set_page_content($page);
/**
* Retrieves the default properties for the defined element type.
* function element_info($type){...}
* 这个函数触发了 module_invoke_all('element_info') hook,并把他缓存到cache里.
*
* 这里得到page的element_info
*/
$page = element_info('page');
}
// Modules can add elements to $page as needed in hook_page_build().
/**
* 等于句代码 module_invoke_all($hook)，允许module 参与page的生成,也可以根据$page的内容定义自己的逻辑
*/
foreach (module_implements('page_build') as $module) {
$function = $module . '_page_build';
$function($page);
}
// Modules alter the $page as needed. Blocks are populated into regions like
// 'sidebar_first', 'footer', etc.
/**
*在生成$page之后，允许module修改 $page的参数(看到hook在drupal中的地位了吧，几乎所有的逻辑都是通过它实现的，
*这也是drupal的自由之处，往往自用和代码逻辑已经分布联系非常紧密，你写的代码可以让别人二次开发么？这就需要经验
*规划了)
*/
drupal_alter('page', $page);
// If no module has taken care of the main content, add it to the page now.
// This allows the site to still be usable even if no modules that
// control page regions (for example, the Block module) are enabled.
/**
*前面介绍过，如果还没有提取过页面的主要内容，我们在这里提取页面的主要内容，
*前面可以在hook里用 drupal_set_page_content() 提取页面的主要内容，如果提取了，下面将不会再一次提取。
*/
if (!$main_content_display) {
$page['content']['system_main'] = drupal_set_page_content();
}
/**
*根据$page内容渲染页面， 也就是返回$page 的 HTML。
*/
return drupal_render($page);
}
/**
*这个函数非常重要，对于刚接触drupal也比较复杂，理解这个函数要小心+细心。
*这个函数的功能是根据传过来的参数，渲染这个数组成需要的HTML。
*@$elements 是一个关联（键/值对）数组， 它记录着所有的渲染的标签（如何渲染，渲染的过程等等），我们称它为已经结构
* 化的数组树。键的名字以#开始的，代表当前的记录是$elements的一个属性，而其他的表示$elements 的子树，需要重新
* 被执行drupal_render()进行递归。
* #access 记录当前元素是否有权利能被渲染。
* #printed 表示当前元素是不是被已经渲染过。
* #cache 表示当前元素是否需要被缓存，缓存的结构是
* 1)
* '#cache'=>array(
* 'bid'=>NULL || 'your bid',
* 'cid'=>'your cid'
* );
* 2)
* '#cache'=>array(
* 'bid'=>NULL || 'your bid',
* 'key'=>array('your','key'),
* 'granularity'=> NULL || DRUPAL_CACHE_PER_ROLE || DRUPAL_CACHE_PER_USER || DRUPAL_CACHE_PER_PAGE
* );
* #markup 标记， 如果这个值存在而 #type的值不存在的话，就使 #type = 'markup'
* #defaults_loaded 表示当前元素是不是被完全的（包括所有默认的属性），如果不是执行
* $elements += element_info($elements['#type']);
* 重新加载。
* #pre_render 表示当前元素是否需要提前渲染，这里的值是用来渲染的函数，参数就是当前元素
* #children 存放当前元素被渲染后的结果
* #theme_wrappers 如果有的话，用theme(theme($theme_wrapper, $elements))重新渲染，可以在首次渲染的结果上进行二次加工
* #post_render 过滤输出内容，用来做输出前的最后工作，用来返回浏览器执行的安全内容。
* #states javascript 控制dom对象的状态，常在form控制表单是使用
* #attached 这里存储着所需要加载的javascript，css
* #prefix 和 #suffix 存放着当前元素渲染后的前缀和后缀。用来做最后的输出。
* $output = $prefix . $elements['#children'] . $suffix;
*
*/
function drupal_render(&$elements){
//......
}
/******未完待续（接下来就是theme函数）*******/