Presentation from Drupal camp 2011

1. Render API
Pavel Makhrinsky
e-mail: gumanistius@gmail.com
skype: gumanista
drupal.org: http://drupal.org/user/773216
facebook: https://www.facebook.com/gumanist

2. Overview
● Form API successor
● Drupal 6 ‘theme’ replacement
● System to build structured arrays into content
● The way to build presentation layer

3. Theming ways
● Noob way
● Drupal 6 way
● Drupal 7 way

4. Noob way
1 <div class="nav">
● Inline 2 <ul class="topnav">
3 <li id="lefttopnav" <?php if($levelone == 'home') echo "class="current"";?>><?php echo $menu1;?></li>
4 <li <?php if($levelone == "item-2") echo "class="current"";?>> <?php echo $menu2;?></li>
● Inline 5 <li <?php if($levelone == "item-3") echo "class="current"";?>> <?php echo $menu4;?></li>
6 <li <?php if($levelone == "item-4") echo "class="current"";?>> <?php echo $menu6;?></li>
7 <li <?php if($levelone == "item-5") echo "class="current"";?>> <?php echo $menu5;?></li>
● Inline 8 <li <?php if($levelone == 'item-6') echo "class="current"";?>> <?php echo $menu7;?></li>
9 </ul>
10 </div>
● Inline
● Inline

5. Drupal 6 way
● Use theme functions
● Implement hook_theme
● Move large markup to templates
1 $items = array('item-1', 'item-2', 'item-3', 'item-4', 'item-5');
2 $output = theme('item_list', $items);

6. Drupal 6 way - advantages
● Common way to render elements
● Reusable functions
● Predictable markup
● Possibility to change generation
● Output altering

7. Drupal 6 way - disadvantages
● Slower performance
● Caching difficulties
● Different parameters

8. Drupal 7 way
● Use renderable arrays
● Alter content you need
1 $items = array('item-1', 'item-2', 'item-3', 'item-4', 'item-5');
2 $output = array(
3 '#items' => $items,
4 '#theme' => 'item_list'
5 );

9. Drupal 7 way advantages
● Content alterable in a common way
● All the renderable elements have preprocess
and process functions
● Transparent caching
● Resources could be attached to elements

10. Render API details
● hook_theme
● Renderable array structure
● Content altering
● #type, #theme, #theme_wrappers
● #states
● Resources
● Performance and caching

11. hook_theme()
● hook_theme
○ variables | render element
○ file
○ path
○ template
○ function
○ preprocess functions

12. Renderable array structure
● ‘#’ elements
● system elements
○ #children
○ #access
○ #printed
○ #sorted

13. Content altering
● #pre_render
● #post_render
● preprocess and process functions

14. #type
● Loads defaults from hook_element_info()
1 // If the default values for this element have not been loaded yet, populate
2 // them.
3 if (isset($elements['#type']) && empty($elements['#defaults_loaded'])) {
4 $elements += element_info($elements['#type']);
5}
1 function module_template_element_info() {
2 return array(
3 'file_template' => array(
4 '#name' => 'misc',
5 '#fileinfo' => array(
6 'filename' => '[module_name].[name].[extension]',
7 'path' => 'includes',
8 'extension' => 'inc'
9)
10 )
11 );
11 }

15. #theme
● Invokes theme() function
1 // Get the children of the element, sorted by weight.
2 $children = element_children($elements, TRUE);
3
4 // Initialize this element's #children, unless a #pre_render callback already
5 // preset #children.
6 if (!isset($elements['#children'])) {
7 $elements['#children'] = '';
8}
9 // Call the element's #theme function if it is set. Then any children of the
10 // element have to be rendered there.
11 if (isset($elements['#theme'])) {
12 $elements['#children'] = theme($elements['#theme'], $elements);
13 }
14 // If #theme was not set and the element has children, render them now.
15 // This is the same process as drupal_render_children() but is inlined
16 // for speed.
17 if ($elements['#children'] == '') {
18 foreach ($children as $key) {
19 $elements['#children'] .= drupal_render($elements[$key]);
20 }
21 }

16. #theme_wrappers
● Wrap #children element with code
1 // Let the theme functions in #theme_wrappers add markup around the rendered
2 // children.
3 if (isset($elements['#theme_wrappers'])) {
4 foreach ($elements['#theme_wrappers'] as $theme_wrapper) {
5 $elements['#children'] = theme($theme_wrapper, $elements);
6}
7}

17. #states
● Adds JavaScript to change the state of an
element based on another element
1 $form['toggle_me'] = array(
2 '#type' => 'checkbox',
3 '#title' => t('Tick this box to type'),
4 );
5 $form['settings'] = array(
6 '#type' => 'textfield',
7 '#states' => array(
8 // Only show this field when the 'toggle_me' checkbox is enabled.
9 'visible' => array(
10 ':input[name="toggle_me"]' => array('checked' => TRUE),
11 ),
12 ),
13 );

18. Resources
● #attached property
● Allow attach
○ CSS
○ JavaScript
○ Libraries
● Not cached

19. Performance and caching
● Setting cache for renderable arrays
● Some cache usage tips

20. #cache
● 'keys' => an array of keys which will be
concatenated to form the cache key.
● 'bin' => the name of the cache bin to be used
(as in 'cache' or 'cache_page', etc.
● 'expire' => a Unix timestamp indicating the
expiration time of the cache.
● 'granularity' => a bitmask indicating the cache
type. This should be
DRUPAL_CACHE_PER_PAGE,
DRUPAL_CACHE_PER_ROLE, or
DRUPAL_CACHE_PER_USER

21. Some cache usage tips
● Don’t cache small items
● Items from #attached not stored with rendered
Elements 5 100 500
items
With #cache
Without #cache
3211
747
3276
4257
3235
18336
● Use cache targeting
● Cache items will not be expired until cron runs,
regardless of the expiration time used

22. Summary
● Don’t use direct call of theme() function
● Generate HTML as later as possible

23. Links
● Render API
○ http://drupal.org/node/933976
○ http://drupal.org/node/930760
○ http://api.drupal.org/api/drupal/includes--common.inc/function/drupal_render/7
● States
○ http://api.drupal.org/api/drupal/includes--common.inc/function/drupal_process_states/7
● Drupal API
○ http://api.drupal.org
● Examples module
○ http://drupal.org/project/examples
● Cache backends
○ http://drupal.org/project/apc
○ http://drupal.org/project/memcache
○ http://drupal.org/project/filecache

24. Thank you
e-mail: gumanistius@gmail.com
skype: gumanista
drupal.org: http://drupal.org/user/773216
facebook: https://www.facebook.com/gumanist