Drupal 7 开发内部培训资料, 分头诗人

ctools

模块地址: http://drupal.org/project/ctools
模块版本: Drupal 7.xDrupal 6.x
用户数: 330 066
依赖:
模块类型: 通用模块

CTools(Chaos Tools)是一系列的API和工具,可以很大程度上的方便开发。包括几个大组件:AJAX、上下文(Context)、CSS格式化与压缩、对象导出、表单工具、向导表单、临时缓存、以及插件系统等。

AJAX组件是CTools提供用来方便Drupal中Ajax操作的一系列工具,包括:

1.模式弹出窗口(Modal)

模式弹出窗口可以把页面内容以及表单通过弹出窗口显示,并且可以很方便的处理返回值。

生成链接点击弹出窗口,先包含需要文件并添加js和样式:

1
2
ctools_include('ajax');  // 使用CTools Ajax组件命令必须要包含
ctools_include('modal'); // 使用CTools Modal组件命令必须要包含

 

1
2
3
4
5
6
7
8
9
10
11
12
ctools_modal_add_js();
$sample_style = array(
  'ctools-sample-style' => array(
    'modalSize' => array(
    'type' => 'fixed',
    'width' => 500,
    'height' => 300,
    'addWidth' => 20,
    'addHeight' => 15,
  ),
);
drupal_add_js($sample_style, 'setting'); // 样式的详细定制语法见CTools模块的帮助

为需要在弹出窗口中显示内容的链接定制css,只要给链接指定类名’ctools-use-modal’即可,如果要指定样式,使用ctools-modal-ID,ID即上面定义的样式名。也可以用快捷命令:

1
2
3
4
5
// 输出的链接html
<a href="ctools_ajax_sample/nojs/animal" class="ctools-use-modal ctools-modal-ctools-sample-style">
Wizard (default modal)</a>
// 生成模式窗口的文字链接,最后一个参数指定样式名,需要加上'ctools-modal-'前缀
ctools_modal_text_button(t('Wizard (default modal)'), 'ctools_ajax_sample/nojs/animal', t('Pick an animal'),  'ctools-modal-ctools-sample-style');

如果用按钮来启动ajax模式窗口,先定义form中一个url隐藏域保存url,再定义按钮:

1
2
3
4
5
6
$form['url'] = array(
  '#type' => 'hidden',
  // 这里的类名必须是下面定义的按钮id加上-url的后缀
  '#attributes' => array('class' => array('ctools-ajax-sample-button-url')),
  '#value' => url('ctools_ajax_sample/nojs/animal'),
);

 

1
2
3
4
5
6
$form['ajax_button'] = array(
  '#type' => 'button',
  '#value' => 'My boutton',
  '#attributes' => array('class' => array('ctools-use-modal')),
  '#id' => 'ctools-ajax-sample-button',
);

在hook_menu()中定义弹出窗口的路径和回调函数,最好在路径中包含%ctools_js,这样回调函数中可以直接读取页面是否支持js。访问链接时,%ctools_js写作nojs。

1
2
3
4
5
6
7
$items['ctools_ajax_sample/%ctools_js/login'] = array(
      'title' => 'Login',
      'page callback' => 'ctools_ajax_sample_login',
      'page arguments' => array(1),
      'access callback' => TRUE,
      'type' => MENU_CALLBACK,
  );

 

弹出窗口中如果不包含form表单,在回调函数中用ctools_modal_render来输出并结束:

1
ctools_modal_render($title, $output);

如果包含form表单,需要先建立form_state数组,然后输出自定义的form或者现存form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
ctools_include('modal');
ctools_include('ajax');
// 基本的$form_state数组,可以定义其他需要使用的信息
$form_state = array(
  'title' => t('Title of my form'),
  'ajax' => $js,
);
// 包装自定义的form
$commands = ctools_modal_form_render($form_state, drupal_render($form));
print ajax_render($commands);
exit();
// 包装已有的form
$output = ctools_modal_form_wrapper('my_form', $form_state);
if ($form_state['executed'] && $js) { // 可以用from_state检测表单提交状态
  $commands = array();
  $commands[] = ctools_modal_command_dismiss(t('Login Success'));
  print ajax_render($commands);
  exit;
}

还可以使用ajax命令作为链接回调函数的输出,这点用法是和标准一致的:

1
2
3
4
$commands = array();
$commands[] = ajax_command_html('#ctools-sample', $output);
print ajax_render($commands);
exit;

2.下拉链接菜单(Drop Down Menu)

下拉链接菜单是一个CTools Ajax组件,通过下拉选项的方式来显示链接,使用方法很简单,先定义一组链接数组,然后调用theme_ctools_dropdown()输出可以了:

1
return theme('ctools_dropdown', array('title' => t('Click to Drop Down'), 'links' => $links));

3.可折叠Div

可折叠Div有点像Drupal 6.x以前的fieldset,即可以控制下面的某段内容显示或者折叠,也只需要通过theme输出就可以了:

1
2
$handle = t('Click to Collapse');
return theme('ctools_collapsible', array('handle' => $handle, 'content' => $content, 'collapsed' => FALSE));

4.跳转菜单

跳转菜单扩充了select选择框的功能,只要选择某项即可跳转到对应链接,只需要用ctools_jump_menu()函数来生成表单:

1
2
3
4
$form_state = array();
// 第三个参数几选择框选项,键为链接,值为文字
$form = ctools_jump_menu(array(), $form_state, array($url => t('Jump!')), array());
return $form;

5.级联选择(dependent)

级联选择是很常见的一种表单形式,也就是当某个可选表单元素,如选择框、复选框、单选框中的某项被选中后,会自动显示相关联的隐藏表单。CTools提供了简单的实现方式。

先包含dependecnt组件,然后再被关联的隐藏表单上设置依赖关系:

1
ctools_include('dependent');

 

1
2
3
4
5
6
7
$form['menu']['title'] = array(
*    '#title' => t('Title'),
*    '#type' => 'textfield',
*    '#default_value' => '',
*    '#description' => t('If set to normal or tab, enter the text to use for the menu item.'),
*    '#dependency' => array('radio:menu[type]' => array('normal', 'tab', 'default tab')),
*   );

#dependency项设置了依赖关系,这里的意思是,如果名为menu-type的单选框被选中,且选择的值为‘normal’、’tab’或者’default’的时候,这个文本框就会显示出来供输入数据。

‘radio:menu[type]‘是对于单选框的特殊格式,如果是选择框或者复选框,只要填上id就可以了。

如果被关联的隐藏表单是单选框或者复选框,需要用#prefix和#suffix属性加上两层div。因为表单并不自带div容器。