As an addition to my article on How to Use the Thesis Custom Loop API, here is a Custom Loop starter template you can use for your own loops. Every loop you can customize in Thesis 1.8 is stubbed in, and comments before each method provide helpful reference information. All you need to do is replace the one-line stub methods with your own custom loop code. You can delete any loop method you’re not customizing, or leave them in place for the future; they simply apply the appropriate default Thesis loop.

(The comments more than double the file size. If you find them distracting, here’s a truly minimal version.)

Thesis Custom Loop Template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227

/**
 * These are the different Thesis loops that can be customized.
 *
 * Replace the calls to the default Thesis loops with your own code.
 * You can also delete any unused loop methods.
 *
 * @link http://codex.wordpress.org/Conditional_Tags More details of 
 *       which page requests trigger which specific loops.
 * @link http://aldosoft.com/blog/2011/01/the-thesis-custom-loop-api/ Detailed
 *       article about how to use the Custom Loop API.
 */
class my_looper extends thesis_custom_loop {
 
	/**
	 * The loop for the blog index page.
	 *
	 * By default this is the home or top-level index page.
	 * Can be changed to any page using Settings > Reading > Posts Page.
	 *
	 * This loop is used by the {@link archive()} loop (and all child loops)
	 * unless Thesis > Design Options > Display Options > Archives is
	 * set to Titles Only.
	 */
	function home() {
		thesis_loop::home();
	}
 
	/**
	 * The loop for the front page of the site if configured in 
	 * Settings > Reading > Front Page. 
	 *
	 * Has no effect if no front page is set.
	 *
	 * By default, delegates to the {@link page()} loop.
	 */
	function front() {
		thesis_loop::front();
	}
 
	/**
	 * The loop for displaying an individual post, i.e. the 
	 * one-article-per-page view of a post.
	 *
	 * Sometimes referred to as "single-entry pages".
	 */
	function single() {
		thesis_loop::single();
	}
 
	/**
	 * The loop for displaying an individual attachment on a post, 
	 * usually an image.
	 *
	 * By default, delegates to the {@link single()} loop.
	 */
	function attachment() {
		thesis_loop::attachment();
	}
 
	/**
	 * The loop for a static, individual page.
	 */
	function page() {
		thesis_loop::page();
	}
 
	/**
	 * Default loop for archive-style pages.
	 *
	 * This loop is the default for category, tag, tax, author,
	 * day, month, year, and search pages.
	 *
	 * Important: Delegates to {@link home()} unless 
	 * Thesis > Design Options > Display Options > Archives is 
	 * set to Titles Only.
	 */
	function archive() {
		thesis_loop::archive();
	}
 
	/**
	 * Loop for category pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function category() {
		thesis_loop::category();
	}
 
	/**
	 * Loop for tag pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function tag() {
		thesis_loop::tag();
	}
 
	/**
	 * Loop for custom taxonomy pages.
	 *
	 * Has no effect unless you have defined a custom taxonomy.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function tax() {
		thesis_loop::tax();
	}
 
	/**
	 * Loop for author pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function author() {
		thesis_loop::author();
	}
 
	/**
	 * Loop for year-level date archive pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function year() {
		thesis_loop::year();
	}
 
	/**
	 * Loop for month-level date archive pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function month() {
		thesis_loop::month();
	}
 
	/**
	 * Loop for day-level date archive pages.
	 *
	 * By default, delegates to the {@link archive()} loop.
	 */
	function day() {
		thesis_loop::day();
	}
 
	/**
	 * Loop for search results page.
	 *
	 * By default, delegates to the {@link archive()} loop IF THERE ARE RESULTS.
	 * By default, just shows a search form if there are no results.
	 *
	 * A custom search loop needs to deal with both possibilities; see the
	 * {@link thesis_loop::search()} for example of how to do so.
	 */
	function search() {
		thesis_loop::search();
	}
 
	/**
	 * Loop for the "404 Not Found" error page.
	 * 
	 * Runs when the URL requested could not be mapped to any page.
	 */
	function fourohfour() {
		thesis_loop::fourohfour();
	}
 
	/**
	 * Loop for page without any posts/pages (an empty query).
	 *
	 * Runs when the URL requested maps to a legitimate page, but there
	 * is no post data to display. Should be rare.
	 */
	function nothing() {
		thesis_loop::nothing();
	}
 
	/* PRIVATE HELPER METHODS */
 
	/**
	 * Merge new query parameters with existing parameters.
	 *
	 * This preserves existing request parameters, for compatibility
	 * with plugins, etc.
	 *
	 * New parameters overwrite existing parameters with same name.
	 *
	 * @access private
	 * @param array $new_params Parameters for a new query via 
	 *        {@link query_posts()} or a new {@link WP_Query}.
	 * @global $wp_query is used to get the current request parameters.
	 *
	 * @return array The merged parameters array, ready for passing to 
	 *               {@link WP_Query::query_posts()} or
	 *               {@link WP_Query::get_posts()}.
	 */
	private function preserve_query_params($new_params = array()) {
		global $wp_query;
		return(array_merge($wp_query->query, $new_params));
	}
 
	/**
	 * Retrieve the current "paged" parameter from the request.
	 *
	 * This is used for "paging" through the query results. 
	 * See {@link http://aldosoft.com/blog/2011/01/thesis-custom-loop-template/ 
	 * for details.}
	 *
	 * This method deals with a WordPress idiosyncracy / inconsistency in the 
	 * name of this parameter.
	 *
	 * @access private
	 * @uses WP_Query::get_query_var()
	 *
	 * @return int The current paged parameter.
	 */
	private function get_paged_param() {
		if(is_front_page()) {
			$paged = (get_query_var('page') ? get_query_var('page') : 1);
		}
		else {
			$paged = (get_query_var('paged') ? get_query_var('paged') : 1);
		}
		return($paged);
	}
}
$custom_looper = new my_looper;

About the Helper Methods

I’ve added two private methods that virtually every Custom Loop will find a way to make use of. (Lines 197-200 and 217-225.) These helpers simplify your loop code by factoring out dealing with some idiosyncrasies of WordPress request parameters.

The first helper makes preserving existing request parameters easier, and more complete:

1
2
3
4
5
6
7
8
9
10
11
12

class my_looper extends thesis_custom_loop {
 
	function home() {
		$new_args = array(
			'orderby' => 'title',
			'order' => 'ASC',
		);
		query_posts($this->preserve_query_params($new_args));
		thesis_loop::home();
	}
}
$custom_looper = new my_looper;

This loop is functionally (almost) identical to the first loop example in the Custom Loop API article. It changes the sort order of the home page, but otherwise leaves the formatting alone. At first blush it’s just a more complicated version of the earlier example, but let’s look at what’s different:

