SUMMARY: Examining the flow of control through the WordPress bootstrap to my theme code during initialization on both client and server side, and during rendering of the page template. Also realized that the client side Javascript needs initialization also. Straightened out everything in my head.

When I’m starting to learn a new development environment, there are generally five things I’m looking for:

• concise language reference
• finding where applications start up, executes, and shuts down
• an architectural overview of the language and underlying application and system frameworks
• a listing of language and framework libraries, grouped by concept
• a complete class/function listing, grouped by concept with associated datatypes

Guess what? Usually, this documentation does not exist in a concise form. You have your best chance finding the language reference, and there probably is at least one decent one. Not so for the rest of it. Your typical official reference is organized alphabetically, which is only good if you’re looking something up to find out what it does. It seems that most programming instruction is done these days through the study of existing recipes. Maybe this is the way it is in all areas of human endeavor…but I digress.

In the case of P’SEC, aka “Project Second”, aka my HTML5/Javascript/WordPress mashup that will become the testbed for productivity application development, I already know PHP somewhat well enough to get by; it’s a C-like language, and the documentation for it is actually widely available with many examples. So, next on the list is finding out where my own code “starts up”.

I’m thinking of implementing my app framework as a WordPress theme, because you can completely customize how it runs if you know a bit about how WordPress works.

First, the WordPress Template Hierarchy describes what PHP files are executed when. I’m thinking of making the starting point for my application a specially-named page. That means I don’t need to modify any WP core files.

Next, every WordPress theme also has a functions.php file that is executed for every pageload, so this is where my common code will reside. I believe functions.php is executed before the appropriate template file. The initialization, which isn’t documented formally, is described in this article the WordPress bootstrap.

WordPress Bootstrap

I poked through the source code myself to see what the key execution path is (perusing wp 3.2.1). Starting from wp-blog-header.php…

1. wp-load.php

• set ABSPATH to wordpress install directory
• load wp-config.php, which sets user constants
• indirectly load wp-settings.php, which initializes all the WP data structures
• • plugins are initialized
• • theme’s functions.php is called just before current user is set-up and init action hook is executed.

2. wp()

• Dispatches through global $wp->main() to set up correct data structures for requested resource (page, posts, etc)

3. template-loader.php

• determines which template page to load

Hooking into WordPress Actions

From the above, we can see that we control two kinds of files that are executed by WordPress as part of the template hierarchy:

• Theme’s functions.php file executes before the WordPress data structures are set-up in the call to wp(). This makes it a good place for us to declare our own data structures and functions, but

• Individual theme template pages are executed after wp().

So our proper startup procedure is broken into two parts:

1. Initialize our own constants and functions in the theme’s functions.php.

2. Everything else, use Action Hook. There’s a list of actions that are executed during a “typical” request.

The action hook that’s most interesting to us is probably init, which we would intercept with:

add_action('init', 'init_function');

The init action hook occurs after everything is set up, including user authentication. There’s also the wp_loaded action, which occurs after init has completely been processed for all plugins in the system. During our init handling, we can do anything we want, so long as it doesn’t rely on a valid wp-query. So, in general we’ll be setting additional action_hooks and filters that will call our own functions. We can also define functions that will be called from our own template files, which implement run-time program logic. That takes care of our own theme initialization and setup.

Javascript Startup

After we display a particular page, I want to be able to manipulate its content interactively. That means I have to also initialize javascript libraries and run page-specific javascript. To me, that sounds like I need to know the state of the webapp as part of my initialization. At minimum, that is:

• what “function page” I am on
• what “step of the transaction” I am in
• what “display state” is currently active

That means I need to create some kind of dispatching system, which is probably core code in my theme functions.php that takes as input many of the following kinds of data:

• the current page being looked at
• the current query that WordPress has
• GET or POST variables beyond what WordPress query is already using
• browser cookies for persistent variables from page-to-page
• javascript variables being passed back

The simplest thing to do is just look at the page name, and then use the wp_enqueue_script() function to load the appropriate script libraries. Specific initialization code probably can be tacked-onto the header by intercepting the wp_head action hook and inserting some script code that sets runtime variables once the page has completely loaded. I’m not that familiar with jQuery or Javascript events, but I think the code I want to initialize is the jQuery(document).ready() call. According to the docs, this event is fired as soon as the DOM is fully constructed, but before all assets are completely received. For that case, jQuery(window).load() can be used, apparently.

Next Steps

I think this is what I need to get started. I think I can do the following:

• Create a special page with the slug test-startup in WordPress, and then create a page-test-startup.php file to put my own stuff in, by copying the existing twentyeleven version of page.php.

• Create a rudimentary page that shows a single todo item, just static HTML.

• Add the functions and action hooks to my theme’s functions.php file that will add jQuery, jQueryUI, and my custom initialization.

• Play with jQuery and stuff and see what I can make it do.

<

p>After that, I can think about the necessary architectural support to load and save a dynamic to-do list using WordPress’ built-in database API.