>

<?php print render($content[‘links’]); ?>
</div>

The preceding example shows the full gamut of the things that you are likely see in a template file. They are as follows:

1. Printing a variable containing a string?
2. Printing a translatable string using t()
3. Conditional if/else/endif statement
4. Delaying rendering on part of a render element with hide()
5. Printing a render element

All of the PHP in a template should be limited to printing out variables. This limited amount of PHP makes it much easier for non-programmers to learn how to use template fles compared to theme functions. However, for module developers, the template implementation is still very similar to the theme function implementation; the handful of differences are relatively minor.

As with theme function implementations, our module would still need to invoke the theme hook usingtheme().

$variables = array(‘typical’ => $typical_object);
$output = theme(‘typical_hook’, $variables);

The theme() function would discover that the typical_hook theme hook was implemented as a template and render the corresponding typical-hook.tpl.php file.

The only valid characters in theme hook names are alphanumeric characters and underscores. This is true of all theme hooks, regardless of whether they are implemented as a theme function or as a template file. However, when theme() looks for template implementations, it will automatically convert any underscores in the theme hook name into hyphens while searching for the template file. For example, calling theme(‘user_picture’, $variables) will result in the template file nameduser-picture.tpl.php being rendered.

Also, just like theme functions, other modules can modify the variables using preprocess functions.

In template fles the focus is on printing out variables in various places in the markup. So for template fles, the preprocess function takes on a more important role. The only difference between a theme function’s preprocess functions and a template file’s are the number and type of preprocess functions.

        Read more about this book     

(For more resources on this subject, see here.)

The preprocess zoo

When you write a theme function, its natural to pass the raw data in as parameters and generate any display-related meta-data inside the function. With a template file, that’s not really possible without putting complex PHP inside the template. However, as was stated earlier, all of the PHP in a template file should be limited to just the bare minimum required to print out a PHP variable. Any processing that we need to do on the raw data parameters to ease it into print-ready variables should be done in preprocess functions.

“template_” preprocess functions

When a module defnes a theme hook by creating a template file, that module should also create a corresponding preprocess function to set up and process any variables that are needed by the template file, but are not passed as parameters to heme(). By convention, that preprocess function should be of the following form:

template_preprocess_[theme hook name](&$variables)

The template_prefix tells Drupal’s theme system that this preprocess function is the primary preprocessor for the theme hook’s variables and should be run before any other module’s preprocess function.

Here’s an example that should make this concept a bit clearer. This is an actual code snippet from Drupal’s block preprocess function. In each page region, all of the blocks in the region get a variable whose value alternates between “odd” and “even”. These values can be used to create zebra-striped styling, that is, alternate styling on every other block in a region.

function template_preprocess_block(&$variables) {
// We store all block counters using drupal_static().
$block_counter = &drupal_static(__FUNCTION__, array());

// All blocks get an independent counter for each region.
if (!isset($block_counter[$variables[‘block’]->region])) {
$block_counter[$variables[‘block’]->region] = 1;
}

// Generate the zebra striping variable.
$variables[‘block_zebra’] = ($block_counter[$variables[‘block’]-
>region] % 2) ? ‘odd’ : ‘even’;

// Increment the region’s block count.
$block_counter[$variables[‘block’]->region]++;
}

The PHP logic in this function is directly related to the display of the block and not to the general business logic of this data. So, it doesn’t make sense that the block module would calculate that meta data before calling theme(); the meta data clearly belongs to the display logic, which is why it’s placed in the block module’s preprocess function.

Multi-hook preprocess functions

In some rare circumstances, you may need to alter or provide some variables for all theme hooks. In fact, Drupal’s theme system does provide some variables to all templates; the preprocess function that provides these variables is both a “template_” preprocess function and a multi-hook preprocess function. Multi-hook preprocess functions are simply functions that don’t have a _HOOK suffx added to their name and are run for every single template file. Their name is of the following form:

[module]_preprocess(&$variables, $hook)

Obviously, there can be a big performance hit if a module needlessly implements a multi-hook preprocess function. If you’re contemplating writing one, if at all possible, consider writing several preprocess functions that target the specifc hooks you need instead, rather then hit all hooks.