• Lines 4-7 define an array of query arguments, which will override existing request parameters. Recall from the earlier article that using an array is generally easier when you have more than one or two parameters to add.

• Line 8 is what’s interesting, instead of concatenating together pieces of a query string, I use the new helper method, preserve_query_params(). The cool thing about the helper is that it accesses the $wp_query global to extract all of the request parameters, not merely those that are in the query string. This is more likely to preserve compatibility with plugins, etc.

• Line 9, delegate to the built-in Thesis home() loop, just as I did before.

The preserve_query_params() method will generally be useful in any Custom Loop where you modify the existing query; it’s unnecessary in situations where you are creating a new query, unless that query needs to “copy” parameters from the default query.

The second helper method, get_paged_param(), is for use when you want to enable paging through the results of a new query, that is, when you are adding a list of items that would not normally display on the URL requested. The portfolio page example in the Custom Loop API article is a good example of where this is useful. Here’s an abbreviated version for discussion:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function page() {
    if(is_page('portfolio')) {
        // Get request var to maintain paging through list of portfolio posts
        $paged = $this->get_paged_param();
 
        // Loop #1: Show the requested page's content
        while (have_posts()) { // Standard WordPress
            the_post(); // Standard WordPress
			// ... HTML output
        }
        wp_reset_query();
 
        // Loop #2: Add a list of portfolio posts
        $portfolio_query_args = array(
            'paged' => $paged,
            'post_type' => 'post',
            'post_status' => 'publish',
            'tag' => 'portfolio',
        );
        query_posts($portfolio_query_args);
 
        if(have_posts()) { while(have_posts()) {
            the_post();
			// ... HTML output
        }}
    }
    // else ...
}

The basic idea is that one page of this site is a portfolio, which will display a stylized list of posts which have been tagged as “portfolio”. The page itself contains static content to introduce the portfolio, so we’re adding a second query to get the portfolio items. The paging issue arises when we have more portfolio posts than will fit in the list (WordPress has a default of 10 here, it can be changed in Settings > Reading > Blog pages show at most).

If we want to be able to “page” backwards and see older portfolio items, we need to enable the “paging controls”, the “Previous Entries” and “Next Entries” links that appear at the bottom of the page in Thesis archive views. These links are auto-generated by Thesis and WordPress functions; all we need to do to enable them is to preserve the “paged” parameter that is part of the request, and feed it to the new query.

So, on line 4 we use the get_paged_param() helper method to grab that parameter. The helper deals with an inconsistency in WordPress, where the parameter is named one thing on most pages, and another on the front page.

Lines 7-11 handle the initial Loop, which is simply displaying the static page content. (And, obviously, line 9 hides a lot of the details; see the portfolio example for the full code.)

Line 14 starts our second Loop, and line 15 is where we add the $paged value to the parameters for the new query. This is the query that will return multiple results, potentially more than will display on one page, and which we want to page through. Adding the $paged parameter tells the query which section of the results to actually retrieve.

On line 20 we run the query, and lines 22-25 deal with looping through the results of the query and outputting the portfolio list HTML for each portfolio post.

Now, there’s additional complexity here that might not be apparent. The WordPress query_posts() documentation explicitly states that you should only use query_posts() to modify the main page Loop. That’s a good rule of thumb, and if you choose to not follow it, you should have a good reason.

In this case, the reason is pagination. If the Loop above were to use get_posts() or create a new WP_Query object manually, it would certainly retrieve the portfolio posts just as well as using query_posts(), without making the code appreciably more complicated.

But the automatic display of the paging controls will only happen for the query results last returned by query_posts(). If the above loop did not use query_posts(), the default Thesis pagination wouldn’t happen, and I would have to write my own pagination code, which would add a lot more code to the loop. This way is easier.

How does it work? WordPress pagination runs off the global $wp_query variable. When you leave your loop (or any hook affecting the “main” query), you need to leave $wp_query holding the results you want paginated and with a valid/preserved $paged parameter. If you do that, pagination runs automatically.

Anyway, to at least wrap up a long story, hopefully this starter template and the helper methods will make your Custom Loops easier to write. Happy looping!

In the latest release of the Thesis theme for WordPress a new feature for advanced theme customization was added called the Thesis Custom Loop API. The Thesis User’s Guide explains the basics of how to use the Custom Loop API. This article expands on that documentation, offering additional context to explain what the Custom Loop API is, what it’s good for, and examples of how to use it.

Wait! There’s more! I’ve written a follow-up to this article, Thesis Custom Loop Starter Template, which provides a complete custom loop class ready for you to customize, along with useful helper methods and additional explanations.

A Bit of WordPress and Thesis Background

To understand what the Thesis Custom Loop is, we need to take a step back, and look at just WordPress. Setting aside plugins for a moment, before the Thesis theme, there was only one way to alter the HTML and contents of your site’s theme: hack away on the theme files themselves. And once you started hacking on your copy of a theme’s files, it became a real challenge to update to a newer version of that theme.

Among other innovations, the Thesis theme made it possible to customize the theme extensively without altering the theme’s files. By isolating theme customizations into a few files in the thesis/custom directory, it became easy, almost trivial to update to newer versions of the theme. (These days child theme functionality is built into WordPress, but it works differently than Thesis, overriding theme files directly, rather than with an API, so it’s not relevant here.)

Thesis achieved this by moving the vast majority of the theme’s code out of standard WordPress theme files and into libraries and classes in the Thesis core code, and weaving into it the Thesis API—the hooks and filters we know and love.

With Thesis, you don’t hack away on the theme files, because there is nothing there. (Check out the thesis/index.php file, it has one line of code.) Instead of altering the HTML and WordPress Loop code directly, you use the hooks and filters to re-order, remove, or alter the various pieces of the Thesis HTML, post content, metadata about those posts (tags, categories, author, etc.), and so on.

What is the Thesis Custom Loop API?

If you have worked with Thesis much, at this point you’re thinking “I know all this, but what does it have to do with the Custom Loop API?”

Standard WordPress theme files don’t merely contain HTML and content tags, they also contain The Loop. The Loop is the heart of WordPress output, and it is how WordPress acquires, processes, and iterates through a set of posts (or pages, etc.) to convert them from database table rows to e.g. your blog’s home page.

When Thesis moved the contents of theme files from the files themselves to functions and classes inside Thesis, it also moved The Loop. While you can use hooks and filters to alter the HTML that Thesis generates when processing The Loop, before Thesis 1.8 there was no (good) way to use anything but a standard WordPress Loop on a Thesis site.

The Thesis Custom Loop API opens that up again. A cynic might say it just returns a built-in WordPress feature that was taken away by earlier versions of Thesis, but actually the Thesis Custom Loop can be a much cleaner way to work with The Loop. We’ll see how in a bit.

The Loop Inside the Custom Loop API

