Skip to content
This repository
Browse code

Think I've got this one ready for public comment.

  • Loading branch information...
commit 233e1e80a3c7eebfd9813c421afcfe9b584f84cb 1 parent 15b7b7e
Doug Stewart authored
34  README.md
Source Rendered
... ...
@@ -1,11 +1,36 @@
1 1
 # Theme Hook Alliance #
2 2
 
  3
+## Status ##
  4
+**DRAFT**
  5
+
3 6
 ## What? ##
4 7
 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.
5 8
 
6 9
 ## Why? ##
7 10
 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.
8 11
 
  12
+## What about WordPress? ##
  13
+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.
  14
+
  15
+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.
  16
+
  17
+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.
  18
+
  19
+### When Core does it, Core wins ###
  20
+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.
  21
+
  22
+### What if Core adds some (or all) of these filters? ###
  23
+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.
  24
+
  25
+For example, if Core were to introduce a `before_header()` hook, we could (in theory) simply alter `tha_header_before()` as follows
  26
+
  27
+	function tha_header_before() {
  28
+		do_action( 'tha_header_before' );
  29
+		do_action( 'before_header' );
  30
+	}
  31
+
  32
+This would allow all themes using the THA hooks to avoid rewriting/refactoring in the case of a Core change.
  33
+
9 34
 ## Conventions ##
10 35
 
11 36
 * Hooks should be of the form 	`tha_` + `[section of the theme]` + `_[placement within block]`.
@@ -17,4 +42,13 @@ There have been [discussions](http://www.wptavern.com/forum/themes-templates/494
17 42
 	* Hooks placed at the very *end* of a block should use `_bottom`.
18 43
 * 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.)
19 44
 
  45
+## Usage ##
  46
+
  47
+1. Copy `tha-theme-hooks.php` to a directory inside of your theme; say, `include/`, for instance.
  48
+2. Include `tha-theme-hooks.php` via `<?php include( 'include/tha-theme-hooks.php' ); ?>` in your `functions.php` or similar.
  49
+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*.
  50
+4. Profit!
  51
+
20 52
 ## Core Compatibility ##
  53
+None, at the moment.
  54
+
18  tha-example-index.php
@@ -19,6 +19,24 @@
19 19
 	<div id="content">
20 20
 	<?php tha_content_top(); ?>
21 21
 
  22
+		<!-- This roughly encapsulates The Loop portion of the layout -->
  23
+		<?php tha_entry_before(); ?>
  24
+		<div class="entry">
  25
+			<?php tha_entry_top(); ?>
  26
+			<h2>This is the title</h2>
  27
+			<div class="itemtext">
  28
+				Lorem ipsum and all that rot.
  29
+			</div><!-- .itemtext -->
  30
+			<?php tha_entry_bottom(); ?>
  31
+		</div>
  32
+		<?php tha_entry_after(); ?>
  33
+		<!-- Close The Loop -->
  34
+		
  35
+		<?php tha_comments_before(); ?>
  36
+		
  37
+		<!-- comments_form() or similar goes here -->
  38
+		
  39
+		<?php tha_comments_after(); ?>
22 40
 	<?php tha_content_bottom(); ?>
23 41
 	</div><!-- #content -->
24 42
 	<?php tha_content_after(); ?>
36  tha-theme-hooks.php
@@ -3,6 +3,8 @@
3 3
 * Theme Hook Alliance hook stub list.
4 4
 *
5 5
 * @package 		themehookalliance
  6
+* @version		1.0-draft
  7
+* @since		1.0-draft
6 8
 * @license		http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU General Public License, v2 (or newer)
7 9
 *
8 10
 * This program is free software; you can redistribute it and/or modify
@@ -22,6 +24,10 @@
22 24
  */
23 25
 define( 'THA_HOOKS_SUPPORT', true );
24 26
 /**
  27
+ * Define the version of THA support, in case that becomes useful down the road.
  28
+ */
  29
+define( 'THA_HOOKS_VERSION', '1.0-draft')
  30
+/**
25 31
  * If/when WordPress Core implements similar methodology, themes and plugins will be
26 32
  * able to check whether the version of THA supplied by the theme supports Core
27 33
  * hooks.
@@ -79,6 +85,36 @@ function tha_content_bottom() {
79 85
 }
80 86
 
81 87
 /**
  88
+* Semantic <entry> hooks
  89
+*/
  90
+function tha_entry_before() {
  91
+	do_action( 'tha_entry_before' );
  92
+}
  93
+
  94
+function tha_entry_after() {
  95
+	do_action( 'tha_entry_after' );
  96
+}
  97
+
  98
+function tha_entry_top() {
  99
+	do_action( 'tha_entry_top' );
  100
+}
  101
+
  102
+function tha_entry_bottom() {
  103
+	do_action( 'tha_entry_bottom' );
  104
+}
  105
+
  106
+/**
  107
+* Comments block hooks
  108
+*/
  109
+function tha_comments_before() {
  110
+	do_action( 'tha_comments_before' );
  111
+}
  112
+
  113
+function tha_comments_after() {
  114
+	do_action( 'tha_comments_after' );
  115
+}
  116
+
  117
+/**
82 118
 * Semantic <sidebar> hooks
83 119
 */
84 120
 function tha_sidebars_before() {

0 notes on commit 233e1e8

Please sign in to comment.
Something went wrong with that request. Please try again.