Now, if you were paying close attention to the form of the name, you’ll also notice that these functions actually receive two parameters, namely, the $variables array and a $hook parameter. $hook, as the name suggests, contains the name of the actual theme hook currently being run. So, while afoo_preprocess(&$variables, $hook) function is run for every template file, it will still be able to tell which template is currently being requested. In fact, $hook is the second parameter for all preprocess functions, but $hook is only useful for multi-hook preprocess functions.

For a good example of a multi-hook preprocess function, let’s look at the function that the theme system uses to set up several variables common to all template files—the template_preprocess() function, which is as follows:

function template_preprocess(&$variables, $hook) {
// Tell all templates where they are located.
$variables[‘directory’] = path_to_theme();

// Initialize html class attribute for the current hook.
$variables[‘classes_array’] = array(drupal_html_class($hook));
}

As you can see, this preprocess function creates a $directory variable which can be used to tell where the template file is located on the web server. In the $classes_array variable, it also starts to set up the CSS classes used in the outer-most wrapping div of the template.

Process functions

Obviously, inside our template file, when we print out our dynamically created list of classes, we’ll need the variable to be a string. <?php print $classes_array; ?> will, most unhelpfully print out “array”. In earlier versions of Drupal, classes were dynamically created but were immediately concatenated into strings. So themes would see one long string with multiple classes in it, menu-block-wrapper menu-block-1 menu-name-management, for example. This made removing or altering classes difficult as themers had to master PHP’s string-manipulation functions or even (gasp!) regular expressions.

In Drupal 7, this problem for themers has been solved using the new process functions. Process functions are an additional phase of variable processing functions that run after the initial preprocess functions. In all respects, process functions are exactly like preprocess functions; there are template_prefixed process functions, multi-hook process functions, module-provided process functions, and theme-provided process functions. The only difference is that process functions are run after all preprocess functions have been run.

Process functions are extremely useful when you have meta data that is likely to be manipulated by other modules or themes and you wish to delay the rendering of the meta data until just before the template file itself is rendered.

In the preceding code example, the template_preprocess() function creates a $classes_array variable that holds an array of classes to be used on the wrapping div in the template file. Modules and themes can easily add classes by simply adding an additional array element from inside their preprocess function, as follows:

$variables[‘classes_array’][] = ‘extra-savoir-faire’;

Themes can use much simpler array manipulation functions in order to remove or alter classes.

// Search for the bogus class and return its array key
// location. If not found, array_search returns FALSE.
// Remember that 0 is a valid key.
$key = array_search(‘bogus’, $variables[‘classes_array’]);
if ($key !== FALSE) {
// Alter the class.
$variables[‘classes_array’][$key] .= ’-dude’;
}
// Or remove the no-soup class.
$variables[‘classes_array’] = array_diff($variables[‘classes_array’],
array(‘no-soup’));

In addition to the $classes_array variable, the template_preprocess() function also creates $attributes_array,$title_attributes_array, and $content_attributes_array variables which are used for HTML attributes on the outermost wrapping div, the title’s heading tag, and the content’s wrapping div, respectively. You’ll see each of these variables used in the typical-hook.tpl.php example.

After modules and themes are given an opportunity to alter these variables, the theme system uses thetemplate_process() function to render those arrays into a simple string, as follows:

function template_process(&$variables, $hook) {
// Flatten out classes.
$variables[‘classes’] = implode(’ ’, $variables[‘classes_array’]);

// Flatten out attributes, title_attributes, and content_attributes.
$variables[‘attributes’] = drupal_attributes(
$variables[‘attributes_array’]);
$variables[‘title_attributes’] = drupal_attributes(
$variables[‘title_attributes_array’]);
$variables[‘content_attributes’] = drupal_attributes(
$variables[‘content_attributes_array’]);
}

A similar problem troubled module developers in Drupal 6. It was impossible to call drupal_add_css() ordrupal_add_js() in a MODULE_preprocess_page() function because the lists of CSS files and JavaScript files were already generated before any of the preprocess functions were run. Again, process functions come to the rescue. Drupal 7 delays the generation of these lists until the template_process_html() function is run.

        Read more about this book     