The WordPress Codex has a solid introduction to The Loop and developer details including multiple examples, which explain what the WordPress Loop is, and why and how a WordPress developer might want to modify it. Kristarella.com also has a great take on WordPress Loops. Since the Custom Loop API is simply the Thesis way to affect The Loop, at some point you will want to read these docs carefully, especially to achieve advanced customizations.

To explore the Thesis Custom Loop API we can use a simplified version of what happens during a request to a WordPress blog (ignoring initialization, error conditions, and other distractions):

1. Parse the URL requested into a set of query conditions and variable settings.
2. Run the query against the database.
3. Turn the database results into a structured list of posts.
4. Pick out the appropriate theme file (index, category, author, etc.), and turn control over to it.
5. The theme file runs The Loop to convert the list of posts into HTML.

To simplify it even further, you can think of it this way:

1. Get some posts.
2. Process the posts into HTML. (Technically, only this second part is The Loop.)

The HTML generated by The Loop affects each item processed by The Loop, whether that is a collection of posts, e.g. for the blog index or an archive page, a single item, e.g. for a static page or individual post, or (in rare situations) no items at all. All of the HTML generated is placed inside the Thesis #content div, i.e.:

1
2
3
4
5

<!-- [...] -->
<div id="content">
    (The Loop output goes here.)
</div>
<!-- [...] -->

Why Play with the Loop?

With all that background under our belts, it shouldn’t be hard to think of reasons why you might want to alter, extend, or replace the standard WordPress Loop, to create pages which are significantly different from standard WordPress or Thesis versions. The most obvious thing to do is to alter the set of posts that are retrieved from the database. Possibilities include:

• Alter the sort order of the posts, e.g., to sort teasers alphabetically.
• Show posts only from certain categories, e.g., shared link items or featured posts.
• Exclude posts from certain categories, e.g., your archived tweets auto-created by Twitter Tools.
• Do any of these for specific tags, authors, post custom fields, etc.

Another thing you can do by altering The Loop is to affect output, but only when displaying certain pages. For example, you might want to:

• Start a page (the Home page, a certain Category page, or any specific static page) off with some static content, and then display a list of posts.
• Add a list of posts to an existing static page.
• Treat custom post type or custom taxonomy archive pages differently than “standard” pages.
• Create a custom Authors page.

And then there are times when you want to customize the HTML for a page beyond what’s available via hooks and filters. That should be rare, but with the Custom Loop API, you can completely replace the HTML output for the #content div of any page.

Getting Started: A Simple Custom Loop

Here is possibly the simplest Custom Loop that actually does something useful (put this in your thesis/custom/custom_functions.php file):

1
2
3
4
5
6
7
8
9
10

class tlooper extends thesis_custom_loop {
 
	function home() {
		global $query_string;
		query_posts($query_string . "&orderby=title&order=ASC");
		thesis_loop::home();
	}
 
}
$the_looper = new tlooper;

This Custom Loop changes the sort order for the home page, to sort by post title, instead of by date. (Why is this useful? Image a site that lists books or movies, you may not care about when a title was added to the site, you just want to look alphabetically. At any rate, it was requested in the Thesis Support Forum.)

It also illustrates the fundamentals of creating your own Custom Loop. First, there is the essential structure:

1. Lines 1-9 define a new Custom Loop class, which extends the thesis_custom_loop class.
2. Within the class, lines 3-7 define a function to be used for the loop to be changed, in this case, the loop for the home page.
3. Line 10 creates a new instance of this class, which is the “trigger” that tells Thesis to actually use it.

This structure of: a class that extends thesis_custom_loop; one or more loop functions, and; activation by instantiating the class, is pretty much the whole Custom Loop API. Indeed, the class definition and instantiation are each one line, and they are dead simple. All of the complexity of creating Custom Loops will be in the loop functions—and they don’t have to be that complicated.

Let’s look at this simple loop function again, line-by-line:

1
2
3
4
5

function home() {
	global $query_string;
	query_posts($query_string . "&orderby=title&order=ASC");
	thesis_loop::home();
}

1. The function signature. Two things to note. First, there are no parameters. None of the Custom Loop functions take parameters; any request params or WordPress variables or settings you might want to access must be brought in from the global scope. Second, the method name is one of 16 defined in the Custom Loop API (see the API Reference section below for specifics). Each one represents a request type (home, post, archives, category, etc.) for which you can override the loop definition. More on this below.

2. Bring the variable $query_string into scope. $query_string is a WordPress global variable, which contains the query string portion of the URL requested, i.e., everything after the “?” in the URL.

3. Run the query for posts, with two new parameters added to the query string. query_posts() is a WordPress function that runs the database query and puts the results in a WordPress global variable for use inside The Loop. When called with parameters, the new parameters override whatever WordPress parsed out of the request URL. Here, appending the new parameters to the existing query string preserves any other query parameters that might already exist.

4. Call the default Thesis HTML output loop for the home page (this is basically just a call to the superclass). This turns control back over to Thesis to handle the conversion of database results into HTML.

To go back to our ultra-simplified explanation of what happens in The Loop…

…this Custom Loop only affects #1, and leaves #2 unchanged. Processing the posts into HTML can be a lot of work, so it’s really cool that Thesis lets you skip that part, if the default HTML is fine. (Traditional WordPress themes don’t allow you to skip that part.)

This example is extremely simple, but it’s a great model for any situation where you just want to change the query that gathers the posts to display on a page. You only have to change one line to change the query. To offer a few variations on this initial theme, here are a few more useful query-only custom loops:

Order by the number of comments on the post, most comments to least:

1
2
3
4
5

function home() {
	global $query_string;
	query_posts($query_string . "&orderby=comment_count&order=DESC");
	thesis_loop::home();
}

Show only posts from certain categories:

1
2
3
4
5

function home() {
	global $query_string;
	query_posts($query_string . "&cat=3,4");
	thesis_loop::home();
}

Exclude posts from certain categories:

1
2
3
4
5

function home() {
	global $query_string;
	query_posts($query_string . "&cat=-1,-14");
	thesis_loop::home();
}

Show posts by a specific author with a specific tag:

1
2
3
4
5

function home() {
	global $query_string;
	query_posts($query_string . "&author_name=Twain&tag=american");
	thesis_loop::home();
}

See the WordPress Codex page on query_posts() for more documentation on the various parameters you can use to affect the query, there is a lot you can do here.

A More Complex Loop: Make A Page “Special”

Here’s the scenario: We have a site where we’re posting a selection of books from Project Gutenberg. Our site has three categories: fiction, non-fiction, and announcements. The first two are for the books, the third is for notifications for site visitors.

So, on the category archive pages for books, we want to list posts in alphabetical order by title. For the announcements, we want a date order. Additionally, we want to format the two different kinds of items, well, differently.

Here’s a custom category() loop method that handles this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

