The Render API in Drupal 7 provides a system for rendering structured data arrays into output like HTML. It is an improved version of the Forms API rendering that uses drupal_render() to generate nearly all page output from render arrays. Render arrays allow elements and pages to be assembled, altered, and cached flexibly through a consistent rendering process. Themes can also interact with render arrays to style output without modifying module code.

1. The Render API in Drupal 7 Franz Heinzmann Frando http://drupal.org/user/21850 twitter.com/frandoh

2. The Render API in Drupal 7 Overview What is the Render API Render API and Forms API Render arrays – A closer look The page rendering process Attaching resources Render caching Rendering into other formats Render API for themers

3. What is the Render API A system to render structured arrays into a flat string of text

4. What is the Render API A system to render structured arrays into a flat string of text A system to create the final page output, usually HTML, from structured arrays of data.

5. What is the Render API A system to render structured arrays into a flat string of text A system to create the final page output, usually HTML, from structured arrays of data. A successor to the Form API rendering system

6. An example

7. Advantages Data can be accessed and altered later on by other modules Better reusability: Makes it much easier to use a page or block callback for more things (e.g. AJAX) One consistent system for all output generation

8. Render API and Forms API Render API is the improved version of the Forms API rendering system. Its center is the drupal_render() function. Forms API uses the Render API to render forms. In D7, drupal_render() is used to render nearly all page output.

9. Render Arrays – A closer look #type Predefine elements in hook_element_info() #access #theme and #theme_wrappers #pre_render #attached

10. Render Arrays – Theming #theme: name of theme function to invoke Has to render all children! In hook_theme(): Choose theming method: Element-As-Variable theming Properties-As-Variable theming

11. Render Arrays – Theming #theme_wrappers: Array of theme functions Wrap markup around the themed output Has to include the themed output $element['#children'] Used e.g. for forms, containers, fieldsets Allows to set #theme functions on specific elements without having to worry about surrounding markup

12. Render Arrays – Theming

13. Render Arrays – Theming

14. drupal_render() Takes one argument only: A render array.

15. drupal_render() Check #access and #printed Check if cached version is available Load defaults (if #type is set) Call #pre_render callbacks Call #theme or concenate children Call #theme_wrappers Call #post_render Handle #attached (JavaScript, CSS, Libraries) If #cache is set: Cache the output string Return #prefix . $output . #suffix

16. The page rendering process All page elements are assembled into one single render array. This includes: main content (page callback result) blocks anything else added by modules Let's look how it actually works.

17. The page rendering process hook_page_build() -> Add elements hook_page_alter() -> Alter existing elements block.module is no longer required!

18. Render caching The #cache property Cache resource intensive elements while other parts are created dynamically

19. Attached resources The #attached property Attach CSS, JavaScript and Libraries to elements instead of adding them in hook_init()

20. Attached resources The #attached property Attach CSS, JavaScript and Libraries to elements instead of adding them in hook_init() Makes AJAX/AHAH loading of individual elements possible Makes caching individual elements possible without „losing“ needed resources

21. Attached resources

22. Render caching The #cache property Cache resource intensive elements while other parts are created dynamically Cache by permission, role, user, … Cache by an SQL query: Compatible with node access!

23. Render caching The #cache property Cache resource intensive elements while other parts are created dynamically Cache by permission, role, user, … Cache by an SQL query: Compatible with node access! Edge Side Includes (ESI)

24. Render caching

25. Taking over page rendering & rendering into other formats Not yet much used, but has been a design goal of the D7 Render API Delivery callbacks hook_menu_alter() hook_page_delivery_callback_alter() Changing $page['#theme']

26. The Render API for themers $element in theme functions and templates render(), show(), hide() Using hook_page_alter() in a theme: Change theme functions for specific instances of a theme hook!

27. Summary Use render arrays in your module's page and block callbacks! Do not call theme()! Use #attached, #pre_render, #cache to easily make your output re-usable and fast Use the power of render arrays to avoid complicated code in theme

28. Challenges ahead Build and establish shared library of easily reusable interface elements Make it easier to render render arrays into other formats D8: Settle on one method of element theming? D8: Actually use render arrays through all of core – no calls to theme()!

29. Resources API documentation: http://api.drupal.org Render API doc on drupal.org: http://drupal.org/node/930760 Examples module: http://drupal.org/project/examples

30. What did you think? Locate this session on the DCC website: http://chicago2011.drupal.org/sessions Click the “Take the Survey” link. Thanks!