(For more resources on this subject, see here.)

Order of preprocess execution

Now with all these different favors of processing functions, it can get a bit confusing as to which function runs in what order. Fortunately, there are just three simple rules that are used to determine the order of processing. They are as follows:

• All preprocess functions run before all process functions
• template_ prefixed functions run frst. [module]_ prefixed functions run next. [theme]_ prefixedfunctions run last
• Multi-hook functions run before hook-specifc functions

This results in the following order of execution for a particular theme hook:

1. template_preprocess()
2. template_preprocesss_HOOK()
3. MODULE_preprocess()
4. THEME_preprocess()
5. THEME_preprocess_HOOK()
6. template_process()
7. template_processs_HOOK()
8. MODULE_process()
9. MODULE_process_HOOK()
10. THEME_process()
11. THEME_process_HOOK()

Whew

If the THEME is actually a list of inherited base and sub-themes, each THEME_-prefixed item above could be a list of each base theme’s and sub-theme’s functions, which would make the list even longer. See the “Base themes and sub-themes” tip near the beginning of this chapter if you haven’t read it already.

Summary

In this article we have covered:

• Business logic versus presentation logic
• Data granularity
• Theme engines
• Two ways to theme

summarized by me

module은 theme에서 수행되는 markup 작업에 세세하게 관여하지 않아도 된다. 다만 default theme implementation만을 수행하면된다.

$variables = array(‘items’ => $list, ‘type’ => ‘ol’);

$content = theme(‘item_list’, $variables);

위의 내용은 다시 “Hey, theme()! I want to markup my data as an item_list. Can you do that for me? I don’t need to know the details. kthxbye.”  와 같이 이해 될수 있다.

hook에 대한 내용

drupal에는 api hooks 와 theme hooks가 있다. theme hook는 data를 markup하는 방법을 말한다. ( 원문 A theme hook is simply the name of a particular way to markup some data. )

예를 들어 item_list theme hook 와 link theme hook에 같은 data를 제공하는 경우 앞은 경우는 list의 형태로 markup 된다. 후자는 link의 형태로 markup 된다. module hook의 경우 drupal core에서 hook가 호출되면 module각각에 들어있는 해당하는 hook가 모두 실행된다. theme hook의 경우는 대응하는 hook가 단 하나 존재한다.

data를 implementation 하는 방법에는 두가지가 있다.

1. theme function을 이용하는 방법이다.

theme()을 호출하면 우선 default theme function을 찾는다. 이름은 theme_HOOK이름 형식이며 include.inc 또는 theme.in 화일에 존재한다. 우선 기본 함수를 찾고 그다음은 각각의 theme에서 제공하는 override 함수가 있는지 확인하고 있으면 그것을 적용한다. 이름의 형식은 THEME이름_HOOK이름 의 형태가 된다. 예를 들어 list형태로 data를 출력하는 경우 theme_item_list()를 기본적으로 이용하나 bartik theme에서 이를 override하는 함수가 있는경우는 bartik_item_list()가 대신 이용된다.

base themes and sub-themes

어느 theme이든 base theme key를 이용 .info 화일에서 parent theme을 선언할수 있다. 이런경우 모든 theme hook implementations 이 sub-theme에도 상속된다.

theme engine

drupal에는 theme engine이 존재하며 이는 template syntax, naming standards, helper functions을 관장한다. 이또한 수정가능하다. 그러나 보통은 수정이 필요하지 않으며 몇몇 engine이 이미 나와 있다. 그러나 PHPTemplate이 가장 많이 사용되며 기본 engine으로 사용된다.

theme implementation

2가지의 방법이 존재한다.

1. theme functions을 이용한다. data를 theme() 함수에 전달 markup data 로 전환한다.

2. templates를 이용한다. php구문, print구문과 markup 구문이 섞여있는 template에 data를 전달하는 방법이다.  

theme 함수 (기본 작업을 수행하는 includes.inc나 theme.inc에 존재한다.)