function category() {
 
	if(is_category('Announcements')) {
 
		// Default sort order (by date) is correct
		// But we want to change the HTML output
 
		// This creates standard Thesis HTML content blocks that 
		// will automatically pick up Thesis styles
		thesis_archive_intro();
		echo '<div class="post_box top">' . "\n";
		echo '  <div class="format_text">' . "\n";
		echo '    <ul class="system_announcements">' . "\n";
 
		// Here's an actual WordPress Loop!
		while(have_posts()) { // This is standard WordPress
			the_post(); // Standard WordPress, sets up global variables
 
			// Output our notices with custom HTML
			echo '      <li><strong><a href="' . get_permalink() . '">' . 
			     get_the_title() . '</a></strong> &mdash; ' . 
			     get_the_time(get_option('date_format')) . "<br />\n" .
			     get_the_content() . "</li>\n";
		}
 
		// This closes the HTML blocks we opened
		echo "    </ul>\n";
		echo "  </div>\n";
		echo "</div>\n";
	}
	else { // For all other categories
 
		// Change the sort order to title, alpha order
		global $query_string;
		query_posts($query_string . "&orderby=title&order=ASC");
 
		// But we're happy with the default HTML output, so delegate the rest
		thesis_loop::category();
	}
}

Here are a few interesting points about this example:

• First, this is just the loop method; you need to put this inside a thesis_custom_loop class for it to work. See the first example for the full structure.

• This loop is divided into two sections by the if statement on line 3. The first section (lines 4-30) runs if the requested category is “Announcements”, and the second section (the else block on lines 31-39) runs for the other categories. is_category() is a standard WordPress function.

• When the category is Announcements, we want the default WordPress sort order, which is by date, most recent to least recent. So, we don’t need to modify the query.

• Line 10 uses a Thesis function to output the introduction block for this archive category. This is the headline, and the intro description for the category if you entered one in Posts > Categories > Introductory Content.

• Lines 11-13 output some basic HTML blocks, using Thesis classes that will pick up styles from Thesis automatically. How do you know what you should output? More on that in a bit.

• Lines 16-17 are the start of The Loop, the standard WordPress version, which we are customizing. Note that it’s a slightly abbreviated version, we don’t need the standard if(have_posts()) test, because we wouldn’t be in this loop function if it failed. Thesis “pre-flights” the loop, that’s part of how it decides which Custom Loop function to run on any given request.

• Lines 20-23 are our replacement for the built-in Thesis functions that output a post. Our version is much simpler than what Thesis does in the standard loop. It also doesn’t run hooks or filters, more on that below.

• Finally, lines 32-38 are the else clause, running for all the other category archive pages. It should look very familiar, from the earlier examples.

How Do I Know What to Put in a Custom Loop?

While you may understand all of the code in the previous example, it may be a little mysterious how I came to write it. How did I know what Thesis HTML and classes to use? How did I know to use the thesis_archive_intro() function to start the page? How do you write a Custom Loop that will still invoke hooks and filters?

When working with a traditional WordPress theme, if you want to customize The Loop, you don’t have to start with a blank slate. The simplest way to get a jumpstart is to make a copy of the relevant theme file, move it into your child theme directory, and modify the code you find in your copied file.

Similarly, the easiest way to make a complex customization of a Thesis loop is to copy the code from the relevant Thesis loop, and paste it into your Custom Loop class. You can find all of the Thesis loops in thesis/lib/classes/loop.php. So, if you want to customize the archive() loop, copy the thesis_loop::archive() method from that file, and paste it into your implementation of thesis_custom_loop. Then start making changes.

Before you do this, though, a word of caution. Thesis is cleverly put together. Before you start hacking away at code you’ve copied out of loop.php it’s worth reading and understanding all of the code you find there. You will certainly learn things about how Thesis works, which will better equip you to make changes to those workings. More importantly, it will help you avoid pitfalls, and track down problems you may encounter.</word>

Add Posts to a Static Page

Here’s the scenario: We have a static page on our site where we would like to add a list of posts with a particular tag below the main page content. For example, perhaps you have a portfolio page that shows off some of your recent projects. Or maybe it’s a page that archives your tweets. In any event, the goal is to have the content of a static page display, and then have a blog-like index of posts below it, which is not your blog page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

function page() {
	if(is_page('portfolio')) {
		// We need this query var to maintain paging through the list of posts
		$paged = $this->get_paged_param();
 
		// First, show the page's content
 
		// This is a stripped down version of the thesis_loop::page() method
		// Post image and comments removed; all hooks preserved
		while (have_posts()) { // Standard WordPress
			the_post(); // Standard WordPress
 
			thesis_hook_before_post_box();
			echo "\t\t\t<div class=\"post_box top\" id=\"post-" . 
				 get_the_ID() . "\">\n";
			thesis_hook_post_box_top();
			thesis_headline_area();
			echo "\t\t\t\t<div class=\"format_text\">\n";
			thesis_post_content();
			echo "\t\t\t\t</div>\n";
			thesis_hook_post_box_bottom();
			echo "\t\t\t</div>\n";
			thesis_hook_after_post_box();
		}
		wp_reset_query();
 
		// Now, show our list of posts (portfolio posts only)
 
		// Build a set of query arguments, and load in the new set of posts
		$portfolio_query_args = array(
			'paged' => $paged,
			'post_type' => 'post',
			'post_status' => 'publish',
			'tag' => 'portfolio',
		);
		query_posts($portfolio_query_args);
 
		// An initial container div, for CSS styling
		echo "\t\t\t<div class=\"portfolio\">\n";
 
		// Another WordPress loop, to output the portfolio posts
		// Note: this assumes adding proper images to portfolio items
		// And making it look good requires additional CSS styles in custom.css
		if(have_posts()) { while(have_posts()) {
			the_post();
			$post_image = thesis_post_image_info('thumb');				
 
			echo "\t\t\t\t<div class=\"folio_item post_box\" id=\"post-" . 
				 get_the_ID() . "\">";
			echo "\t\t\t\t\t" . $post_image['output'];
			echo "\t\t\t\t\t<h2><a href=\"" . get_permalink() . "\">" . 
				 get_the_title() . "</a></h2>\n";
			echo "\t\t\t\t\t<div class=\"format_text\">\n";
			echo get_the_excerpt();
			echo "\t\t\t\t\t</div>\n";
			echo "\t\t\t\t</div>\n";
		}} // end WordPress Loop (both if and while)
 
		// Close our portfolio container div
		echo "\t\t\t</div>\n";
	}
	else {
		thesis_loop::page();
	}
}
 
/* PRIVATE METHODS */
 
// Deal with an irritating inconsistency in WP 3.0.4 and earlier
private function get_paged_param() {
	if(is_front_page()) {
		$paged = (get_query_var('page') ? get_query_var('page') : 1);
	}
	else {
		$paged = (get_query_var('paged') ? get_query_var('paged') : 1);
	}
	return($paged);
}

