Beyond the Guidelines: Theme Development Best Practices @chip_bennett  (Volume 1) Chip Bennett, WordCamp Toronto, 05 Novem...
Beyond the Guidelines: Theme Development Best Practices Audience Developers  Themes intended to be hosted by WPORG Best Pr...
Theme Inline Documentation phpDoc ftw! WordCamp Toronto: 05 November 2011
Beyond the Guidelines: Theme Development Best Practices Why? <ul><li>You'll use it!
Auto-generation of Theme documentation/cross-reference
Built-in support: explains template file use, function input/output </li></ul>Use phpDoc standard <ul><ul><li>Syntax </li>...
Long Description
Tags </li></ul></ul></ul><ul><li>Page-level docblocks:  </li></ul><ul><li>All template files
Inline docblocks: </li></ul><ul><ul><li>Function definitions, constants, global variables, classes </li></ul></ul>WordCamp...
Beyond the Guidelines: Theme Development Best Practices Example 1: template file undocumented WordCamp Toronto: 05 Novembe...
Beyond the Guidelines: Theme Development Best Practices Adding a page-level PHP docblock WordCamp Toronto: 05 November 201...
Long Description
@package tag
@copyright tag
@license tag </li></ul>Purpose: <ul><li>Describe purpose of template/functional file
Cross-reference functions used in the template file
Document copyright attribution and license declaration </li></ul>
Beyond the Guidelines: Theme Development Best Practices Example 2: index.php template file page-level docblock WordCamp To...
Beyond the Guidelines: Theme Development Best Practices Adding a function-level PHP docblock WordCamp Toronto: 05 November...
Long Description
@param tag
@return tag </li></ul>Purpose: <ul><li>Describe purpose of the function/global variable/constant/class
Cross-reference functions called within the function
Describe function parameter (input) datatypes, criticality, purpose
Describe function output datatype and purpose
Document copyright attribution (if borrowed/derived code) </li></ul>
Beyond the Guidelines: Theme Development Best Practices Example 3: function-level docblock WordCamp Toronto: 05 November 2...
Copyright Attribution and License Declaration Credit where it's due and maintaining users' rights WordCamp Toronto: 05 Nov...
Beyond the Guidelines: Theme Development Best Practices Almost every Theme and Plugin is Doing It Wrong WordCamp Toronto: ...
License URI tag </li></ul>What's Missing <ul><li>Copyright Attribution
Derivative Themes
Incorporated Code
Bundled Resources </li></ul>Why are Copyright and License Important? <ul><li>Ensure end-user freedoms are preserved
Upcoming SlideShare
Loading in...5
×

WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)

4,666

Published on

As Theme developers become more accustomed to the Theme Review Guidelines, the overall quality of WordPress.org repository-hosted Themes has improved tremendously. However, ample opportunity for continual improvement remains. As the Theme Review Team continues to refine and improve the Guidelines with each new WordPress release, I believe that we can work together with the Theme developer community proactively to implement community-standard best practices. In this presentation, I will discuss areas for such best practices, including Theme inline documentation, proper copyright attribution and copyright declaration, Child-Theme readiness, proper enqueueing of scripts and stylesheets, and a few, other miscellaneous areas.

Published in: Technology

WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)

  1. 1. Beyond the Guidelines: Theme Development Best Practices @chip_bennett (Volume 1) Chip Bennett, WordCamp Toronto, 05 November 2011
  2. 2. Beyond the Guidelines: Theme Development Best Practices Audience Developers Themes intended to be hosted by WPORG Best Practices Theme Documentation Copyright Attribution / License Declaration Child-Theme Readiness Enqueueing Scripts and Stylesheets WordPress Coding Standards Related The WordPress Theme Repository http://www.slideshare.net/chipbennett/wordcamp-kc-the-wordpress-theme-repository How to Prepare and Submit Your Theme to the WPORG Theme Repository: http://www.slideshare.net/chipbennett/word-campstl-submittingathemetothethemerepository WordCamp Toronto: 05 November 2011
  3. 3. Theme Inline Documentation phpDoc ftw! WordCamp Toronto: 05 November 2011
  4. 4. Beyond the Guidelines: Theme Development Best Practices Why? <ul><li>You'll use it!
  5. 5. Auto-generation of Theme documentation/cross-reference
  6. 6. Built-in support: explains template file use, function input/output </li></ul>Use phpDoc standard <ul><ul><li>Syntax </li></ul></ul><ul><ul><ul><li>Short Description
  7. 7. Long Description
  8. 8. Tags </li></ul></ul></ul><ul><li>Page-level docblocks: </li></ul><ul><li>All template files
  9. 9. Inline docblocks: </li></ul><ul><ul><li>Function definitions, constants, global variables, classes </li></ul></ul>WordCamp Toronto: 05 November 2011 Theme Inline Documentation
  10. 10. Beyond the Guidelines: Theme Development Best Practices Example 1: template file undocumented WordCamp Toronto: 05 November 2011 Theme Inline Documentation Oenology Theme: index.php file, undocumented and uninformative
  11. 11. Beyond the Guidelines: Theme Development Best Practices Adding a page-level PHP docblock WordCamp Toronto: 05 November 2011 Theme Inline Documentation Basic PHP docblock structure: Page-level docblock content: <ul><li>Short Description
  12. 12. Long Description
  13. 13. @package tag
  14. 14. @copyright tag
  15. 15. @license tag </li></ul>Purpose: <ul><li>Describe purpose of template/functional file
  16. 16. Cross-reference functions used in the template file
  17. 17. Document copyright attribution and license declaration </li></ul>
  18. 18. Beyond the Guidelines: Theme Development Best Practices Example 2: index.php template file page-level docblock WordCamp Toronto: 05 November 2011 Theme Inline Documentation Oenology Theme: index.php page-level docblock: documented, informative
  19. 19. Beyond the Guidelines: Theme Development Best Practices Adding a function-level PHP docblock WordCamp Toronto: 05 November 2011 Theme Inline Documentation Function-level docblock content: <ul><li>Short Description
  20. 20. Long Description
  21. 21. @param tag
  22. 22. @return tag </li></ul>Purpose: <ul><li>Describe purpose of the function/global variable/constant/class
  23. 23. Cross-reference functions called within the function
  24. 24. Describe function parameter (input) datatypes, criticality, purpose
  25. 25. Describe function output datatype and purpose
  26. 26. Document copyright attribution (if borrowed/derived code) </li></ul>
  27. 27. Beyond the Guidelines: Theme Development Best Practices Example 3: function-level docblock WordCamp Toronto: 05 November 2011 Theme Inline Documentation Oenology Theme: function-level docblock, documents custom-function use
  28. 28. Copyright Attribution and License Declaration Credit where it's due and maintaining users' rights WordCamp Toronto: 05 November 2011
  29. 29. Beyond the Guidelines: Theme Development Best Practices Almost every Theme and Plugin is Doing It Wrong WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration Required <ul><li>License tag
  30. 30. License URI tag </li></ul>What's Missing <ul><li>Copyright Attribution
  31. 31. Derivative Themes
  32. 32. Incorporated Code
  33. 33. Bundled Resources </li></ul>Why are Copyright and License Important? <ul><li>Ensure end-user freedoms are preserved
  34. 34. Copyright requires ownership, and license requires copyright
  35. 35. Preserve chain of ownership/copyright/license
  36. 36. Borrowed code: give credit where it's due
  37. 37. Bundled resources: ensure license compatibility </li></ul>
  38. 38. Beyond the Guidelines: Theme Development Best Practices Theme Copyright/License Whichever license you plan to use, the process involves adding two elements to each source file of your program: a copyright notice ... and a statement of copying permission – GNU (GPL) <ul><ul><li>Copyright Notice </li></ul></ul><ul><ul><ul><ul><li>Format: Program Name, “Copyright” and/or “(C)”, Year, Owner </li></ul></ul></ul></ul>Oenology WordPress Theme, Copyright 2010 Chip Bennett <ul><li>Statement of Copying Permission </li></ul>This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public Licensealong with this program. If not, see <http://www.gnu.org/licenses/>. <ul><li>What Goes Where? </li><ul><li>style.css: primary copyright/license information
  39. 39. Template files: page- and function-level docblock tags </li><ul><li>@package or @link, @copyright, @license </li></ul></ul></ul>WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration
  40. 40. Beyond the Guidelines: Theme Development Best Practices Derivative Themes <ul><li>Include Copyright/License from original Theme with primary Copyright/License information in style.css </li></ul>Awesome Derivation WordPress Theme, (c) 2011 Chip Bennett Derived from Twenty Eleven WordPress Theme, (c) the WordPress team 2011, and released under the GNU GPL <ul><li>Be sure to retain full-text license (if included), or a link to the full-text license. </li></ul>WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration
  41. 41. Beyond the Guidelines: Theme Development Best Practices Incorporated Code (bundled functions, code snippets, etc.) <ul><li>Use function- or page-level PHP docblock Description and Tags to attribute </li><ul><li>@link
  42. 42. @copyright
  43. 43. @license </li></ul></ul>WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration Bundled Resources (fonts, images, icons, flash, scripts, etc.) <ul><li>Retain readme files (if included)
  44. 44. Document in Theme readme.txt or style.css </li><ul><li>Source link
  45. 45. Copyright
  46. 46. License/license link </li></ul></ul>
  47. 47. Child-Theme Readiness Make your Theme future-proof for user modifications WordCamp Toronto: 05 November 2011
  48. 48. Beyond the Guidelines: Theme Development Best Practices Help your users help themselves WordCamp Toronto: 05 November 2011 Child-Theme Readiness Encourage your users to use a Child Theme; assume that they will <ul><li>Proper use of get_template_directory() vs get_stylesheet_directory()
  49. 49. Contextual template-part file includes
  50. 50. Post-format template-part file includes
  51. 51. Advanced Child Theme overrides </li></ul>
  52. 52. Beyond the Guidelines: Theme Development Best Practices get_template_directory() vs. get_stylesheet_directory() WordCamp Toronto: 05 November 2011 Child-Theme Readiness get_stylesheet_directory()/get_stylesheet_directory_uri() <ul><li>Anything intended over-ridden by Child Themes </li></ul>get_template_directory()/get_template_directory_uri() <ul><li>Anything not intended to be over-ridden by Child Themes </li><ul><li>functions.php sub-file includes
  53. 53. Theme settings functional code
  54. 54. Enqueued stylesheets and scripts
  55. 55. Bundled resources </li></ul></ul>Template files and template-part files <ul><li>Use get_template_part() or locate_template() </li></ul>
  56. 56. Beyond the Guidelines: Theme Development Best Practices Template-part file overrides: contextual includes WordCamp Toronto: 05 November 2011 Child-Theme Readiness get_template_part( $file, $slug ) <ul><li>See also: get_header( $slug ), get_footer( $slug ), get_sidebar( $slug )
  57. 57. Facilitates context-specific Child Theme overrides
  58. 58. Relies on built-in cascade: </li><ul><li>Child Theme $file-$context.php
  59. 59. Parent Theme $file-$context.php
  60. 60. Child Theme $file.php
  61. 61. Parent Theme $file.php </li></ul><li>Examples </li><ul><li>In single.php: get_header( 'single' ) => header-single.php
  62. 62. In page.php: get_template_part( 'loop', 'page' ) => loop-page.php </li></ul></ul>Benefit: <ul><li>Parent Theme doesn’t have to include, e.g. loop-page.php, but enables Child Theme to override *specifically* in this context. </li></ul>
  63. 63. Beyond the Guidelines: Theme Development Best Practices Template-part file overrides: Post Format includes WordCamp Toronto: 05 November 2011 Child-Theme Readiness get_template_part( $file, get_post_format() ) <ul><li>Facilitates post format-specific Child Theme overrides
  64. 64. get_post_format() returns null for “standard”
  65. 65. Relies on same cascade, falls back to $file.php if post format is not defined (i.e. “standard”) for current post.
  66. 66. Examples </li><ul><li>get_template_part( 'entry', get_post_format() ) </li><ul><li>entry-aside.php
  67. 67. entry.php </li></ul></ul></ul>Benefit: <ul><li>Parent Theme doesn’t have to include custom markup for every post format type, but enables Child Theme to override *specific* post formats. </li></ul>
  68. 68. Beyond the Guidelines: Theme Development Best Practices Advanced Child Theme Overrides WordCamp Toronto: 05 November 2011 Child-Theme Readiness Hook all function calls into appropriate actions <ul><li>Facilitates un-hooking </li></ul>Incorrect <ul><li>Function called directly in functions.php </li></ul>Correct <ul><li>Function called inside a callback and hooked into appropriate action </li></ul>
  69. 69. Beyond the Guidelines: Theme Development Best Practices Advanced Child Theme Overrides WordCamp Toronto: 05 November 2011 Child-Theme Readiness <ul><li>Output the action in the template file: </li></ul>Custom Action Hooks <ul><li>Users can add content/functionality with a callback function, either in a Child Theme or even just a custom Plugin </li></ul><ul><li>Define the action hook with do_action() </li></ul>
  70. 70. Beyond the Guidelines: Theme Development Best Practices Advanced Child Theme Overrides WordCamp Toronto: 05 November 2011 Child-Theme Readiness Pluggable Functions vs. Custom Filter Hooks <ul><li>Pluggable functions allow entire function declaration to be overridden
  71. 71. Custom Filter hooks allow function output to be overridden </li></ul>Pluggable Functions <ul><li>Child Theme declares function with the same name </li></ul>Custom Filter Hooks <ul><li>Define custom filter via apply_filters( $hook, $output)
  72. 72. Child Theme hooks callback into add_filter() call </li></ul>
  73. 73. Enqueueing Stylesheets and Scripts Making your stylesheets and scripts play nicely with others WordCamp Toronto: 05 November 2011
  74. 74. Beyond the Guidelines: Theme Development Best Practices Because Themes Don't Exist in a Vacuum WordCamp Toronto: 05 November 2011 Enqueueing Stylesheets and Scripts Required <ul><li>Enqueue rather than hard-code in document head </li></ul>What's Missing <ul><li>Admin vs. front-end
  75. 75. Admin context
  76. 76. Use of core-bundled scripts </li></ul>Why is proper script/stylesheet enqueueing Important? <ul><li>Ensure dependencies are met
  77. 77. Ensure forward-compatibility
  78. 78. Play nicely with Plugins and core </li></ul>
  79. 79. Beyond the Guidelines: Theme Development Best Practices WordCamp Toronto: 05 November 2011 Enqueueing Stylesheets and Scripts Always use the core-bundled version of scripts <ul><li>e.g. jQuery and jQuery Plugins </li><ul><li>Note: WordPress 3.3 will include all jQuery Plugins, not just ones used by core </li></ul><li>Do not replace core-bundled scripts with Theme-bundled or CDN-hosted versions, even on the front end
  80. 80. Other Plugins will (rightfully) expect the core-bundled version to be registered </li></ul>Enqueueing front-end scripts <ul><li>Appropriate hook: wp_enqueue_scripts
  81. 81. Use the $deps parameter in wp_enqueue_script() call
  82. 82. For safety: if ( ! is_admin() )
  83. 83. Bonus Tip: enqueueing comment-reply.js </li></ul>
  84. 84. Beyond the Guidelines: Theme Development Best Practices WordCamp Toronto: 05 November 2011 Enqueueing Stylesheets and Scripts Enqueueing admin scripts <ul><li>Enqueue only on your Theme's settings page!
  85. 85. Appropriate hook: admin_print_scripts-$hook
  86. 86. $hook = $context_$pagename
  87. 87. $context </li><ul><li>add_*_page() function call </li><ul><li>add_theme_page() => $context = appearance_page </li></ul></ul><li>$pagename </li><ul><li>add_*_page()$menu_slug parameter </li><ul><li>add_theme_page( $page_title, $menu_title, $capability, $menu_slug , $function ) </li></ul></ul><li>Example: admin_print_scripts_appearance_page_oenology-settings </li></ul>
  88. 88. WordPress Coding Standards ...some of them are useful for Theme developers, too! WordCamp Toronto: 05 November 2011
  89. 89. Beyond the Guidelines: Theme Development Best Practices WordCamp Toronto: 05 November 2011 WordPress Coding Standards Yoda Conditions <ul><li>When doing logical comparisons, always put the variable on the right side. </li></ul>Ternary Operators <ul><li>If you don't use a variable more than once, don't create it
  90. 90. Always have them test if the statement is true, not false </li><ul><li>Exception: ! is_empty() </li></ul></ul>Brace Usage <ul><li>Braces should be used for multiline blocks
  91. 91. If any related set of blocks is more than one line long then all of the related blocks should be enclosed in braces
  92. 92. Loops should always contain braces
  93. 93. Single line blocks can omit braces for brevity </li></ul>
  94. 94. Beyond the Guidelines: Theme Development Best Practices WordCamp Toronto: 05 November 2011 WordPress Coding Standards Single/Double Quote Usage <ul><li>Use where appropriate.
  95. 95. If you're not evaluating anything in the string, use single quotes. </li></ul>Naming Conventions <ul><li>Variable/function names: use lowercase letters (never camelCase); separate words via underscores
  96. 96. File names: name descriptively; use lowercase letters; separate words via hyphens </li></ul>Space Usage <ul><li>After commas
  97. 97. On both sides of logical and assignment operators
  98. 98. On both sides of the opening and closing parenthesis: </li><ul><li>if, elseif, foreach, for and switch blocks </li></ul><li>On both side of concatenations </li></ul>Indentation <ul><li>Should always reflect logical structure
  99. 99. Use real tabs and not spaces
  100. 100. For associative arrays, values should start on a new line
  101. 101. When mixing PHP and HTML together, indent PHP blocks to match the surrounding HTML code.
  102. 102. Closing PHP blocks should match the same indentation level as the opening block. </li></ul>
  103. 103. Feedback You’ve heard from me; now I want to hear from you WordCamp Toronto: 05 November 2011
  104. 104. Beyond the Guidelines: Theme Development Best Practices Open Forum Feedback, criticism, and ideas for the WordPress Theme Repository: <ul><ul><li>Theme Repository: </li><ul><li>Theme Selection,
  105. 105. Theme Quality,
  106. 106. Child Themes/Theme Frameworks
  107. 107. etc. </li></ul><li>Theme Review </li><ul><li>Submission/Review/Approval Process
  108. 108. Theme Review Guidelines </li></ul></ul></ul>WordCamp Toronto: 05 November 2011
  109. 109. Resources Sites and information referenced, and further reading WordCamp Toronto: 05 November 2011
  110. 110. Beyond the Guidelines: Theme Development Best Practices Resources Theme Inline Documentation <ul><ul><li>phpDoc Standard: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
  111. 111. phpDoc Generator: http://www.phpdoc.org/
  112. 112. WordPress Inline Doc Standard (Codex): http://codex.wordpress.org/Inline_Documentation </li></ul></ul>Copyright Attribution/License Declaration <ul><ul><li>GNU.org How-To: http://www.gnu.org/licenses/gpl-howto.html </li></ul></ul>Child Theme Readiness <ul><ul><li>get_stylesheet_directory(): http://codex.wordpress.org/Function_Reference/get_stylesheet_directory
  113. 113. get_template_directory(): http://codex.wordpress.org/Function_Reference/get_template_directory
  114. 114. get_template_part(): http://codex.wordpress.org/Function_Reference/get_template_part
  115. 115. WordPress Plugin API: http://codex.wordpress.org/Plugin_API </li></ul></ul>Script/Stylesheet Enqueueing <ul><ul><li>wp_enqueue_script(): http://codex.wordpress.org/Function_Reference/wp_enqueue_script </li></ul></ul>WordPress Coding Standards <ul><ul><li>WordPress Coding Standards: http://codex.wordpress.org/WordPress_Coding_Standards </li></ul></ul>Theme Review <ul><ul><li>Theme Review Team Site: http://make.wordpress.org/themes
  116. 116. Theme Review Guidelines : http://codex.wordpress.org/Theme_Review
  117. 117. Theme Unit Tests: http://codex.wordpress.org/Theme_Unit_Test </li></ul></ul>More From Me <ul><ul><li>Oenology Theme: http://wordpress.org/extend/themes/oenology
  118. 118. WordCamp KC Presentation: http://www.slideshare.net/chipbennett/wordcamp-kc-the-wordpress-theme-repository
  119. 119. WordCamp STL Presentation: http://www.slideshare.net/chipbennett/word-campstl-submittingathemetothethemerepository </li></ul></ul>WordCamp Toronto: 05 November 2011
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×