우선 theme function의 이름은 theme_[theme hook 이름] 의 형식이다. theme hook 이름  은 실제 함수이름으로 사용되므로 php 함수이름 정의 규칙을 따른다. 알파벳, 숫자 , 언더스코어를 사용할수 았다. 예를 들어 example_format theme hook의 경우는 theme_example_format()이 된다.

실제 function정의의 형태는 function theme_THEME_HOOK_이름 ($variables){ …….} 가 된다. parameter는 단 하나이며 여기에 markup 될 data 와 방법에 관련된 options이 모두 array의 형태로 전달된다.

예시)

For an example of a $variables array, let’s look at how the DocBlock of the theme_item_list() function defnes it:

• Items: An array of items to be displayed in the list. If an item is a string, then it is used as is. If an item is an array, then the data element of the array is used as the contents of the list item. If an item is an array with a “children” element, those children are displayed in a nested list. All other elements are treated as attributes of the list item element.

• Title: The title of the list.

• Type: The type of list to return (e.g. ul,ol).

• Attributes: The attributes applied to the list element.

위와 같이 정의된 theme function 은 markup된 형태의 string을 return한다. 대부분은 html string 이 될것이다. 특수한 경우는 markup된 형태가 아닌 다른 형식의 string이 return 되기도한다. 예를 들어 error log 를 얻어내야 하는 경우.

theme function은 일반 function과 달리 직접 호출해서 사용하지 않고 theme()이용하여 간접 사용한다.

preprocess functions

preprocess function 은 theme hook가 호출될때 하나의 module이 다른 module에 의해 사용되는 variables을 변경할수 있게 한다. 특정theme hook를 위해 theme()에 data를 전달하는 경우 preprocess function가 호출되고 data가 preprocess function을 거쳐 변경된 data가 원래 theme hook로 전달된다.

과정

1. theme(‘hook이름’, $variables) 가 호출된다.

2. theme()는 특정 hook를 위해 preprocess function을 호출한다.

3. preprocess function이 data를 변경한다

4. theme()은 변경된 data를 이용 원래 hook를 호출수행한다.

preprocess function의 이름 형식 [module이름]_preprocess_[themehook이름] 이어야 한다.

함수 정의 형식예

function foo_preprocess_item_list(&$variables)

{

// add a class to the list wrapper

$variables[‘attributes’][‘class’][]=’foo-list’;

}

유의사항: variable은 by reference형태로 전달된다.그러므로 함수내에서 return 구문이 필요없으며 직접 값은 원래 변수에서 변경된다.

theme overrides

drupal theme 은 css, images, javascripts, template files, .info file 와 template.php 화일로 구성된다.

template.php 화일은 module의 .module 화일과 유사한 기능을 한다. 모든 필요한 php 함수들을 포함하고 있으며 theme이 initialized 되면 자동 load된다. 기본적으로 정의된 theme hook fucntion을 override 하는 경우는 기존형식인

function theme_hook이름($variables){…..}

에서 function 새이름_hook이름($variables){….}를 template.php 에 정의한다.

예를 들면 bartik theme을 사용하며 includes/menu.inc에 있는 theme_menu_local_tasks()를 override하는 경우 template.php 안에 bartik_menu_local_tasks()를 만든다. bartik이 아닌 다른 문구도 상관없으나 theme 이름을 하면 이해하기 쉬울듯하다. theme function이 override 되어도 preprocess function은 원래 의도된 그대로 실행된다. theme preprocess function도 만들수 있으며 theme이름_preprocess_hook이름()의 형식으로 만들면된다. theme preprocess가 module preprocess 를 override하지는 않는다. module preprocess 먼저 그리고 theme preprocess 이 다음으로 순서대로 실행된다.

template files

theme functions 대신에 template files을 이용해 theme hook가 implementation 할수있다.template file은 기본적으로 html 문서내용에 template’s variables 를 사용하는 php statements를 포함하고 있다. theme_hook이름() 을 이용하기 보다 hook이름.tpl.php 화일을 이용한다.

예를 들면

div class=“<?php print $classes; ?>”<?php print $attributes; ?>>

<?php if ($title): ?>

<h2<?php print $title_attributes; ?>>

  <?php print $title; ?>

</h2>

<?php endif;?>

