Your SlideShare is downloading. ×
0
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
WordCamp TOR: Beyond The Guidelines - Theme Development Best Practices (Vol 1)
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

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

4,610

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 …

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
0 Comments
6 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
4,610
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
106
Comments
0
Likes
6
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

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

×