Understanding this loop:

• First of all, in spite of the length, you should recognize the basic structure. We have a simple “if this is the special page do something interesting, else just do the normal loop” structure. If you have a bunch of “special” pages on your site, this could get awkward. In that case, create private methods, one for each special page, and call those methods from a case statement in your actual custom loop method.

• The next thing to notice is there are two WordPress Loops! The first one, lines 10-24, is there to display the page’s content. The second, lines 44-57, is for our list of portfolio posts.

• Line 4 uses a private method to grab a request parameter for what screen of posts to display. That is, if you have more than 10 posts that should display here, preserving this parameter will give you working [Previous] and [Next] links to “page” through them.

  I put this in a separate method, shown on lines 70-78, because a WordPress inconsistency makes this more complicated than it should be. Also, (I believe) capturing the value needs to be done at the start of the method, before we re-run or reset the query.

• Lines 10-24 are the first Loop, which should only have one item to process, the current static page. The interior of the loop is copy-and-pasted from the Thesis page loop, simplified to remove the Thesis image and WordPress comments elements that don’t necessarily fit on a portfolio page. All of the Thesis hook functions remain, which means that your custom hook functions will continue to run on this page. If that isn’t what you want, you can remove them here.

• Line 25 resets the WordPress query object, in preparation for re-using it. This is just basic cleanup, but you need to do it if another query is going to be run on the page.

• Lines 30-35 build up the parameters for our second query. This is a slightly different way of doing it than constructing a query string, as we did in earlier examples. Using an array is generally neater when you have a larger number of parameters, and makes it easier to modify or add to later.

• Line 36 runs the query, putting the items found into the global $wp_query object for use in The Loop.

• Line 39 adds a <div> to the page (line 60 closes it), to contain our portfolio items, and to add a CSS class to allow us to style the portfolio items differently from, say, teasers. (What CSS styling to use is an exercise for the reader, but it goes into your thesis/custom/custom.css file, the same as all of your theme style customizations.)

• Lines 44-57 are the second WordPress Loop. This one is the full monty, because we need to handle the situation where there are no matching posts retrieved by query_posts(). For the most part this just outputs HTML with the relevant Thesis classes attached in the usual places, but does not call hooks or use the Thesis formatting methods, instead using the standard get_the_title() and get_the_excerpt() WordPress functions. Note that we do attach a portfolio-specific class ‘folio_item’ to the div containing the portfolio post HTML.

• The one Thesis-specific item in this loop, beyond the CSS classes, is on line 46, where we retrieve the Thesis post image for the item, and then on line 50, where the image HTML is outputted. You can display the thumbnail instead of the full-size image by using thesis_post_image_info('thumb') instead of ‘image’.

Don’t let the length of this loop function or any seeming complexity discourage you. I built this loop up slowly, one piece at a time, until I had completed it. Start with a basic if/else or case statement, then add the first WordPress Loop structure with simple output, and then build that output up a line at a time. Then move on to the next piece of your customization. The first one will seem hard, and take a while, but do a couple of loops yourself, and you’ll be knocking them out like they’re nothing in no time. Really!

Thesis Custom Loop API Reference

There are a total of 16 different loops you can customize on your Thesis-equipped WordPress site. As explained above, you do this by writing functions inside your Custom Loop class. You can define each of these loop functions inside the same Custom Loop class—you only need one. (In theory you can create multiple Custom Loop classes, and have them all be active on the same site, but that’s needlessly complicated.)

Some of the 16 loops available through the Custom Loop API have a hierarchical relationship. That is, by default or with certain settings many of the loops delegate to a “parent” loop, and if you customize that parent loop, all of the child loops will be affected as well. In general, you want to customize the most specific loop that you can.

Additionally, each of the 16 loops has a method that delegates control to the corresponding standard Thesis loop, as described in the first loop example above. The method name is the same as the Custom Loop method name, in the form of thesis_loop::method_name().

Special Loops

These loops are unique in some way, mostly by not belonging to a group of related loops.

• home()

  This is the loop for the site’s blog index page. In a default WordPress configuration, this is the site’s home or top-level index page. However, this can be changed to any static page, using Settings > Reading > Posts Page.

  Additionally, this loop is used by the archives loop (and all child loops) unless Thesis > Design Options > Display Options > Archives is set to Titles Only. If you customize this loop, you may need to also (un)customize $this->archive().

• search()

  The loop that handles a search results page. By default it delegates displaying results to the $this->archive() loop if there are results, but merely shows a search form if there are no results. A custom search loop must handle both conditions.

• fourohfour()

  The loop that handles the “404 Not Found” error page. This means that the URL requested does not correspond to any page.

  If you want to do something really clever when people try to reach a funky URL, this is the place, but if you just want to display a customized message, a search form, and maybe some popular posts, it’s probably easier to do it via the 404 hooks.

• nothing()

  The loop that handles a page without any posts or pages. Different from the 404 page, it means that the requested URL maps to a legitimate page, but there is no post data to display. I think this should be rare.

Post Loops

These two loops handle individual posts. Calling this a “loop” is somewhat misleading, because in this context the query should only return one post to process.

• single()

  The loop for displaying an individual post, i.e. the one-article-per-page view of a post.

• attachment() — delegates to $this->single()

  The loop for displaying an individual attachment, usually an image, on a post.

Page Loops

These two loops handle individual static pages. Again, calling this a “loop” is somewhat misleading, because in this context the query should only return one page to process.

• page()

  The loop for static pages.

• front() — delegates to $this->page()

  The loop for a static front page configured in Settings > Reading > Front Page. Has no effect if no static front page is set.

Archive Loops

These loops handle archive-style pages. By default, all of these use the main archive() loop, which is not to be confused with a static archives page, as described in the Thesis User’s Guide article “Create and Customize an Archives Page”. In this case, the term “archive” is simply used generically.

• archive()

  The default loop for all of the archive-style pages. Many Thesis display settings affect the formatting of archives pages, so be sure to start there, before resorting to a custom loop.

  Important: The archive() loop delegates to $this->home() unless Thesis > Design Options > Display Options > Archives is set to Titles Only.

• category() — delegates to $this->archive()

  The loop for category pages, that is, the page you see when you click a category link.

• tag() — delegates to $this->archive()

  The loop for tag pages. You probably guessed that.

• tax() — delegates to $this->archive()

  The loop for custom taxonomy pages. Only useful if you have defined a custom taxonomy.

• author() — delegates to $this->archive()

  The loop handling the display of a single author’s archive page.

• year() — delegates to $this->archive()

• month() — delegates to $this->archive()

• day() — delegates to $this->archive()

  I really think you can figure these last three out without my spelling it out for you. :-)

