ode - a simple personal publishing platform for the web

You don't know Ode until you know about Ode's query string parameters. Learn more.

Ode's query string parameters

Let's take a look at the pattern of a normal request to Ode:

scheme://base_url/path/year/month_num/month_day/filename.theme \ ?query string

http://sample.net/cgi-bin/ode.cgi \ /dir1/dir2/dir3/2009/01/15/ \
some_filename.some_theme? \
first_param=first_value&second_param=second_value \
&third_param=third_value
|----------------------------- req_string -----------------------|

|http://sample.net/cgi-bin/ode.cgi| |/dir1/dir2/dir3/| \ 
|--------- base_url --------------| | ----- path ----|

|2009| / |       01|  / |      15| / \
|year|   |month_num|   |month_day| / 

|some_filename| . |some_theme| ? \ 
|- filename --| . |- theme --| ?

|first_param=first_value&second_param=second_value& \
third_param=third_value|
|----------------------------- query string ---------|

There may be any number of parameter name/value pairs included as part of a query string. We can't know what all of them might be. For example, some addin, which does not yet exist, may operate by reading the value of some as-of-yet unknown parameter.

However, the script itself recognizes a small set of parameters. Knowing what these are and how they are used is important to getting the most out of using Ode.

Parameters recognized by ode.cgi (in the absence of any addins) include:

1. start_date
2. end_date
3. date_pattern
4. num_posts
5. first_post
6. site_look_date

It's probably best to think of these as 3 groups, such that parameters within each group are related and can work in combination.

Group 1: Date restriction parameters

1 - start_date
2 - end_date
3 - date_pattern

Group 2: Navigation parameters

4 - num_posts
5 - first_post

Group 3: Theme related parameters

6 - site_look_date

Let's take a look at each of these groups

!--jump--!

Group 1: Date restriction parameters

• start_date
• end_date
• date_pattern

You may already know that a client may include one or more date restriction components as part of the path. These path-based date restrictions function as something like dynamic date-based quasi-categories.

They limit the entries returned in response to the request to only those items with a post date matching the specified year, month, day, ..., second

For example, given the request

http://sample.net/cgi-bin/ode.cgi/technology/apple/2009/03/01/

'2009/03/01/' is a path-based date restriction, which instructs the script to limit content returned to entries with a post date of March 1st, 2009.

These path-based date restrictions are only one of two mechanisms the script employs that allow for date related requests.

There is also a parameter-based date range feature.

The relevant parameters are:

1. start_date
2. end_date
3. date_pattern

These can be used individually or in combination.

When used in combination they should be flexible enough to specify just about any date range you might be want.

Parameter: start_date

?start_date=20090128

If only the start_date parameter is used, the response includes posts from (and including) the specified start_date going forward.

Partial dates match the beginning of the period. e.g.,

start_date=2009

is equivalent to start_date=20090101

The value of the start_date parameter is a 4, 6, or 8 character string of digits in the form:

YYYY[MM[DD]]

YYYYMMDD - 4 digit year, 2 digit month, and 2 digit day

20090128

YYYYMM - 4 digit year and 2 digit month

200901

YYYY - 4 digit year only

2009

Underscores are allowed between components of the start_date string to improve readability. So the following are all valid start_date values:

'2009_0128'
'200901_28'
'2009_01_28'

Parameter: end_date

?end_date=20090128

If only the end_date parameter is used, the response includes posts to (and including) the specified end_date and before.

Partial dates match the end of the period. e.g.,

end_date=2009

is equivalent to end_date=20091231

The value of the end_date parameter is a 4, 6, or 8 character string of digits in the form:

YYYY[MM[DD]]

YYYYMMDD - 4 digit year, 2 digit month, and 2 digit day

20090128

YYYYMM - 4 digit year and 2 digit month

200901

YYYY - 4 digit year only

2009

Underscores are allowed between components of the end_date string to improve readability. So the following are all valid end_date strings:

'2009_0128'
'200901_28'
'2009_01_28'

The start_date and end_date parameters can be combined. The result is a range of dates bracketed at the beginning by the start_date value and at the end by the value of end_date.

Example 1:

?start_date=20070420&end_date=2009_0420

Matches entries with post dates starting on April 20th, 2007 and ending on April 20, 2009. All other posts are excluded.

Example 2

?start_date=2009_0101&end_date=2009_1231

Matches all entries in 2009 (i.e with post dates from 2009_0101 to 2009_1231 inclusive.)

Example 3

?start_date=2009&end_date=2009

Note that the following values match exactly the same set of posts as the previous example.

This is not a special case. It follows from the rules we have a already discussed. Remember that partial start_date values match the beginning of the given period and partial end_date values match the end.

Question: What if the end_date is earlier than the start_date?

Answer: The end_date parameter is ignored.

Example 4

?start_date=20091231&end_date=20090101

Because the value of end_date is earlier than start_date, the end_date parameter is ignored entirely and the parameters match all entries from Dec 31, 2009 to the current date and time.

Parameter: date_pattern

?date_pattern=2008_0214

As the name suggests, date_pattern is a pattern match mechanism (albeit a very simple one) which greatly improves the flexibility with which we can specify dates.

date_pattern is an 8 character string of digits and a single wild card, '-'.

Digits are literal characters in the string, while the wild card will match any single digit.

Important: Unlike start_date and end_date, date_pattern does not allow date strings of fewer than 8 characters.

This 8 character string consists of three components:

1. four digit year (e.g. '2008')
2. two digit month (e.g. '01')
3. two digit day (e.g. '01')

Any of these components can be replaced by wild cards '-', but the component must be replaced in its entirety.

The following are all valid date_patterns:

----1231
2008--31
200812--
----12--

(Of course, there are many more valid date patterns.)

On the other hand, the examples below are invalid:

