wordcamp tor: beyond the guidelines - theme development best practices (vol 1)
TRANSCRIPT
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
AudienceDevelopers Themes intended to be hosted by WPORGBest PracticesTheme DocumentationCopyright Attribution / License DeclarationChild-Theme ReadinessEnqueueing Scripts and StylesheetsWordPress Coding StandardsRelatedThe WordPress Theme Repositoryhttp://www.slideshare.net/chipbennett/wordcamp-kc-the-wordpress-theme-repositoryHow 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 standardSyntax
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
RequiredLicense tag
License URI tag
What's MissingCopyright 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/LicenseWhichever 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 BennettStatement 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 .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 ThemesInclude Copyright/License from original Theme with primary Copyright/License information in style.css
Awesome Derivation WordPress Theme, (c) 2011 Chip BennettDerived from Twenty Eleven WordPress Theme, (c) the WordPress team 2011, and released under the GNU GPLBe 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.cssSource 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 willProper 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 Themesfunctions.php sub-file includes
Theme settings functional code
Enqueued stylesheets and scripts
Bundled resources
Template files and template-part filesUse 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
ExamplesIn single.php: get_header( 'single' ) => header-single.php
In page.php: get_template_part( 'loop', 'page' ) => loop-page.php
Benefit:Parent Theme doesnt 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.
Examplesget_template_part( 'entry', get_post_format() )entry-aside.php
entry.php
Benefit:Parent Theme doesnt 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 actionsFacilitates un-hooking
IncorrectFunction called directly in functions.php
CorrectFunction 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 HooksUsers 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 HooksPluggable functions allow entire function declaration to be overridden
Custom Filter hooks allow function output to be overridden
Pluggable FunctionsChild Theme declares function with the same name
Custom Filter HooksDefine 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
RequiredEnqueue rather than hard-code in document head
What's MissingAdmin 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 scriptse.g. jQuery and jQuery PluginsNote: 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 scriptsAppropriate 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 scriptsEnqueue only on your Theme's settings page!
Appropriate hook: admin_print_scripts-$hook
$hook = $context_$pagename
$contextadd_*_page() function calladd_theme_page() => $context = appearance_page
$pagenameadd_*_page()$menu_slug parameteradd_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 ConditionsWhen doing logical comparisons, always put the variable on the right side.
Ternary OperatorsIf you don't use a variable more than once, don't create it
Always have them test if the statement is true, not falseException: ! is_empty()
Brace UsageBraces 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 UsageUse where appropriate.
If you're not evaluating anything in the string, use single quotes.
Naming ConventionsVariable/function names: use lowercase letters (never camelCase); separate words via underscores
File names: name descriptively; use lowercase letters; separate words via hyphens
Space UsageAfter 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
IndentationShould 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
Youve heard from me; now I want to hear from you
WordCamp Toronto: 05 November 2011
Beyond the Guidelines: Theme Development Best Practices
Open ForumFeedback, criticism, and ideas for the WordPress Theme Repository: Theme Repository: Theme Selection,
Theme Quality,
Child Themes/Theme Frameworks
etc.
Theme ReviewSubmission/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
ResourcesTheme Inline DocumentationphpDoc 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 DeclarationGNU.org How-To: http://www.gnu.org/licenses/gpl-howto.html
Child Theme Readinessget_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 Enqueueingwp_enqueue_script(): http://codex.wordpress.org/Function_Reference/wp_enqueue_script
WordPress Coding StandardsWordPress Coding Standards: http://codex.wordpress.org/WordPress_Coding_Standards
Theme ReviewTheme 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 MeOenology 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
Click to edit the title text formatClick to edit Master title style
11/5/11
WordCamp Toronto: 05 November 2011
Click to edit the title text formatClick to edit Master title style
11/5/11
WordCamp Toronto: 05 November 2011
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelEighth Outline Level
Ninth Outline LevelClick to edit Master text stylesSecond levelThird levelFourth levelFifth level
Click to edit the title text formatClick to edit Master title style
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelEighth Outline Level
Ninth Outline LevelClick to edit Master text styles
11/5/11
WordCamp Toronto: 05 November 2011