Wait! There’s even more! I’ve written a follow-up to this article, Thesis Custom Loop Starter Template, which provides a complete, functionally benign custom loop class, along with useful helper methods and additional explanations.

What Not to Use the Custom Loop API For

Thesis users got by without the Custom Loop API for quite some time, it was only added in the most recent version of Thesis. If affecting The Loop is so useful, how did people get along without this feature?

The answer is, many effects can be achieved using other features of Thesis, and indeed, before you begin writing a Custom Loop, it’s always worth investigating whether you can achieve the same end via a setting, or using Thesis hooks and filters. Customizations implemented with those mechanisms will require less maintenance in the long run, as they are more isolated from changes in WordPress or Thesis.

Here are a few things that people often want to do, where you might think you need to create a Custom Loop, along with links to articles or forum posts that show an easier way.

• Ads, or images, or anything, inserted in-between X number of posts. See Insert Ad After Content and this forum post for a few ideas.
• Add a custom headline or introduction to category pages. In Thesis 1.8, this is a built-in feature.
• A top-level Archives page — see the Thesis User’s Guide article “Create and Customize an Archives Page” instead.

If you’re a Thesis developer, there are a lot of great articles and forum posts, so it’s always worth looking for answers before you start digging on your own. Start by reading the various articles about Thesis hooks, and then move onto specific techniques and solutions. Thesis is incredibly flexible, once you get to know it.

Credits, Resources, and Further Reading

I found the following articles useful while learning about the Thesis Custom Loop API, and some of my examples are inspired by code I found in them. If you really want to learn more about writing custom loops, these are great places to start.

• Thesis User’s Guide: Thesis Custom Loop API
• Tutorial: Static Front page with paginated posts (Loop API)
• Thesis Custom Loop Starter Template
• Rockin’ out WordPress custom loops
• WordPress Codex: Query Overview
• WordPress Codex: Custom Queries
• WordPress Codex: query_posts function reference
• WordPress Codex: The Loop in Action (overview)
• WordPress Codex: The Loop (details and examples)
• WordPress Codex: Conditional Tags

The code presented here was developed and tested on a standard install of WordPress 3.0.4 with the Thesis Theme for WordPress 1.8. No plugins were activated.

One of the things that drew me to evaluating and purchasing the Thesis theme for WordPress was the outstanding typography that seemed to be a part of every Thesis site I looked at.

The settings for fonts are simple to use — you choose a single typeface for each option — but behind the scenes, Thesis builds a complete “font stack,” that is, a comprehensive collection of fonts to use, sorted in order of preference. This ensures that your text will look good, no matter what fonts are installed on a viewer’s computer.

For example, when you choose Georgia for your main font, behind the scenes Thesis specifies a series of fonts that are similar to Georgia:

font-family: Georgia, 'Times New Roman', Times, serif;

The variety of typefaces offered by Thesis is somewhat limited, due to the nature of fonts on the web today; there’s only a dozen or so that are “safe” to use, because everyone has them. But recently a few services have come along, which take advantage of new features in modern web browsers to offer more variety in type. Possibly the most “mature” of these (with mature being a relative term) is Typekit. But how do you use Typekit with Thesis, when Thesis only allows you to choose fonts from a pre-defined list?

It turns out that this is quite easy to accomplish. In a nutshell, you treat Typekit as a second custom.css file. There are three simple steps:

1. On Typekit, create your “kit” for your web site. Use the same CSS selectors here that you would use in your custom.css file if you were specifying them there:

   

   You can uncheck any font weights that you’re not planning to use, and you can leave the default CSS Stack setting. Be sure to click the (big ass?) Publish button!

2. When you’ve got your kit specified, copy the embedding code from Typekit:

   

   Click the Embed Code link at the top right of the page to see this.

3. Switch back to your site, and paste the Typekit JavaScript into Thesis, in the Header Scripts section of the Thesis Options panel:

   

At this point, you should be able to reload your site, and see the new font(s) in action, wherever you have set them to be used. If you want have additional control over the use of your Typekit fonts, such as bold, italic, text spacing (tracking), etc., you can add it to your custom.css file as normal. This is all straightforward CSS. Typekit is only specifying the font family; all other font settings are handled by Thesis (automatically) or your custom.css file.

There is one aspect of customizing your CSS font specifications that might not be obvious: when a typeface comes with a more broad range of weights, say, from light to ultra bold, how do you specify which weight to use? The answer is very simple, just add a font-weight CSS attribute with a numeric value from this list:

font-weight: 200; /*  Thin               */
font-weight: 300; /*  Light              */
font-weight: 400; /*  Normal             */
font-weight: 500; /*  Medium / Semi-Bold */
font-weight: 600; /* (not used)          */
font-weight: 700; /*  Bold               */
font-weight: 800; /*  Black              */
font-weight: 900; /*  Heavy              */

So, if you want to use the Milibus typeface for your navigation menu, but the default weight of normal seems a little light to you, while bold is just too bold, to use the semi-bold face just add this to your custom.css:

/* Make the weight of the nav menu a little stronger for Milibus */
.custom ul.menu li.tab a {
	font-weight: 500;  /* semi-bold */
}

Again, do not specify the font-family in your custom.css file for elements that will use fonts from Typekit. Typekit handles the font-family for you; you do everything else in custom.css.

I hope this inspires you to get (more) creative with type on your web site!

The Thesis theme for WordPress is arguably the most advanced premium theme for WordPress-driven web sites. It combines fantastic layout flexibility (1-, 2-, and 3-columns, in various arrangements) with strong design customizability (colors for virtually every element are customizable, plus borders, padding, fonts and sizing, etc.) and terrific typography. Out of the box it looks great in all major web browsers, and can be customized wildly to achieve incredible diversity in visual design.

But, oddly, printing pages from a Thesis-based site will often remind you of how the web looked in 1996. That’s because by default the Thesis theme applies its styling only to on-screen display. Printing is entirely unstyled:

The gory details of the how and why are in a DIYThemes forum posting I made a couple days ago, Thesis prints unstyled by default. This is not good. Fortunately, it is possible to extend Thesis with PHP code, in ways that most themes would never dream of, and this gives us options for better printing.

The beginning of a solution is to add a stylesheet for print; the recommended placement is in thesis/custom/print.css. Then you add the link tag to your site via a hook function in your custom_functions.php file:

1
2
3
4
5
6
7

function add_print_stylesheet() {
    echo "\n";
    echo '<link rel="stylesheet" href="' . THESIS_CUSTOM_FOLDER . 
         '/print.css" type="text/css" media="print" />';
    echo "\n";
}
add_action('wp_head', 'add_print_stylesheet');

Now you have an active, but empty, print.css stylesheet. You still have unstyled content when you print. What’s next?

There are two approaches you can take:

