Theme Frameworks and Namespacing Guidelines
Due to confusion – mostly caused by inconsistent nomenclature – regarding namespacing requirements for Theme frameworks, we would like to clarify the guidelines, and open the floor to discussion.
First, a word on nomenclature. For the purposes of this discussion, and the guidelines, a “Theme framework” is not a stand-alone Theme, but rather a “drop-in” code library used to facilitate Theme development. The following are examples of such Theme frameworks (note: this list is not an endorsement; rather, it constitutes a quick Google search for examples only):
Note that none of the above examples constitutes a full, stand-alone Theme. Each is a library of code, used to develop a Theme. Such code libraries are different in both nature and purpose from stand-alone Themes that use the term “framework” to refer to an intended use as a Theme to be forked for further development. (Even the Codex conflates the uses of the “Theme framework” terminology in this manner.)
So, to keep the terminology clear, when I refer to “framework”, I mean a drop-in code library, and not a stand-alone “starter” or “base” Theme. In other words, using this definition of “framework”: Hybrid Core is a Theme framework; the Genesis Theme (even though it is called “Genesis Theme Framework”) is not a Theme framework, but rather a stand-alone, base/starter Theme.
Now, on to the Guidelines, which include the following requirement:
Themes are required to use a unique slug as a prefix for anything in the public namespace, including all custom function names, classes, hooks, public/global variables, database entries (Theme options, post custom metadata, etc.)
This guideline applies to forked/derivative Themes. For example, several Twenty Ten and Twenty Eleven derivative Themes get submitted to the repository. We require these Themes to re-namespace their custom functions, hooks, global variables, textdomain, etc.
However, some confusion arises when a Theme uses a framework – i.e. a drop-in code library – to develop the Theme. Should the Theme be required to re-namespace the framework code? Our current thinking is that such a requirement would effectively defeat the purpose of using a Theme framework, and would deter, rather than facilitate, Themes using such frameworks – and, more importantly, keeping the framework updated.
Requiring Themes to re-namespace such framework library code would be analogous to requiring Themes to re-namespace bundled jQuery Plugin libraries. Also, requiring such re-namespacing serves no practical purpose, and would be counter-productive toward one of the Theme Review Team’s long-term desires to have the means/process/infrastructure for vetting/approving such Theme frameworks, in order to facilitate their broader use. If we started requiring Themes to re-namespace the framework library code today, we’d have a mess on our hands in the future, if we one day are able to have vetted/approved versions of those same frameworks.
So, bottom line, TL:DR: forked/derivative stand-alone Themes ARE required to re-namespace; Themes that use framework libraries are NOT required to re-namespace the framework library code.
What are your thoughts?
ZaMoose 1:08 pm on March 15, 2012 Permalink |
Agree 100%. Kind of wish we would just call so-called “Frameworks” “libraries” instead.
I mean, is the STL a “framework”?
Edward Caissie 2:06 pm on March 15, 2012 Permalink |
+1; that was the recommendation I was going for in the discussions prior to this post. We just have to get used to not using the “framework” buzzword everywhere it is currently being applied.
Justin Tadlock 3:23 pm on March 15, 2012 Permalink |
We should start calling those other “so-called frameworks” what they really are: themes. Everyone who builds a theme with a few hooks in it is calling it a framework now. Those of us who have had true development frameworks for years now (e.g., Hybrid Core, Carrington Core, WP Framework) shouldn’t need to start calling them something else because a few companies have decided it’s a good word to use for marketing purposes.
ZaMoose 3:33 pm on March 16, 2012 Permalink |
Justin:
No offense intended. Hybrid Core, etc. do indeed hew fairly closely to the compsci definition of “framework” with one small exception:
Inversion of control
In a true framework, the program flow is generally dictated by the framework and not the calling program. Perhaps it’s a minor point, but that’s where my objection was coming from.
scribu 2:00 am on April 8, 2012 Permalink |
Well, it’s not that clear cut. For example, you can’t really call Carrington Core a “library”. You load it, but then it creates the advanced template hierarchy by itself and you can hook into it via some filters, if you need to.
Otto 4:31 pm on March 15, 2012 Permalink |
Are you speaking of namespacing in terms of function naming or in terms of internationalization calls?
Function names = don’t care if they re-namespace or not. Doesn’t matter much, since only the active theme is loaded, and having the same functions in multiple themes is fine.
Internationalization function calls *must* have their domains be replaced with the new domain if there is any such code in the framework that would require it. Note that domains need to be plain text strings as well, using defines or global variables does not work properly, and never really will for various reasons. However, this should be as simple as a global search/replace if the framework is up to par. If the framework is smart about it, all the strings for this could be defined in a single file.
Sayontan Sinha 6:34 pm on March 15, 2012 Permalink |
What about namespacing of JS libraries? The wp_enqueue_script call provides a handful of JS libraries, but if a theme is using a common JS library like Fancybox or JQuery Cycle, what is the requirement? Does the
$handleargument of wp_enqueue_script need to have the theme name prefixed? This can lead to repeated loading of the same file on a site.Michael Fields 6:49 pm on March 19, 2012 Permalink |
Hello,
The above requirements appear to have been altered before this post was made to include “hooks” in the requirements:
Read the Codex changeset.
I was just wondering if there was any discussion regarding these changes to the requirements? I would love to have taken part in such a dialog. Hooks are bit different when compared to the other items in the list. IMHO it is perfectly valid for a theme to include un-prefixed hooks. One of the most convincing use-cases is plugin integration. I’ve been using this practice for many months mainly inspired by Rethinking Template Tags in Plugins. I really love this solution and think it’s great for automatic plugin/theme integration. I use it myself here.
I believe that introducing such a requirement may limit communication between plugins and themes. I do my best to follow the guidelines laid out by the WPTRT. Can we discuss this topic more?
Chip Bennett 6:53 pm on March 19, 2012 Permalink |
Indeed; I changed that guideline to clarify the existing intent, which is that everything belonging to the Theme that resides in the public namespace, must be uniquely prefixed.
I’m all in favor of using a consistent, standard nomenclature for hooks; unfortunately, no such standard exists. If/when it does, it will certainly be a benefit to developers and users alike, for exactly the reasons you stated.