首页 » 站点定制与外观主题 » 外观主题开发指南 » 如何升级你的主题

从4.7.x升级到5.x

相关的Drupal 5.0 API 变化

下面列出的是Drupal 5.0中与外观主题有关的API接口变化，如果你的主题中用到了下面的函数，都要进行相应的更新才能在5.0下正常工作：

  1. $primary_links 与 $secondary_links 变量结构改变
  2. 新增 drupal_add_css() 函数添加CSS文件
  3. 新的 $feed_icon 显示聚合图标
  4. 新的clearing类
  5. theme_links() 改为返回链接列表
  6. 新增 drupal_add_js() 函数添加javascript脚本
  7. _phptemplate_callback signature change

4.7.x

<?php
print '<ul>';
foreach ($primary_links as $link) {
   print '<li>'. $link .'</li>';
}
print '</ul>';
?>

在5.x中如果还使用上面的代码，就会显示出"Array"字样，而不是实际的链接。

5.x 中改用theme_links() 函数

<?php
print theme('links', $primary_links);
?>

theme_links() 返回的就是link列表，每个link array的key都是"模块名-链接名"的形式：比如 menu-1-3-4 或者 node-read-more 或者 comment-add-new。

关于theme_links的更多信息，请参见相关的4.7到5.0模块升级手册。

2. 使用 drupal_add_css() 添加CSS文件

在4.7.x里，需要使用类似下面的代码来添加自定义的CSS文件：

<?php
theme('stylesheet_import', base_path() . path_to_theme() . '/extra_stylesheet.css') or theme_add_style($themes[$theme]->filename);
?>

在5.x里，改为了：

<?php
drupal_add_css($path = NULL, $type = 'module', $media = 'all');
?>

这样添加CSS文件变得更加容易，而且可以控制CSS文件的先后顺序（例如Drupal内核CSS，然后是扩展模块的CSS，然后是外观主题的CSS)。

此外在phpTemplate中新增了一个 $css 变量，包含当前页面所有的CSS文件。原来的变量 $styles 还是包含加载CSS文件所必需的实际HTML代码，而新的 $css 变量的引入使你可以在theme里非常方便地替换CSS文件：

<?php
  // print $styles;
  // 去掉这一行，如果我们需要在下面去掉drupal.css

  unset($css['core']['misc/drupal.css']);
  print drupal_get_css($css);
?>

3. 新的聚合图标 $feed_icon

在 phpTemplate 里还新增了一个 $feed_icon ，这个变量是一个包含当前页面所有的聚合图标的字符串。有了这个变量，你就可以随意摆放聚合图标，而不是直线与页面正文(body)了。更多内容可参看相关的“模块升级手册部分”。

4. 新的clear CSS类

在5.x以前的版本中，CSS文件里所用的清除浮动类(clearing class)是这样的：

<br class="clear" />

这样带来的一个问题是插入了很多不必要的换行。5.x采用了新的纯基于CSS的清除类，你的有关代码也要改变：

4.7.x

<div>
Some text here.
<br class="clear" />
</div>

5.x

<div class="clear-block">
Some text here.
</div>

theme_links() 函数在5.x中修正为返回链接列表，并且自动加入了帮助识别的CSS标记，包括“first”与“last"。

5.x中theme_links的用法

<?php
print theme('links', $primary_links);
?>

上面的PHP代码将会生成下面的HTML链接代码：

<ul class="links">

<li class="first menu-1-1-52"><a href="/drupalCVS/?q=test" title="" class="menu-1-1-52">test</a></li>

<li class="menu-1-2-52"><a href="/drupalCVS/?q=test2" title="" class="menu-1-2-52">test2</a></li>

<li class="last menu-1-3-52"><a href="/drupalCVS/?q=test3" title="" class="menu-1-3-52">test3</a></li>

</ul>

此外，你还可以提供参数来指定CSS类的ID：

<?php
print theme('links', $primary_links, array('class' =>'links', 'id' => 'navlist'));
?>

将生成下面的HTML代码：

<ul class="links" id="navlist">

<li class="first menu-1-1-52"><a href="/drupalCVS/?q=test" title="" class="menu-1-1-52">test</a></li>

<li class="menu-1-2-52"><a href="/drupalCVS/?q=test2" title="" class="menu-1-2-52">test2</a></li>

<li class="last menu-1-3-52"><a href="/drupalCVS/?q=test3" title="" class="menu-1-3-52">test3</a></li>

</ul>

6. drupal_add_js() 函数-插入javascript脚本

在4.7.x中，javascript文件是通过drupal_set_html_head()来加入到HTML header中的。

在5.x中模块中，javascript脚本是通过下面的函数插入的：

<?php
drupal_add_js($data = NULL, $type = 'module', $scope = 'header', $defer = FALSE, $cache = TRUE);
?>

在theme中，可以通过drupal_get_js()函数来插入所有的javascript脚本（include, settings和js代码）。最好在你的theme一开始的部分，紧跟着drupal_get_css()函数就使用这一函数来插入javascript脚本。

在phpTemplate中，同时还新增了一个 $scripts 变量，包括加载设置javascript脚本所需的所有HTML代码。如果你需要在theme中替换某个javascript脚本，也非常容易：

<?php
   // print $scripts;
  // 不要print $scripts，因为我们要在下面去掉autocomplete.js

  // 这里以数组的形式返回所有的javascript脚本信息
  $js = drupal_add_js(NULL, NULL, 'header');
  unset($js['module']['misc/autocomplete.js']);
  print drupal_get_js('header', $js);
?>

7. _phptemplate_callback 函数改变

在基于phptemplate引擎的主题中使用 _phptemplate_callback() 函数可以自定义theme所需的变量，供给相应的 *.tpl.php 文件使用。4.7中，你必须通过第三个参数 $file 来明确指定外部文件的名称，如果没有这一参数，那么drupal会自动使用 $hook.tpl.php 文件。在5.x中 $file 参数变成了一个数组，你可以提供一系列文件名作为建议，如果drupal没有找到建议文件，那么才自动使用 $hook.tpl.php ，这样就使得 _phptemplate_callback() 函数的应用更灵活更广泛。

4.7.x

<?php
function _phptemplate_callback($hook, $variables = array(), $file = NULL) {
?>

5.x

<?php
/**
* Execute a template engine call.
*
* Each call to the template engine has two parts. Namely preparing
* the variables, and then doing something with them.
*
* The first step is done by all template engines / themes, the second
* step is dependent on the engine used.
*
* @param $hook
*   The name of the theme function being executed.
* @param $variables
*   A sequential array of variables passed to the theme function.
* @param $suggestions
*   An array of suggested template files to use. If none of the files are found, the
*   default $hook.tpl.php will be used.
* @return
*  The HTML generated by the template system.
*/
function _phptemplate_callback($hook, $variables = array(), $suggestions = array()) {
?>

‹ 如何升级你的主题向上实用PHP与Javascript代码 ›
»