<?php print render($content[‘links’]); ?>

</div>

이런 형식이 된다.

theme function implementation 과 마찬가지로 theme()을 이용하여 theme hook를 호출해야 한다.

예를 들어 $variables = array(‘typical’ => $typical_object);

$output = theme(‘typical_hook’, $variables);

theme()를 이용하여 template이 호출될때 theme hook 이름 자리에 들어 있는 언더스코어는 대쉬 (-) 로 전환되어 호출된다. 예를 들어 theme(‘user_picture’, $variables)의 경우는 user-picture.tpl.php 가 검색 호출된다. theme function 과 마찬 가지로 template 의 경우도 preprocess function을 이용하여 variables을 변경할수 있다. template 화일에는 되도록이면 더이상 변경이 필요없는 출력 준비된 variable만을 이용하는 것을 권장한다. data 처리는 되도록이면 preprocess에서 처리하는 것을 권장한다.

“template_” preprocess functions

module 이 template file을 이용하여 theme hook를 정의하는 경우, 해당 module은 이에 대응하는 preprocess function을 만들어야 한다. 형식은 template_preprocess_[theme_hook이름](&$variables) 이 된다.

예시를 들면 function template_preprocess_block(&$variables) {

// We store all block counters using drupal_static().

$block_counter = &drupal_static(__FUNCTION__, array());

// All blocks get an independent counter for each region.

if (!isset($block_counter[$variables[‘block’]->region])) {

  $block_counter[$variables[‘block’]->region] = 1;

}

// Generate the zebra striping variable.

$variables[‘block_zebra’] = ($block_counter[$variables[‘block’]-

>region] % 2) ? ‘odd’ : ‘even’;

// Increment the region’s block count.

$block_counter[$variables[‘block’]->region]++;

}

preprocess function안에는 data의 표시 형식 변경에 관련된 내용만 들어가게 한다. 직접적인 business logic은 이전에 이미 처리되어서 전달 되어져야 한다.

multi-hook preprocess functions

모든 theme hooks를 위해 variables를 변경해야 하는 경우 multi-hook preprocess가 사용된다. _HOOK 접미사가 함수이름에 붙지 않으며 모든 template file을 위해 사용된다.

[module이름]_preprocess(&$variables,$hook) 이 함수이름 형식이다.이 함수는 모든 hook실행시 전에 variables의 변경을 수행함으로 성능에 좋지 않은 영향을 줄수 있다. 함수 정의 구문에서 사용되는 2번째 파라미터는 현재 사용중인 theme hook 이름을 가지고 있다. 보통 multi-hook preprocess는 모든 template에서 사용되는 기본 variables의 설정에 사용된다.

process functions

preprocess functions을 통해서 css, class 이름, attributes의 내용등을 수정할수 있다. 그리고 그 최종 생산물은 array형태가 되며 이를 각각의 string 형태로 만들어 가는 과정을 process function이 담당한다. drupal 6에서는 MODULE_preprocess_page() 함수에서 drupal_add_js(), drupal_add_css()를 이용하는 것이 불가능했지만 drupal 7에서는 template_process_html()이 호출되기 전까지 string을 만들어 내는 것을 지연시키므로 가능하다.

order of preprocess 실행

모든 preprocess functions은 process function 전에 실행된다.

template_ 로 시작되는 함수가 [module이름]_ 으로 시작되는 함수보다 먼저 실행된다. 맨 마지막이 [theme이름]_ 으로 시작되는 함수가 실행된다.

multi-hook 함수가 특정 hook 에 한정된 함수보다 먼저 실행된다.

1. template_preprocess()

2. template_preprocesss_HOOK()

3. MODULE_preprocess()

4. THEME_preprocess()

5. THEME_preprocess_HOOK()

6. template_process()

7. template_processs_HOOK()

8. MODULE_process()

9. MODULE_process_HOOK()

10. THEME_process()

11. THEME_process_HOOK()

base theme 이 있고 sub theme 이 있어서 상속되는 형태라면 base theme 의 내용이 실행되고 sub theme의 내용이 실행되는 보다 복잡한 순서 전개가 이루어 진다.