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

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!



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




Example 1: template file undocumented



Oenology Theme: index.php file, undocumented and uninformative


Adding a page-level PHP docblock



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


Example 2: index.php template file page-level docblock



Oenology Theme: index.php page-level docblock: documented, informative


Adding a function-level PHP docblock



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)


Example 3: function-level docblock



Oenology Theme: function-level docblock, documents custom-function use

Copyright Attribution and License Declaration

Credit where it's due and maintaining users' rights



Almost every Theme and Plugin is Doing It Wrong



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


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




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.




Incorporated Code (bundled functions, code snippets, etc.)Use function- or page-level PHP docblock Description and Tags to attribute@link

@copyright

@license



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



Help your users help themselves



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


get_template_directory() vs. get_stylesheet_directory()



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


Template-part file overrides: contextual includes



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.


Template-part file overrides: Post Format includes



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.


Advanced Child Theme Overrides



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





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





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



Because Themes Don't Exist in a Vacuum



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




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




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!





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




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



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


Resources

Sites and information referenced, and further reading



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


Click to edit the title text formatClick to edit Master title style

11/5/11



11/5/11


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


Technology

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