• Create a new print.css stylesheet from scratch, adding only the minimum styling required to make printouts look the way you want. Ultimately, this can produce the best results.
• Import the on-screen stylesheets into the print stylesheet, and then add further additions, customizations, and overrides from there.

The second option will result in printouts looking exactly like your site does in a web browser. For some kinds of content this will not be ideal, but for most pages it’s better than being completely unstyled when printed, and it is a lot easier than writing a new stylesheet from scratch. If you’re looking for the quickest way to get to “pretty good,” this is the way to go.

To do it, put this in your print.css file:

1
2
3
4
5
6
7

@import url("../style.css") print;
@import url("layout.css") print;
@import url("custom.css") print;
 
#sidebars {
	display: none;
}

The #sidebars block removes your sidebars when printing. This is what most sites will want to do, but if you don’t, just delete lines 5-7.

The Aldosoft site is a mostly static content site, with a few pages describing who we are and what we do. When I started working on the redesign for the site, one of the main things I wanted to add was a blog for, well, articles like this one.

It’s pretty easy to use WordPress to build an entirely static content site, based on Pages. This is what the old Aldosoft site did. The setting for changing the Home page from a list of Posts to a static Page is easy to find, and obvious in use.

Putting a blog onto the site, “pushed off” the home page to a section at the same level as other pages of the site, is not so obvious. There’s a number of different settings which seem relevant, but how they all fit together is not clear. The documentation in the WordPress Codex (from which the title of this post is taken) is not written with the latest version of WordPress in mind, and makes it seem more complicated than it actually is.

Various Google searches turned up more semi-obsolete, incomplete, or just plain wrong answers. (Any article that says you need to add new files to your theme is outdated, at least for WordPress 2.8+ installations.) This article documents the simplest approach required to build a site like this one, a basic mostly-static WordPress site, where the blog is not the focus of the home page, but pushed down to the same secondary level as all the other pages.

You need to do three simple things:

1. Create a new page (not post), with no content (the page content will be replaced by your blog posts, once you finish step #2). This should be named whatever you want to call the blog section; here it’s just “Blog”. The page slug should be what you want to use for the URL to your blog; in my case it’s “blog”. (Told you this would be simple.)

2. Set the front page to “static” mode, and activate displaying your posts (your blog) on the new page. Settings > Reading > Front page displays:

   

   You are setting the “Front page” (or root of your site) to be the static page that will be the home page, and the “Posts page” to be the page you created in step #1.

3. Change your permalink structure, and use the Custom permalink structure to add your blog’s slug to the permalinks.

   

   This is optional if your preferred URLs don’t need to have posts appear “under” the main blog listing page. It will work either way.

There additional steps you will want to take if your theme does not automatically recognize the new Blog page, if you want to add links to your blog archives, etc. But those are steps you would need to take for any WordPress site, not specific to hosting your site’s blog at the secondary level.

I recently needed to install the PostgreSQL database server on my Mac for development with Ruby on Rails. I ran into a few gotchas, and while I was eventually able to Google and guess my way to success, it took a while. This installation guide is as much for me, 6 months from now, as it is for others who may wish to also install Postgres.

These instructions were current as of April 22, 2009, and were executed on Mac OS X 10.5.6 with Rubygems 1.3.2 and the Postgres 8.3.7 distribution. The shelf life of these instructions is probably brief, though they should work at least as a rough guide until the next major release of Mac OS X, or of Postgres.

Preferences and Biases

There are other Postgres + Rails instructions which recommend the use of either MacPorts or Fink. I personally dislike these solutions; part of it is having used Fink in its early days and having it screw up royally, and part of it is a sense that the efforts are misplaced. (Why not make your Open Source contribution of how to get a project properly compiled and installed on Mac OS X directly in the project itself?) In any event, I refuse to use either…though I agree that they have a place for people less comfortable compiling software directly from source code.

I also prefer not to use pre-compiled binary installations of Open Source tools, unless the maintainer has demonstrated a long-term commitment and expertise in building and maintaining the package. Marc Liyanage did a terrific job with PHP 5 for Mac OS X releases up through “Tiger.” MySQL is doing a great job creating Mac OS X installer packages for the MySQL database. But many binary installations either make odd decisions about where to put things, or don’t get maintained, or make module/configuration/packaging decisions different from what I need, or all three.

So I generally prefer to compile from source code, and install my additions to Mac OS X in /usr/local. Dan Benjamin explains the logic and benefits of /usr/local in exhausting detail, I won’t go into it further. Either you agree, and these instructions may be useful to you, or you don’t, and you should keep Googling.

Prerequisites and Preconditions

• These instructions are for Mac OS X 10.5 “Leopard” only.
• You need to be comfortable, or better yet confident, on the command line.
• You need to have Apple’s developer tools installed.
• You need to have current versions of Ruby on Rails and Rubygems installed.
• You need to understand what it means to update your $PATH environment, preferrably in ~/.bash_login. You do have a ~/.bash_login file, right?

But mostly this document assumes that you’ve already gone through the outstanding instructions for installing a complete Ruby on Rails development suite provided at Hivelogic. Indeed, if you didn’t use those instructions, at least mostly, you probably shouldn’t use mine either.

The Instructions

There are two things that need to be installed, the Postgres server and the Ruby gem for the Postgres database driver. You will also want to add a launchd task for starting and stopping the database server.

Installing the PostgreSQL Database Server

Postgres traditionally runs as a “daemon,” or background process, and manages all control to its files, especially its data. This requires that you create a dedicated user account and group, which only Postgres will use. While you could do this in the Accounts preference pane, it’s better to do this from the command line, so that the system won’t treat the Postgres user like a normal user. This is done with the Directory Service command line utility, dscl.

Before creating the Postgres user you need to pick out internal ID numbers for the user and group. You need to find a number that is not currently in use, so start by seeing what is in use. View the list of user accounts and ID numbers (note that some output is elided):

$ dscl . -list /Users UniqueID
_amavisd           83
_appowner          87
_appserver         79
[...]
_mysql             74
[...]
alderete           501
daemon             1
nobody             -2
root               0

Next the groups:

$ dscl . -list /Groups PrimaryGroupID
_amavisd                       83
_appowner                      87
_appserveradm                  81
[...]
_mysql                         74
[...]
tty                            4
utmp                           45
wheel                          0

Within these lists you want to find an ID number under 500 that is not in use. My primary source for these instructions recommending adding 100 to the ID for MySQL, which seems reasonable. It’s also probably helpful to find a number that is available for both the user and the group ID, so you don’t have to worry about which is which. From the output above, I chose 174, which met both criteria.

With chosen user and group IDs, create the user. Here we are creating a user with a $HOME of /usr/local/pgsql, the location where we will be installing Postgres. We’re also creating the user in such a way that it’s useful only as a daemon; it is not possible to log in to the system as this user, either at the normal login screen or via ssh.

$ sudo dscl . -create /Users/postgres UniqueID 174
$ sudo dscl . -create /Users/postgres PrimaryGroupID 174
$ sudo dscl . -create /Users/postgres HomeDirectory /usr/local/pgsql
$ sudo dscl . -create /Users/postgres UserShell /usr/bin/false
$ sudo dscl . -create /Users/postgres RealName "PostgreSQL Administrator"
$ sudo dscl . -create /Users/postgres Password \*

Now verify that the user was created as expected, by reading back the values from the system:

$ dscl . -read /Users/postgres
AppleMetaNodeLocation: /Local/Default
GeneratedUID: 0024E028-00A9-48FB-B14A-68026D442870
HomeDirectory: /usr/local/pgsql
Password: *
PrimaryGroupID: 174
RealName:
 PostgreSQL Administrator
RecordName: postgres
RecordType: dsRecTypeStandard:Users
UniqueID: 174
UserShell: /usr/bin/false

Follow a similar procedure to create and verify the group:

$ sudo dscl . -create /Groups/postgres PrimaryGroupID 174
$ sudo dscl . -create /Groups/postgres Password \*
$ dscl . -read /Groups/postgresAppleMetaNodeLocation: /Local/Default
GeneratedUID: 7A7F8760-455F-4315-84DD-2DA330AD9845
Password: *
PrimaryGroupID: 174
RecordName: postgres
RecordType: dsRecTypeStandard:Groups

With the dedicated user and group created, you can now download, compile, and install Postgres. The source code distribution can be downloaded from one of the Posgresql.org mirrors. If you use Safari to download it, be sure you’ve turned off the Open “safe” files after downloading option. (And leave it off, it is a known security risk.)

Move the archive to your preferred location (such as /usr/local/src), start a Terminal session there, and:

$ tar zxvf postgresql-8.3.7.tar.gz
$ cd postgresql-8.3.7
$ ./configure
[...]
$ make
[...]
$ sudo make install
[...]

Note: there may be options you want to enable with the configure script, such as encryption or authentication methods. Use ./configure --help to get more details.

Installing the software does not actually create a location to store the database data, or initialize the system databases. Do that next:

$ sudo mkdir /usr/local/pgsql/data
$ sudo chown postgres:postgres /usr/local/pgsql/data
$ sudo -u postgres /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
Password:
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.
[...]
Success. You can now start the database server using:
    /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
or
    /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start

You’ll want to create a Postgres user (distinct from the system user for Postgres), but before you can do that, you need to start the server. Below I describe how you can have Postgres start automatically when your computer boots, but for now, let’s just start it up manually:

$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start

Now create that Postgres user, and a default database for it to use. This is the account that you will eventually use in the database.yml file of your Rails applications. And finally, use the psql command line tool to verify that we’ve successfully created the user and database.

$ sudo -u postgres createuser alderete
$ createdb
$ psql
Welcome to psql 8.3.7, the PostgreSQL interactive terminal.
[...]
alderete=# \l
               List of databases
           Name           |  Owner   | Encoding 
--------------------------+----------+----------
 alderete                 | alderete | UTF8
 postgres                 | postgres | UTF8
 template0                | postgres | UTF8
 template1                | postgres | UTF8
(4 rows)
alderete=# \q

Note: The above illustrates creating a database user and new database, both named for my Unix account name, “alderete”. Using the Unix account name simplifies using Postgres’s command line tools, you won’t have to enter the Postgres account name every time. But that will only work if your name is “alderete” too. ;-) Instead, use your Unix (or “short”) account name instead! This will likely be visible in your command line prompt, but it will also appear in the list of users you generated at the beginning of these instructions.

