Permalink
Browse files

Add stable of tha and check for beta release before include

  • Loading branch information...
1 parent 7f46405 commit 778e3c13be247fc979fa7e5376bff98fc197955a @bueltge committed Oct 17, 2012
Showing with 367 additions and 1 deletion.
  1. +4 −1 functions.php
  2. +63 −0 inc/tha-1.0/README.md
  3. +73 −0 inc/tha-1.0/tha-example-index.php
  4. +227 −0 inc/tha-1.0/tha-theme-hooks.php
View
@@ -71,7 +71,10 @@ function documentation_setup() {
*/
add_theme_support( 'tha_hooks', array( 'all' ) );
// include the file from this project, if theme supported
- require_if_theme_supports( 'tha_hooks', get_template_directory() . '/inc/tha/tha-theme-hooks.php' );
+ if ( file_exists( get_template_directory() . '/inc/tha/tha-theme-hooks.php' ) ) // beta release from repo
+ require_if_theme_supports( 'tha_hooks', get_template_directory() . '/inc/tha/tha-theme-hooks.php' );
+ else
+ require_if_theme_supports( 'tha_hooks', get_template_directory() . '/inc/tha-1.0/tha-theme-hooks.php' );
// Add default posts and comments RSS feed links to <head>.
add_theme_support( 'automatic-feed-links' );
View
@@ -0,0 +1,63 @@
+# Theme Hook Alliance #
+
+## Status ##
+**1.0**
+
+## What? ##
+Child theme authors and plugin developers need a consistent set of entry points to allow for easy customization and altering of functionality. Core WordPress offers a suite of [action hooks](http://codex.wordpress.org/Plugin_API/Action_Reference/) and [template tags](http://codex.wordpress.org/Template_tags) but does not cover many of the common use cases. The Theme Hook Alliance is a community-driven effort to agree on a set of third-party action hooks that THA themes pledge to implement in order to give that desired consistency.
+
+## Why? ##
+There have been [discussions](http://www.wptavern.com/forum/themes-templates/494-standard-theme-hook-names.html) about implementing a common set of hooks, a [Trac ticket](http://core.trac.wordpress.org/ticket/18561#comment:92) and even an [initial pass](http://codex.wordpress.org/User_talk:Dcole07) at implementing something similar. However, for whatever reason[s], these efforts have not gained traction. I proposed this third-party solution [here](http://literalbarrage.org/blog/2012/06/29/wordpress-theme-hook-alliance) and this project is intended to be an implementation of these goals.
+
+## What about WordPress? ##
+As stated above, there have been attempts to have something along these lines added to WordPress Core in the past and, while they have generally been seen as good ideas, they have remained as such.
+
+Taking this out of the realm of Core and into the third-party realm is a bit of a risky proposition, to be sure. If the conventions laid out below are not adopted in a widespread fashion, this effort will ultimately fail.
+
+However, this is no reason to wait. Child themes have recently been approved for release in the official [Themes Repository](http://wordpress.org/extend/themes) and plugin authors continue to need more reliable entry points into WordPress' content flow so as to avoid nasty hacks like output buffering.
+
+### When Core does it, Core wins ###
+A small note: none of the proposed theme hooks are intended to replace or rewrite existing WordPress functionality. So, for instance, if a desired result can be obtained by filtering the output of e.g. `the_content()`, there is no need to create an entirely new hook. Therefore, any functions that duplicate work Core performs already should be rejected immediately.
+
+### What if Core adds some (or all) of these filters? ###
+If this idea gains enough traction, there is a chance that a partial, or even full, portion of these hooks will make their way into Core. When/if this occurs, we can simply update `tha-theme-hooks.php` to include the new `do_action()` calls at the appropriate places. Then, THA users will simply need to update their copy of `tha-theme-hooks.php` to take advantage.
+
+For example, if Core were to introduce a `before_header()` hook, we could (in theory) simply alter `tha_header_before()` as follows
+
+```php
+ function tha_header_before() {
+ do_action( 'tha_header_before' );
+ do_action( 'before_header' );
+ }
+```
+
+This would allow all themes using the THA hooks to avoid rewriting/refactoring in the case of a Core change.
+
+## Conventions ##
+
+* Hooks should be of the form `tha_` + `[section of the theme]` + `_[placement within block]`.
+* Hooks should be named based upon the generally-accepted semantic name for the section of a theme they cover, e.g., `tha_content_*` should refer to the section/block of a theme containing the content (or "The Loop"), while `tha_sidebar_*` would refer to the sidebars generally called by `get_sidebar()`.
+* Hooks should be suffixed based upon their placement within a block.
+ * Hooks immediately *preceding* a block should use `_before`.
+ * Hooks immediately *following* a block should use `_after`.
+ * Hooks placed at the very *beginning* of a block should use `_top`.
+ * Hooks placed at the very *end* of a block should use `_bottom`.
+* If the theme section covered by a hook can contain multiple semantic elements, it should be pluralized. (Primarily applies to `tha_sidebars_before/after` in the early goings.)
+
+## Usage ##
+
+1. Copy `tha-theme-hooks.php` to a directory inside of your theme; say, `include/`, for instance.
+2. Include `tha-theme-hooks.php` via `<?php include( 'include/tha-theme-hooks.php' ); ?>` in your `functions.php` or similar.
+3. Using `tha-example-index.php` as a guide, *be sure to implement all of the hooks described in `tha-theme-hooks.php` in order to offer full compatibility*.
+4. Profit!
+
+## Core Compatibility ##
+Working on it!
+
+## THA-Compatible Themes ##
+* **In-Progress**
+ * [Oenology](http://www.chipbennett.net/themes/oenology/) by Chip Bennett ([github](https://github.com/chipbennett/oenology))
+ * [Elbee Elgee](http://literalbarrage.org/blog/code/elbee-elgee) by Doug Stewart ([bitbucket](https://bitbucket.org/zamoose/elbee-elgee))
+* **Full Support**
+ * [The Bootstrap](http://wordpress.org/extend/themes/the-bootstrap) by Konstantin Obenland ([github](https://github.com/obenland/the-bootstrap))
+ * [Documentation](https://github.com/bueltge/Documentation) by Frank Bültge
@@ -0,0 +1,73 @@
+<html>
+<head>
+ <?php tha_head_top(); ?>
+ <title><?php wp_title(); ?></title>
+ <link rel="stylesheet" href="<?php echo get_stylesheet_uri(); ?>" type="text/css" media="all" />
+ <?php tha_head_bottom(); ?>
+ <?php wp_head(); ?>
+</head>
+<body <?php body_class(); ?>>
+
+ <?php tha_header_before(); ?>
+ <div id="header">
+ <?php tha_header_top(); ?>
+ <h1><?php bloginfo( 'name' ); ?></h1>
+ <p class="dscription"><?php bloginfo( 'description' ); ?></p>
+ <?php tha_header_bottom(); ?>
+ </div><!-- #header -->
+ <?php tha_header_after(); ?>
+
+ <?php tha_content_before(); ?>
+ <div id="content">
+ <?php tha_content_top(); ?>
+
+ <!-- This roughly encapsulates The Loop portion of the layout -->
+ <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
+
+ <?php tha_entry_before(); ?>
+ <!-- Post Entry Begin -->
+ <div <?php post_class( 'entry' ); ?>>
+ <?php tha_entry_top(); ?>
+ <h2><?php the_title(); ?></h2>
+ <div class="itemtext">
+ <?php the_content(); ?>
+ </div><!-- .itemtext -->
+ <?php tha_entry_bottom(); ?>
+ </div>
+ <!-- Post Entry End -->
+ <?php tha_entry_after(); ?>
+
+ <?php endwhile; endif; ?>
+ <!-- Close The Loop -->
+
+ <?php tha_comments_before(); ?>
+ <!-- Post Comments Begin -->
+ <?php comments_template(); ?>
+ <!-- post Comments End -->
+ <?php tha_comments_after(); ?>
+
+ <?php tha_content_bottom(); ?>
+ </div><!-- #content -->
+ <?php tha_content_after(); ?>
+
+ <?php tha_sidebars_before(); ?>
+ <div id="sidebar">
+ <?php tha_sidebar_top(); ?>
+ <?php dynamic_sidebar( 'sidebar' ); ?>
+ <?php tha_sidebar_bottom(); ?>
+ </div><!-- #sidebar-->
+ <?php tha_sidebars_after(); ?>
+
+ <?php tha_footer_before(); ?>
+ <div id="footer">
+ <?php tha_footer_top(); ?>
+
+ <h3>Footer</h3>
+ <p>This is some sample footer text.</p>
+
+ <?php tha_footer_bottom(); ?>
+ </div><!-- #footer -->
+ <?php tha_footer_after(); ?>
+ <?php wp_footer(); ?>
+</body>
+</html>
@@ -0,0 +1,227 @@
+<?php
+/**
+* Theme Hook Alliance hook stub list.
+*
+* @package themehookalliance
+* @version 1.0-draft
+* @since 1.0-draft
+* @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU General Public License, v2 (or newer)
+*
+* 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 2 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.
+*/
+
+/**
+ * Define the version of THA support, in case that becomes useful down the road.
+ */
+define( 'THA_HOOKS_VERSION', '1.0-draft' );
+
+/**
+ * Themes and Plugins can check for tha_hooks using current_theme_supports( 'tha_hooks', $hook )
+ * to determine whether a theme declares itself to support this specific hook type.
+ *
+ * Example:
+ * <code>
+ * // Declare support for all hook types
+ * add_theme_support( 'tha_hooks', array( 'all' ) );
+ *
+ * // Declare support for certain hook types only
+ * add_theme_support( 'tha_hooks', array( 'header', 'content', 'footer' ) );
+ * </code>
+ */
+add_theme_support( 'tha_hooks', array(
+
+ /**
+ * As a Theme developer, use the 'all' parameter, to declare support for all
+ * hook types.
+ * Please make sure you then actually reference all the hooks in this file,
+ * Plugin developers depend on it!
+ */
+ 'all',
+
+ /**
+ * Themes can also choose to only support certain hook types.
+ * Please make sure you then actually reference all the hooks in this type
+ * family.
+ *
+ * When the 'all' parameter was set, specific hook types do not need to be
+ * added explicitly.
+ */
+ 'head',
+ 'header',
+ 'content',
+ 'entry',
+ 'comments',
+ 'sidebars',
+ 'sidebar',
+ 'footer',
+
+ /**
+ * If/when WordPress Core implements similar methodology, Themes and Plugins
+ * will be able to check whether the version of THA supplied by the theme
+ * supports Core hooks.
+ */
+// 'core'
+) );
+
+/**
+ * Determines, whether the specific hook type is actually supported.
+ *
+ * Plugin developers should always check for the support of a <strong>specific</strong>
+ * hook type before hooking a callback function to a hook of this type.
+ *
+ * Example:
+ * <code>
+ * if ( current_theme_supports( 'tha_hooks', 'header' ) )
+ * add_action( 'tha_head_top', 'prefix_header_top' );
+ * </code>
+ *
+ * @param bool $bool true
+ * @param array $args The hook type being checked
+ * @param array $registered All registered hook types
+ *
+ * @return bool
+ */
+function tha_current_theme_supports( $bool, $args, $registered ) {
+ return in_array( $args[0], $registered[0] ) || in_array( 'all', $registered[0] );
+}
+add_filter( 'current_theme_supports-tha_hooks', 'tha_current_theme_supports', 10, 3 );
+
+/**
+* HTML <head> hooks
+*
+* $tha_supports[] = 'head';
+*/
+function tha_head_top() {
+ do_action( 'tha_head_top' );
+}
+
+function tha_head_bottom() {
+ do_action( 'tha_head_bottom' );
+}
+
+
+/**
+* Semantic <header> hooks
+*
+* $tha_supports[] = 'header';
+*/
+function tha_header_before() {
+ do_action( 'tha_header_before' );
+}
+
+function tha_header_after() {
+ do_action( 'tha_header_after' );
+}
+
+function tha_header_top() {
+ do_action( 'tha_header_top' );
+}
+
+function tha_header_bottom() {
+ do_action( 'tha_header_bottom' );
+}
+
+/**
+* Semantic <content> hooks
+*
+* $tha_supports[] = 'content';
+*/
+function tha_content_before() {
+ do_action( 'tha_content_before' );
+}
+
+function tha_content_after() {
+ do_action( 'tha_content_after' );
+}
+
+function tha_content_top() {
+ do_action( 'tha_content_top' );
+}
+
+function tha_content_bottom() {
+ do_action( 'tha_content_bottom' );
+}
+
+/**
+* Semantic <entry> hooks
+*
+* $tha_supports[] = 'entry';
+*/
+function tha_entry_before() {
+ do_action( 'tha_entry_before' );
+}
+
+function tha_entry_after() {
+ do_action( 'tha_entry_after' );
+}
+
+function tha_entry_top() {
+ do_action( 'tha_entry_top' );
+}
+
+function tha_entry_bottom() {
+ do_action( 'tha_entry_bottom' );
+}
+
+/**
+* Comments block hooks
+*
+* $tha_supports[] = 'comments';
+*/
+function tha_comments_before() {
+ do_action( 'tha_comments_before' );
+}
+
+function tha_comments_after() {
+ do_action( 'tha_comments_after' );
+}
+
+/**
+* Semantic <sidebar> hooks
+*
+* $tha_supports[] = 'sidebar';
+*/
+function tha_sidebars_before() {
+ do_action( 'tha_sidebars_before' );
+}
+
+function tha_sidebars_after() {
+ do_action( 'tha_sidebars_after' );
+}
+
+function tha_sidebar_top() {
+ do_action( 'tha_sidebar_top' );
+}
+
+function tha_sidebar_bottom() {
+ do_action( 'tha_sidebar_bottom' );
+}
+
+/**
+* Semantic <footer> hooks
+*
+* $tha_supports[] = 'footer';
+*/
+function tha_footer_before() {
+ do_action( 'tha_footer_before' );
+}
+
+function tha_footer_after() {
+ do_action( 'tha_footer_after' );
+}
+
+function tha_footer_top() {
+ do_action( 'tha_footer_top' );
+}
+
+function tha_footer_bottom() {
+ do_action( 'tha_footer_bottom' );
+}

0 comments on commit 778e3c1

Please sign in to comment.