The document discusses best practices for WordPress theme development, including using inline documentation, proper copyright and licensing, making themes child-theme ready, correctly enqueueing scripts and stylesheets, and following WordPress coding standards. It provides examples and explanations for each topic.

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: Short Description

12. Long Description

13. @package tag

14. @copyright tag

15. @license tag 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: Short Description

20. Long Description

21. @param tag

22. @return tag 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 @link

42. @copyright

43. @license 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 Selection,

105. Theme Quality,

106. Child Themes/Theme Frameworks

107. etc. 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