The Render API in Drupal 7

10,878 views
10,702 views

Published on

See http://chicago2011.drupal.org/sessions/render-api-drupal-7 for details.

Published in: Technology
0 Comments
13 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
10,878
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
0
Comments
0
Likes
13
Embeds 0
No embeds

No notes for slide

The Render API in Drupal 7

  1. 1. The Render API in Drupal 7 Franz Heinzmann Frando http://drupal.org/user/21850 twitter.com/frandoh
  2. 2. The Render API in Drupal 7 Overview <ul><li>What is the Render API </li></ul><ul><li>Render API and Forms API </li></ul><ul><li>Render arrays – A closer look </li></ul><ul><li>The page rendering process </li></ul><ul><li>Attaching resources </li></ul><ul><li>Render caching </li></ul><ul><li>Rendering into other formats </li></ul><ul><li>Render API for themers </li></ul>
  3. 3. What is the Render API <ul><li>A system to render structured arrays into a flat string of text </li></ul>
  4. 4. What is the Render API <ul><li>A system to render structured arrays into a flat string of text </li></ul><ul><li>A system to create the final page output, usually HTML, from structured arrays of data. </li></ul>
  5. 5. What is the Render API <ul><li>A system to render structured arrays into a flat string of text </li></ul><ul><li>A system to create the final page output, usually HTML, from structured arrays of data. </li></ul><ul><li>A successor to the Form API rendering system </li></ul>
  6. 6. An example
  7. 7. Advantages <ul><li>Data can be accessed and altered later on by other modules </li></ul><ul><li>Better reusability: Makes it much easier to use a page or block callback for more things (e.g. AJAX) </li></ul><ul><li>One consistent system for all output generation </li></ul>
  8. 8. Render API and Forms API <ul><li>Render API is the improved version of the Forms API rendering system. Its center is the drupal_render() function. </li></ul><ul><li>Forms API uses the Render API to render forms. </li></ul><ul><li>In D7, drupal_render() is used to render nearly all page output. </li></ul>
  9. 9. Render Arrays – A closer look <ul><li>#type </li></ul><ul><ul><li>Predefine elements in hook_element_info() </li></ul></ul><ul><li>#access </li></ul><ul><li>#theme and #theme_wrappers </li></ul><ul><li>#pre_render </li></ul><ul><li>#attached </li></ul>
  10. 10. Render Arrays – Theming <ul><li>#theme: name of theme function to invoke </li></ul><ul><li>Has to render all children! </li></ul><ul><li>In hook_theme(): Choose theming method: </li></ul><ul><ul><li>Element-As-Variable theming </li></ul></ul><ul><ul><li>Properties-As-Variable theming </li></ul></ul>
  11. 11. Render Arrays – Theming <ul><li>#theme_wrappers: Array of theme functions </li></ul><ul><li>Wrap markup around the themed output </li></ul><ul><li>Has to include the themed output $element['#children'] </li></ul><ul><li>Used e.g. for forms, containers, fieldsets </li></ul><ul><li>Allows to set #theme functions on specific elements without having to worry about surrounding markup </li></ul>
  12. 12. Render Arrays – Theming
  13. 13. Render Arrays – Theming
  14. 14. drupal_render() <ul><li>Takes one argument only: A render array. </li></ul>
  15. 15. drupal_render() <ul><li>Check #access and #printed </li></ul><ul><li>Check if cached version is available </li></ul><ul><li>Load defaults (if #type is set) </li></ul><ul><li>Call #pre_render callbacks </li></ul><ul><li>Call #theme or concenate children </li></ul><ul><li>Call #theme_wrappers </li></ul><ul><li>Call #post_render </li></ul><ul><li>Handle #attached (JavaScript, CSS, Libraries) </li></ul><ul><li>If #cache is set: Cache the output string </li></ul><ul><li>Return #prefix . $output . #suffix </li></ul>
  16. 16. The page rendering process <ul><li>All page elements are assembled into one single render array. </li></ul><ul><li>This includes: </li></ul><ul><ul><li>main content (page callback result) </li></ul></ul><ul><ul><li>blocks </li></ul></ul><ul><ul><li>anything else added by modules </li></ul></ul><ul><li>Let's look how it actually works. </li></ul>
  17. 17. The page rendering process <ul><li>hook_page_build() -> Add elements </li></ul><ul><li>hook_page_alter() -> Alter existing elements </li></ul><ul><li>block.module is no longer required! </li></ul>
  18. 18. Render caching <ul><li>The #cache property </li></ul><ul><li>Cache resource intensive elements while other parts are created dynamically </li></ul>
  19. 19. Attached resources <ul><li>The #attached property </li></ul><ul><li>Attach CSS, JavaScript and Libraries to elements instead of adding them in hook_init() </li></ul>
  20. 20. Attached resources <ul><li>The #attached property </li></ul><ul><li>Attach CSS, JavaScript and Libraries to elements instead of adding them in hook_init() </li></ul><ul><li>Makes AJAX/AHAH loading of individual elements possible </li></ul><ul><li>Makes caching individual elements possible without „losing“ needed resources </li></ul>
  21. 21. Attached resources
  22. 22. Render caching <ul><li>The #cache property </li></ul><ul><li>Cache resource intensive elements while other parts are created dynamically </li></ul><ul><li>Cache by permission, role, user, … </li></ul><ul><li>Cache by an SQL query: Compatible with node access! </li></ul>
  23. 23. Render caching <ul><li>The #cache property </li></ul><ul><li>Cache resource intensive elements while other parts are created dynamically </li></ul><ul><li>Cache by permission, role, user, … </li></ul><ul><li>Cache by an SQL query: Compatible with node access! </li></ul><ul><li>Edge Side Includes (ESI) </li></ul>
  24. 24. Render caching
  25. 25. Taking over page rendering & rendering into other formats <ul><li>Not yet much used, but has been a design goal of the D7 Render API </li></ul><ul><li>Delivery callbacks </li></ul><ul><ul><li>hook_menu_alter() </li></ul></ul><ul><ul><li>hook_page_delivery_callback_alter() </li></ul></ul><ul><li>Changing $page['#theme'] </li></ul>
  26. 26. The Render API for themers <ul><li>$element in theme functions and templates </li></ul><ul><li>render(), show(), hide() </li></ul><ul><li>Using hook_page_alter() in a theme: Change theme functions for specific instances of a theme hook! </li></ul>
  27. 27. Summary <ul><li>Use render arrays in your module's page and block callbacks! </li></ul><ul><ul><li>Do not call theme()! </li></ul></ul><ul><li>Use #attached, #pre_render, #cache to easily make your output re-usable and fast </li></ul><ul><li>Use the power of render arrays to avoid complicated code in theme </li></ul>
  28. 28. Challenges ahead <ul><li>Build and establish shared library of easily reusable interface elements </li></ul><ul><li>Make it easier to render render arrays into other formats </li></ul><ul><li>D8: Settle on one method of element theming? </li></ul><ul><li>D8: Actually use render arrays through all of core – no calls to theme()! </li></ul>
  29. 29. Resources <ul><li>API documentation: http://api.drupal.org </li></ul><ul><li>Render API doc on drupal.org: </li></ul><ul><li>http://drupal.org/node/930760 </li></ul><ul><li>Examples module: http://drupal.org/project/examples </li></ul>
  30. 30. What did you think? Locate this session on the DCC website: http://chicago2011.drupal.org/sessions Click the “Take the Survey” link. Thanks!

×