Thoughts on branding, design, writing and life by Kevin Potts. Established 2003.

Improve Search Results in Textpattern

Textpattern has a decent search function out of the box, but there are several simple ways in which to get more from your results page. These tips cover dedicating a page to search, showing the results count, restating the search term, and searching within specific categories and/or sections.

One contributing factor to Textpattern’s power as a content management system is its inherent templating flexibility. This clean slate is key when tweaking and optimizing search results. In fact, it’s so open, that customizing the search function is one of the leading questions within the forums.

Textpattern’s out-of-the-box functionality is basic, and the tags are not particularly robust. However, with some creative forms and some first-class plugins, the usability of your search results can take leaps forward in terms of usability.

Dedicate a Page and Section to Search

By default, Textpattern will re-use the default page to display search results. This is not always convenient. To separate these two things, create a new page and section dedicated to displaying search results.

First, go to Presentation > Pages and duplicate the default page, calling the new one “search.” Then go to Presentation > Sections, create a new section called “search,” and make sure to assign the page you just created as the template, and set all options to “no.”

Somewhere in your templates, you will have a <txp:search_input /> tag. To assign the section you just created, add the attribute section="search". (This only works when Textpattern is in clean URL mode. In messy mode, check out this older but still functional tutorial from Justin French.)

This allows for full customizion of the search page without mucking about the default page.

Show the Result Count

Textpattern provides the tag <txp:search_result_count /> that will display the number of returned hits. However, in order to function, it must be accompanied by a <txp:article /> tag, which actually counts the results. This is best illustrated through a code example:

<txp:article pgonly="1" />
<txp:search_result_count />
<txp:article form="search_results" />
</txp:if_search />

The <txp:article /> tag with the attribute pgonly="1" performs the actual count; the following tag is used to display the count. The <txp:search_result_count /> must come second.

Restate the Search Term

One great way to improve the usability of search results is to restate the search string at the top of the results page. This not only reminds them of their query, but will help explain if no results appeared because the search term was misspelled.

Textpattern does not supply this functionality natively; instead, we have to rely on the plugin tru_tags. Besides being an amazing tagging plugin by itself (this site uses it), it provides a sweet little bonus tag <txp:tru_tags_search_parameter /> that returns whatever the user typed into the search box. For example, using the result count above, you could run both of these techniques in tandem:

<p>There were <txp:article pgonly="1" /><txp:search_result_count text="results" /> for the search "<txp:tru_tags_search_parameter />."</p>

This would return something like There were 8 results for the search “your mom.” It really is as simple as that.

Restrict Search Results to a Section or Category

I recently had a project that required the capability to search within only a few categories and a particular section, in addition to a primary site-wide search. The ability to search just one section is fairly well documented. However, the ability to search within particular categories requires a bit more legwork.

The plugin chh_article_custom serves as a replacement to the <txp:article_custom /> and <txp:article /> tags. In addition to some general bells and whistles, it has a few unique bits that include an expansion on the searchall attribute. When the variable is set to searchall="none", search results are restricted to the attributes of the tag. For instance:

<txp:chh_article form="search_results" limit="999" searchall="none" section="bigcats" category="Tigers,Lions,Panthers" />

This will restrict search results to the section “bigcats” as well as the categories “Tigers,” “Lions” and “Panthers.” This is very useful for complex sites where sections and categories are used to isolate specific types of content.

What I Cannot Figure Out

All of this aside, the one major deficiency I find in Textpattern’s search is that the engine only goes through the titles and bodies of articles — I have yet to find a way to get TXP to also search excerpts, categories, custom fileds, posted dates and other pieces of data. There have been some very hackish solutions posted, but even after tromping around publish.php, the only thing I found was a reliable way to break all search functionality completely. If anyone has any non-programmer-friendly clues, let me know.

, , ,

commentary + criticism


wrote the following on Thursday January 10, 2008

Useful article but it’s worth noting that with the imminent release of Textpatterm 4.0.6 you will not longer need the 2 plugins you mentioned. The tag search_term has been added also the article tag will support comma separated lists of sections and categories. Woo Ho!


wrote the following on Friday January 11, 2008

Ah, well there you go. Thanks for the info. I hope those new tags work as well as the plugins.


wrote the following on Sunday January 20, 2008

Good article. I liked the section on restricting search results to specific sections or categories.

I just want to mention that Textpattern as of 4.0.5 does actually natively provide a tag for restating the search term; which is:

<txp:page_url type="q" />

Jamie Knight

wrote the following on Wednesday January 23, 2008


Thanks for the nice short article. Will work nicly on site which need to be implimented today while we are waiting for 4.0.6.

Jamie & Lion


wrote the following on Saturday January 26, 2008

Thanks for the comments. Unfortunately I do not closely follow the development news. Since Textpattern has been completely unpredictable in its release schedule, I have to write about what can be done in the latest stable version, not what might be possible in a future version. Usameh, thank you for enlightening us on that technique -- I will give it a shot.

Steve Lam

wrote the following on Sunday February 3, 2008

I believe this plugin allows you to search through other fields in the db like custom fields etc. Although the manual at first glance seemes overwhelming and maybe a little too advanced for most people.

As for TXP development, many prominent plugin writers have started a fork of their own named xPattern, after the devs turned down an offer from members of the community to have a community driven branch.

Markus Merz

wrote the following on Friday July 18, 2008

Well, beside tweaking the core search function which I did from the very 1st beginning just recently I made an astonishing discovery: The Google search box is my new friend and favorite and has replaced the standard TXP search form for my site.

The ‘fuzzy search’ provided by the Google site search is much better when it comes to relevance compared to accurate full text ‘word find’.

Not only does the Google search result page (embedded in my site design) list articles but also TXP search result pages, category pages and tag search result pages which in TXP would be totally different pages(!).

Side note: If you use sub-domains these are also included in the Google SERP. I.e. I use a news aggregator in a news. sub-domain.

I just can recommend to test the good old Google search box.

Dominik Lenk

wrote the following on Wednesday January 21, 2009

The plugin @wet_haystack@ allows you to search through other custom fields.