--081231, Year is --08

The year component must consist of either 4 digits or 4 wild card characters (not a mix of both).

200-1231, Year is 200-

The year component must consist of either 4 digits or 4 wild card characters (not some of each).

20081-31, Month is 1-

The month component must consist of either 2 digits or 2 wild card characters (not a mix of both). Again, individual components (year, month, day) must consist entirely of digits or wild card characters. How are these patterns interpreted? Let's look at a few examples:

date_pattern=----0214, All posts from Feb 14th in any year.

date_pattern=------14, All posts made on the 14th of any month and year.

date_pattern=2008----, All posts from 2008 regardless of month or day

date_pattern=----03--, All posts in March regardless of year or day.

The following rules apply to start_date, end_date, and date_pattern (except that in the case of date_pattern, the rule applies only for those components which are not wild).

Remember that the format for all of these date parameters is: YYYYMMDD.

YYYY

The value of YYYY must be greater than or equal to EARLIEST_YEAR (1969 by default).

MM

The value of MM must be one of: '01', '02', ..., '12'.

There are only twelve months of the year, and MM must specify one of them.

DD

The value of DD must be one of: '01', '02', ..., '31'.

There are at most 31 days in any month, and DD must specify one of them.

Note that the script does not require that MM and DD together specify a valid date. ( e.g. it will not complain about 2009_0231).

Why?

For two reasons:

1. This isn't intended to be a robust date checking mechanism, just a simple test to avoid the sort of confusion that might result from inadvertent errors.

2. The script behaves sensibly even when these date range parameters are invalid.

For example: '2008_0231'

If this were the start_date value, the script would return entries with post dates after 0231, beginning with 0301.

This is the same range that would be returned for the valid date 0228.

Likewise, if this were the end_date value, the script would return entries with post dates before and including 0231,including all entries with post dates through 0228, but not 0301.

Again, this is exactly how the script would behave with the valid date.

Of course, an invalid date_pattern, for example:

----0231

would most likely return no posts, because there should be no entries dated Feb 31st.

Even in this case, it can be argued that the response is valid, because we are accurately providing the client all of the matching posts (in the same way that we would for any valid date_pattern).

How do these work together?

IMPORTANT: Parameter date ranges override path based date restrictions.

Given a request like:

/Technology/Software/2009/04/19/index.boku?start_date=2008

the path date restriction is silently ignored.

!Make sure you understand this point!

start_date and end_date can be used together to define a range of post dates starting at start_date and ending with end_date (as described above).

date_pattern can also be used with start_date and end_date.

This is also straightforward.

Candidate posts are compared to date_pattern first, and then if they fit the pattern, are checked against start_date and end_date parameters.

To be included in the response, a post must satisfy all of the conditions.

Group 2: Navigation parameters

• num_posts
• first_post

Parameter: num_posts

The num_posts parameter overrides $config::num_posts and dictates the total number of posts returned in response to the request.

More accurately, there will be no more than num_posts entries. (Of course, we can't return more posts then the total number that satisfy the request, regardless of the value of num_posts.)

The value must be a positive integer (i.e. a string of digits 0 - 9) or 'all'. (Note that this is a case-insensitive match, so all of the following are recognized: 'all', 'All', 'ALL', 'AlL', ...).

An integer is a request for a specific number of posts. The word 'all' specifies that every post matching the request should be returned.

So for example, given a request like:

http://sample.net/cgi-bin/ode.cgi/?num_posts=all

The script will return a single page containing every post on the site.

Parameter: first_post

The first_post parameter specifies the first post included on the page returned to the browser.

All posts before first_post (in sorted order) are skipped.

The value of first_post must be a positive integer (i.e. a string of digits 0 - 9).

For example, given the request:

http://sample.net/cgi-bin/ode.cgi/?first_post=6

Posts 6 - 15 are returned with the page (assuming $config::num_posts is 10, the default value).

Together, these two parameters can be used to create links allowing a browser to navigate forward and backward through successive pages of posts.

Let's say we have a site with 100 posts and we want 10 posts displayed per page.

At the end of the first page of posts we might want to include a 'next' link to the next page of 10 posts (11 - 20). That link would look something like:

<a href="http://sample.net/cgi-bin/ode.cgi/ \
    ?first_post=11&num_posts=10">next 10 posts</a>

From the second page, we might want to navigate forward to the next page (21 - 30) and back to the first page (1 - 10). These links would look like

<a href="http://sample.net/cgi-bin/ode.cgi/ \
    ?first_post=21&num_posts=10">next 10 posts</a>

<a href="http://sample.net/cgi-bin/ode.cgi/ \
    ?first_post=1&num_posts=10">previous 10 posts</a>

(Tip: Ode provides these next and previous posts links automatically.)

Group 3: Theme related parameters

• site_look_date

Parameter: site_look_date

The site_look_date parameter hooks into the script's theme mechanism allowing clients to request a previous version of a named theme.

The value of the site_look_date is the same sort of 4, 6, or 8 character string of digits as start_date and end_date:

YYYY[MM[DD]]

YYYYMMDD - 4 digit year, 2 digit month, and 2 digit day

20080128

YYYYMM - 4 digit year and 2 digit month

200801

YYYY - 4 digit year only

2008

Underscores are allowed between components of the site_look_date string to improve readability.

The following are all valid sitelookdate strings:

2008_0128
200801_28
2008_01_28

The theme used to build the page will be the version of the named theme that was in use on the provided site_look_date, (or the current version of the theme if there is no more appropriate version).

Read about themes for more info.

Next

That completes our little tour which included the following stops:

• Introduction
• Posts
• Themes
• Date restrictions
• Parameters (this post)

Hopefully you feel like you understand Ode a little bit better. There is more to discuss. We're just getting started. Check back soon.