Last updated: 2006-01-09 23:02

Context-sensitive operation

Like <txp:article /> (and unlike <txp:article_custom />), chh_article_custom acts differently depending on whether it is called in list-mode or single-article mode.

To allow the tag to serve both single articles and lists of articles, specify a single-article form with the form attribute (_listform_ can be left unset, in which case article lists will use the default article form). If you want chh_article_custom to always return a list like <txp:article_custom />, simply omit the form attribute.

Multiple categories and sections

More than one category or section may be specified as comma-separated lists.

<txp:chh_article_cutstom section="pets,livestock" category="dogs,cats,chickens" />

Additionally, the special setting of category="?" (or section="?") will use the currently browsed category (or section) in the same manner as <txp:article />.

Hierarchical categories

For each category specified, whether by the category attribute or by browsing to that category, articles are returned from it and all of its subcategories.

For example, consider a category layout like this:

  • Dogs
    • Chihuahua
    • Retrievers
      • Golden
      • Labrador
  • Cats
    • Maine Coon
    • Persian

<txp:chh_article_custom category="Dogs,Cats&Persian" children="y" />

The above tag will create a linked list (because no listform is specified) of all articles having either Category1 or Category2 set to Dogs, Chihuahua, Retrievers, Golden, or Labrador; or having Category1 set to Cats and Category2 set to Persian (or vice versa).

It will not return an article with Category1 set to Cats and Category2 set to Dogs.

This feature, which requires one extra database query per page, is disabled by default (children="n").

Browse-by-category name munging

Since Txp’s category implementation doesn’t support true hierarchical categories (ie, you can’t have baz as a subcategory of both foo and bar), here is one somewhat weaksauce workaround.

<txp:chh_article_custom category="?News" />

When the current category is empty, such as on a section page or the home page, the above tag will return articles from News only, so we can give general pet news. But when browsing the Dogs category, the tag returns only DogsNews articles.

The "?" is a placeholder for the currently selected category.

Advanced date selection

To display a list of all articles published yesterday, use the day attribute:

<txp:chh_article_custom day="-1" />

Which means to list articles where the day of publication is today’s date minus one. That is, if today is Wednesday, the tag would list articles published anytime from midnight to 11:59pm Tuesday. So day="-2" would list articles published two days ago (Monday) and day="+1" would list articles to be published tomorrow (Thursday).

Likewise, the month attribute can also accept a numeric descriptor so that month="-1" lists all articles published last month—the previous calendar month, not within the last 30 days.

To list articles published in the last 30 days, use the time attribute.

<txp:chh_article_custom time="-30 days" />

Or in the last 2 hours (time="-2 hours"), or the last year (time="-1 year").

Be aware that day and month work in concert with time. So day="+1" will only produce output if time="future" (because time="past" is the default).

Finally, all three attributes can accept two comma-separated date/interval descriptors for the start and end points of the list. So day="-6,+1" will list articles from six days ago up to, but not including, tomorrow. In other words, any day in the last week, including all of today.

When no second argument is included, time default’s the end point to the current time. day and month default to the specified day/month plus one, so that if no ending day/month is specified, the tag will return entries from a single day/month.

To show all articles published this month, use month="+0" (the +/- is not optional).

Examples

All of yesterday’s posts day="-1"
All of todays posts, including yet-to-be-published articles time="any" day="+0"
All of tomorrow’s posts time="future" day="+1"
Posts published from six months ago to today time="-6 months"
Posts published in any of the last 6 months, including this one months="-5,+1"
Posts from last month month="-1"
Posts published this month month="+0"
Posts due to be published this month time="future" month="+0"
Posts published since this day last month time="-1 month"

Note: day and month calculations are based on the database server’s local time, not the timezone specified in your Txp preferences. I will look into the possibilities of performing the appropriate timezone calculations in later versions.

chh_article can return search results just like txp:article, with some additional options for the type of search conducted, set by the searchmode attribute:

searchmode="natural" enables MySQL’s standard full-text weighted search. searchmode="boolean" enables MySQL’s boolean-mode full-text searching, allowing more complex (google-like) search queries.

See the MySQL Manual’s Full-Text Search Functions documentation for more information on full-text methodology and syntax.

This feature is not meant to replace any advanced search plugin but to give a few options over the default Txp exact-phrase search.