CTools API

2 篇文章 / 0 new
最新文章
author
CTools API
CTools(Chaos Tools)是一系列的API和工具,可以很大程度上的方便開發。包括幾個大組件:AJAX、上下文(Context)、CSS格式化與壓縮、物件導出、表單工具、導覽表單、臨時緩存、以及插件系統等。

AJAX元件是CTools提供用來方便Drupal中Ajax操作的一系列工具,包括:
1.模式彈出視窗(Modal)
模式彈出視窗可以把頁面內容以及表單通過彈出視窗顯示,並且可以很方便的處理返回值。生成鏈結點擊彈出視窗,先包含需要檔並添加js和樣式:
ctools_include('ajax');  // 使用 CTools Ajax 組件須引入
ctools_include('modal'); // 使用 CTools Modal 組件須引入
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即上面定義的樣式名。也可以用快捷命令:
// 輸出的鏈結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,再定義按鈕:
$form['url'] = array(
  '#type' => 'hidden',
  // 這裏的類名必須是下面定義的按鈕id加上-url的尾碼
  '#attributes' => array('class' => array('ctools-ajax-sample-button-url')),
  '#value' => url('ctools_ajax_sample/nojs/animal'),
);
$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。
$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來輸出並結束

ctools_modal_render($title, $output);
如果包含form表單,需要先建立form_state陣列,然後輸出自定義的form或者現存form:
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命令作為鏈結回調函數的輸出,這點用法是和標準一致的:
$commands = array();
$commands[] = ajax_command_html('#ctools-sample', $output);
print ajax_render($commands);
exit;
2.下拉鏈結功能表(Drop Down Menu)
下拉鏈結功能表是一個CTools Ajax元件,通過下拉選項的方式來顯示鏈結,使用方法很簡單,先定義一組鏈結陣列,然後調用theme_ctools_dropdown()輸出可以了:
return theme('ctools_dropdown', array('title' => t('Click to Drop Down'), 'links' => $links));
3.可折疊Div
可折疊Div有點像Drupal 6.x以前的fieldset,即可以控制下面的某段內容顯示或者折疊,也只需要通過theme輸出就可以了:
$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元件,然後再被關聯的隱藏表單上設置依賴關係:
ctools_include('dependent');
$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容器。
 
from http://www.drupalla.com/project/ctools
author
Form wizard tool - $form_info array
$form_info = array(
    'id' => 'delegator_page',
    'path' => "my/$page_name/from/%step",
    'show trail' => TRUE,
    'show back' => TRUE,
    'show return' => FALSE,
    'next callback' => 'delegator_page_add_subtask_next',
    'finish callback' => 'delegator_page_add_subtask_finish',
    'return callback' => 'delegator_page_add_subtask_finish',
    'cancel callback' => 'delegator_page_add_subtask_cancel',
    'order' => array(
      'start' => t('Basic settings'),
      'second' => t('Argument settings'),
      'third' => t('Access control'),
      'fourth' => t('Menu settings'),
      'fiveth' => t('Task handlers'),
    ),
    'forms' => array(
      'start' => array(
        'form id' => 'delegator_page_form_basic'
      ),
      'second' => array(
        'form id' => 'delegator_page_form_access'
      ),
      'third' => array(
        'form id' => 'delegator_page_form_menu'
      ),
      'fourth' => array(
        'form id' => 'delegator_page_form_argument'
      ),
      'fiveth' => array(
        'form id' => 'delegator_page_argument_form_multiple'
      ),
    ),
  );

$form_info 相關參數:

id
An id for wizard. This is used like a hook to automatically name callbacks, as well as a form step's form building function. It is also used in trail theming.
path
The path to use when redirecting between forms. %step will be replaced with the key for the form.
return path
When a form is complete, this is the path to go to. This is required if the 'return' button is shown and not using AJAX. It is also used for the 'Finish' button. If it is not present and needed, the cancel path will also be checked.
cancel path
When a form is canceled, this is the path to go to. This is required if the 'cancel' is shown and not using AJAX.
show trail
顯示 from 進行程序(如同 breadcrumb). Defaults to FALSE.
show back
顯示 back button 按紐. Defaults to FALSE.
show return
顯示 return 按紐. Defaults to FALSE.
show cancel
顯示 cancel 按紐. Defaults to FALSE.
back text
'back' 按鈕文字. Defaults to t('Back').
next text
'next' 按鈕文字. Defaults to t('Continue').
return text
'return' 按鈕文字. Defaults to t('Update and return').
finish text
'finish' 按鈕文字. Defaults to t('Finish').
cancel text
'cancel' 按鈕文字. Defaults to t('Cancel').
ajax
Turn on AJAX capabilities, using CTools' ajax.inc. Defaults to FALSE.
modal
Put the wizard in the modal tool. The modal must already be open and called from an ajax button for this to work, which is easily accomplished using functions provided by the modal tool.
ajax render
A callback to display the rendered form via ajax. This is not required if using the modal tool, but is required otherwise since ajax by itself does not know how to render the results. Params: &$form_state, $output.
finish callback
指定 callback function 名稱, form 程序完成或按下 finish 按鈕時被呼叫. Params: &$form_state.
Defaults to $form_info['id']._finish if function exists.
cancel callback
指定 callback function 名稱,按下 cancel 按鈕時被呼叫. 使用時應在此階段發生時一併清除cache 資料一並清除. Params: &$form_state.
Defaults to $form_info['id']._cancel if function exists.
return callback
指定 callback function 名稱,按下 return 按鈕時被呼叫. 通常與 finish callback 相同, 兩者僅使用 finish callback. 此callback主要目的待釐清? Params: &$form_state.
Defaults to $form_info['id']._return if function exists.
next callback
指定 callback function 名稱,按下 next 按鈕時被呼叫. 主要用來處理與暫存使用者階段輸入的資料. Params: &$form_state.
Defaults to $form_info['id']._next if function exists.
order
An optional array of forms, 若設置則 form 呈現步驟會依 order 所指定的 key name 順序進行(key name須為forms.form id), 若沒指定則會依 forms 內的 form id 項目順序進行, Note that submit callbacks can override the order so that branching logic can be used.
forms
為一個 arrays, 若 order 沒設定則 array 順序為預設的進行步驟, 每一個array資料包含下參數:
form id
必要參數, 指定該步驟要載入的 function 名稱. Defaults to $form_info['id']._.$step._form.
include
The name of a file to include which contains the code for this form. This makes it easy to include the form wizard in another file or set of files. This must be the full path of the file, so be sure to use drupal_get_path() when setting this. This can also be an array of files if multiple files need to be included.
title
Modal form 模式下指定視窗標題文字. 注意使用時必須沒有設定 $form_state['title'] 否則將顯示 $form_state['title'].
發表回應前,請先登入
Free Web Hosting