This document provides an overview of different approaches to theming in Drupal: the "noob way" of using direct PHP/HTML, the Drupal 6 method of using theme functions, and the Drupal 7 Render API method of generating renderable arrays. It discusses advantages of the Render API like content alteration hooks, caching and performance. Key aspects covered include the renderable array structure, the use of #type, #theme, #states and #attached properties. The document recommends generating HTML as late as possible and using the Render API and caching to improve performance.

1. Render API Pavel Makhrinsky http://donetsk.drupal.ua

2. Render API Pavel Makhrinsky e-mail: [email_address] skype: gumanista

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

4. Theming ways Noob way Drupal 6 way Drupal 7 way

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

6. 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 );

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

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

9. 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 );

10. 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

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

12. hook_theme() hook_theme variables | render element file path template function preprocess functions

13. Renderable array structure ‘ #’ elements system elements #children #access #printed #sorted

14. Content altering #pre_render #post_render preprocess and process functions

15. #type Loads defaults from hook_element_info() 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 } 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 }

16. #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 }

17. #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 }

18. #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=&quot;toggle_me&quot;]' => array ( 'checked' => TRUE ), 11 ), 12 ), 13 );

19. Resources #attached property Allow attach CSS JavaScript Libraries Not cached

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

21. #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

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

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

24. 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

25. Thank you e-mail: [email_address] skype: gumanista