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

Beyond the Guidelines: Theme Development Best Practices @chip_bennett (Volume 1) Chip Bennett, WordCamp Toronto, 05 November 2011

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

Theme Inline Documentation phpDoc ftw! WordCamp Toronto: 05 November 2011

Beyond the Guidelines: Theme Development Best Practices Why?
You'll use it!
Auto-generation of Theme documentation/cross-reference
Built-in support: explains template file use, function input/output
Use phpDoc standard
Syntax
Short Description
Long Description
Tags
Page-level docblocks:
All template files
Inline docblocks:
Function definitions, constants, global variables, classes
WordCamp Toronto: 05 November 2011 Theme Inline Documentation

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

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
Long Description
@package tag
@copyright tag
@license tag
Purpose:
Describe purpose of template/functional file
Cross-reference functions used in the template file
Document copyright attribution and license declaration

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

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
Long Description
@param tag
@return tag
Purpose:
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)

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

Copyright Attribution and License Declaration Credit where it's due and maintaining users' rights WordCamp Toronto: 05 November 2011

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
License URI tag
What's Missing
Copyright Attribution
Derivative Themes
Incorporated Code
Bundled Resources
Why are Copyright and License Important?
Ensure end-user freedoms are preserved
Copyright requires ownership, and license requires copyright
Preserve chain of ownership/copyright/license
Borrowed code: give credit where it's due
Bundled resources: ensure license compatibility

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
Template files: page- and function-level docblock tags
@package or @link, @copyright, @license
WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration

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

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
@copyright
@license
WordCamp Toronto: 05 November 2011 Copyright Attribution and License Declaration Bundled Resources (fonts, images, icons, flash, scripts, etc.)
Retain readme files (if included)
Document in Theme readme.txt or style.css
Source link
Copyright
License/license link

Child-Theme Readiness Make your Theme future-proof for user modifications WordCamp Toronto: 05 November 2011

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()
Contextual template-part file includes
Post-format template-part file includes
Advanced Child Theme overrides

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
Theme settings functional code
Enqueued stylesheets and scripts
Bundled resources
Template files and template-part files
Use get_template_part() or locate_template()

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 )
Facilitates context-specific Child Theme overrides
Relies on built-in cascade:
Child Theme $file-$context.php
Parent Theme $file-$context.php
Child Theme $file.php
Parent Theme $file.php
Examples
In single.php: get_header( 'single' ) => header-single.php
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.

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
get_post_format() returns null for “standard”
Relies on same cascade, falls back to $file.php if post format is not defined (i.e. “standard”) for current post.
Examples
get_template_part( 'entry', get_post_format() )
entry-aside.php
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.

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

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()

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
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)
Child Theme hooks callback into add_filter() call

Enqueueing Stylesheets and Scripts Making your stylesheets and scripts play nicely with others WordCamp Toronto: 05 November 2011

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
Admin context
Use of core-bundled scripts
Why is proper script/stylesheet enqueueing Important?
Ensure dependencies are met
Ensure forward-compatibility
Play nicely with Plugins and core

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
Other Plugins will (rightfully) expect the core-bundled version to be registered
Enqueueing front-end scripts
Appropriate hook: wp_enqueue_scripts
Use the $deps parameter in wp_enqueue_script() call
For safety: if ( ! is_admin() )
Bonus Tip: enqueueing comment-reply.js

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!
Appropriate hook: admin_print_scripts-$hook
$hook = $context_$pagename
$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

WordPress Coding Standards ...some of them are useful for Theme developers, too! WordCamp Toronto: 05 November 2011

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
Always have them test if the statement is true, not false
Exception: ! is_empty()
Brace Usage
Braces should be used for multiline blocks
If any related set of blocks is more than one line long then all of the related blocks should be enclosed in braces
Loops should always contain braces
Single line blocks can omit braces for brevity

Beyond the Guidelines: Theme Development Best Practices WordCamp Toronto: 05 November 2011 WordPress Coding Standards Single/Double Quote Usage
Use where appropriate.
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
File names: name descriptively; use lowercase letters; separate words via hyphens
Space Usage
After commas
On both sides of logical and assignment operators
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
Use real tabs and not spaces
For associative arrays, values should start on a new line
When mixing PHP and HTML together, indent PHP blocks to match the surrounding HTML code.
Closing PHP blocks should match the same indentation level as the opening block.

Feedback You’ve heard from me; now I want to hear from you WordCamp Toronto: 05 November 2011

Beyond the Guidelines: Theme Development Best Practices Open Forum Feedback, criticism, and ideas for the WordPress Theme Repository:
Theme Repository:
Theme Selection,
Theme Quality,
Child Themes/Theme Frameworks
etc.
Theme Review
Submission/Review/Approval Process
Theme Review Guidelines
WordCamp Toronto: 05 November 2011

Resources Sites and information referenced, and further reading WordCamp Toronto: 05 November 2011

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
phpDoc Generator: http://www.phpdoc.org/
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
get_template_directory(): http://codex.wordpress.org/Function_Reference/get_template_directory
get_template_part(): http://codex.wordpress.org/Function_Reference/get_template_part
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
Theme Review Guidelines : http://codex.wordpress.org/Theme_Review
Theme Unit Tests: http://codex.wordpress.org/Theme_Unit_Test
More From Me
Oenology Theme: http://wordpress.org/extend/themes/oenology
WordCamp KC Presentation: http://www.slideshare.net/chipbennett/wordcamp-kc-the-wordpress-theme-repository
WordCamp STL Presentation: http://www.slideshare.net/chipbennett/word-campstl-submittingathemetothethemerepository
WordCamp Toronto: 05 November 2011

http://a0.twimg.com	6
http://us-w1.rockmelt.com	1
http://paper.li	1
https://si0.twimg.com	1
https://twitter.com	1

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

by Chip Bennett

Accessibility

Categories

Upload Details

Usage Rights

5 Embeds 10

Statistics

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