Finally, add important Postgres directories to your various system paths. Add the following lines to your ~/.bash_login file:

export PATH="$PATH:/usr/local/pgsql/bin"
export MANPATH="$MANPATH:/usr/local/pgsql/man"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/pgsql/lib"

Be sure to source this file to activate the new environment settings:

$ . ~/.bash_login

Install the Postgres Ruby Gem

Normally installing a Ruby gem is pretty simple, but the Postgres database driver has native (compiled) components, and these need to be linked against the Postgres binary. The problem is that by default Postgres is only built for the hardware architecture of your computer (PowerPC or Intel), while the gem appears to try to link against both architectures. This causes an error, and the helpful suggestion that appears with the error message does not in fact work, producing the exact same error message.

The trick to getting past this is to set the preferred architecture right on the gem install command, like so:

$ sudo env ARCHFLAGS='-arch i386' gem install \
  postgres -- --with-pgsql-dir=/usr/local/pgsql
Password:
Building native extensions.  This could take a while...
Successfully installed postgres-0.7.9.2008.01.28
1 gem installed

(If you’re still using a PowerPC-based computer, change “i386” to “ppc”.)

This should allow the gem to install successfully.

Automatically Starting Postgres at System Startup

On my development systems I’m using the database constantly, and so I have it set to start up automatically, as part of my computer’s boot process. The “Leopard” way to do this is to add a launchd task to your system. This is a text file that you’ll save on your desktop, and then move to /Library/LaunchDaemons/org.postgresql.dbms.plist. The following was copied from my primary source (see below):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
    "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.postgresql.dbms</string>
    <key>UserName</key>
    <string>postgres</string>
    <key>GroupName</key>
    <string>postgres</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/pgsql/bin/postmaster</string>
      <string>-D</string>
      <string>/usr/local/pgsql/data</string>
    </array>
    <key>StandardErrorPath</key>
    <string>/usr/local/pgsql/logs/postgresql.log</string>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Once this file is in place, you can load it by restarting your computer, or with this command:

$ sudo launchctl load /Library/LaunchDaemons/org.postgresql.dbms.plist

If you can believe it, you’re done. Pour a cold one, or get right to it with rails mynewapp -d postgresql. Good luck!

Sources, Citations, and Credits

By far the most complete posting on this topic was
Working Software’s Building and Installing PostgreSQL on Mac OS X, which covered installing Postgres from source completely. While the instructions above are copy/pasted from my Terminal windows, I was copying lines directly from this article to paste into Terminal in the first place.

The one thing that wasn’t covered in the above article was installing the Ruby gem for Postgres, which is required to use Postgres in Rails. The normal gem install [gemname] produced errors, and most suggestions I found didn’t work any better. What finally did work was including the “-arch i382” option directly on the gem installation line, which appears to be orginally published towards the bottom of PostgreSQL on Leopard for Rails: A few notes. (A few other posts repeat this advice, so I’m not sure who first published it.)

Finally, although it’s quite dated, the Apple Developer Connection article PostgreSQL on Mac OS X provides useful background information, and notes about using Postgres from other languages besides Ruby.