Navigate posts by category OR date. Do you want to see what you post last Mar 29, or every Mar 29th (or the 29th of any month for the past 3 years)? You can do that.

Date restrictions

Ode recognizes two forms of date restriction:

1. path-based date restrictions
2. parameter based date ranges

1 - path-based date restrictions

Note: This feature can be disabled in the config file by setting the value of the $use_path_date_restrictions to false.

The path-based restrictions allow the visitor to specify a target date as part of the path. Posts are compared against the date in the path and only entries with matching dates are returned.

Example 1

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

is a request for all posts in the /technology/apple/macosx/ category with a post date of January 1st, 2009.

Example 2

http://sample.net/cgi-bin/ode.cgi/technology/2007/

Is a request for all posts in the /technology/ category with date in the year 2007 (i.e. Jan 1st, 2007 - Dec 31st, 2007).

2 - Parameter based date ranges

Note: Read about Ode's recognized query string parameters for more information about these date range parameters. (put link here)

The script also recognizes three date related parameters:

• start_date
• end_date
• date_pattern.

!--jump--!

start_date is used to define a lower boundary (i.e. an earliest date) for posts returned in response to the request. Selected posts must be dated on or after the specified start_date.

The end_date parameter specifies an upper boundary (i.e. a latest date) for selected posts. A qualifying post must be dated on or before the end_date value.

date_pattern adds some necessary flexibility to the script's date matching capabilities by introducing a very simple wild card mechanism.

The date_pattern will be in the format YYYYMMDD:

• YYYY - four digit year (e.g. '2009')
• MM - two digit month number ('01' - '12')
• DD - two digit day of the month ('01' - '31')

Each of YYYY, MM, and DD are composed of digits 0 - 9 except that any of these may be wild.

Wild portions of the date_pattern match any value.

There is a single wild character '-', which always replaces *a single digit*. **IMPORTANT**: Entire portions must be wild for the value to be considered valid.

Let's look at some examples of valid date_pattern values:

2009_0101, All posts returned must be dated 2009\_0101

----_0101, Posts from Jan 1st of any year

2009_--01, Posts from the 1st of any month in the year 2009

2009_01--, Posts from any day in the the month of Jan 2009

----_01--, All posts from Jan regardless of year or day of the month

(Note that underscore characters are allowed between year, month, and day to improve readability.)

The following are not valid date_pattern parameter values:

--08_0101, Year must be wild or literal, not a little of each.

08_0101  , The pattern must conform to the format YYYYMMDD

Additional notes about date restrictions:

1 - The date range parameters can be used in combination.

That is, any or all of start_date, end_date, and date_pattern may be included with any request.

2 - The path-based restrictions and date range parameters are mutually exclusive, with the parameters taking precedence over the path-based dates. This means that if a path-based date restriction is used along with any of the parameters, the path restriction is completely ignored and only the parameter is enforced.

More about path-based dates

Path 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, ...

year,
year, month,
year, month, day
year, month, day, hour
year, month, day, hour, min,
year, month, day, hour, min, sec

This is essentially what happens with path-based categories as well (i.e. posts returned must match the requested path).

Example 1

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 3rd, 2009.

Considering the rest of the path, the request targets posts matching the date 2009/0301 which are also found in the category 'technology > apple' (including subdirectories of technology/apple/).

Example 2

http://sample.net/cgi-bin/ode.cgi/2007/

is a request for entries with a post date in the year 2007.

Example 3

http://sample.net/cgi-bin/ode.cgi/2009/12/28/23/59/59/

This very specific request targets entries with a post date of: Dec 28 2009, 11:59:59p.

Of course we might expect that at most a single post would satisfy this request. The script supports these very specific date restrictions (down to the sec) in order to allow for very precise date-based permalinks.

About Permalinks

Ode naturally supports category-based permalinks. So why use date-based permalinks?

Category-based permalinks work just fine and because Ode depends on the file system as its content database we know that category-based permalinks are always unique. (We cannot accidentally create two posts with the same name in the same category because the operating system won't allow it.) Because of this, any reference which includes both a filename and path is a suitable permalink.

The trouble is that these permalinks will break if the posts are moved.

It's reasonable to assume that the site maintainer will, at some point, need to relocate at least a single post.

Yes, we can handle those changes through some sort of redirection, but

a. setting up the redirection can be a pain,

b. because it's a pain, some people won't bother, and we should strive to avoid breaking the web (even just our own very small corner of it) whenever possible.

A post date is intended to be the date when the post was first added to the site. Because a post can never be first added to the site a second time, this date should not change.

Date-based permalinks should prove to be robust under Ode because of steps taken with the script to ensure that post dates do not change unexpectedly (even if a post is copied, moved, etc.).

Unfortunately, date-based permalinks are not guaranteed to be unique the way that category permalinks are.

Though we can't force the OS to allow us to create two identically named files at the same path even if we wanted to, it is technically possible to create two posts with the same name and post date.

Note that in practice this should never happen unintentionally. Post dates are computed automatically, and it seems highly unlikely that an author (or even multiple authors working on the same site) will create two identically named posts at exactly the same time (to the second).

If this is a concern for you, the possibility of conflicts can be eliminated though the use of an informal naming convention which guarantees uniqueness.

A couple of final notes about path based date restrictions:

1 - Filesystem path components must precede date restrictions.

2 - The names of actual path components (the names of directories under $config::document_root) must not consist of only digits.

Any request for such an address is likely to cause problems for the path-based date restriction mechanism. What's worse, it would be treated as a date restriction, which is certainly not what you want.

Let's repeat that, so there is no confusion:

1 - Real path components (categories) must precede path-based date restrictions whenever both are included as part of the requested address.

This means that the only valid elements of the requested address that can appear after the date restriction are:

*filename (some_post) *suffix (html) *the query string (?first_param=first_value&second_param=second_value)

2 - Path components (i.e. directories under the site's document root) must not consist of only digits.

Category names may contain digits, but must also include at least one non-digit character. (Where a digit is any character meeting Perl's definition of a digit, i.e. matching \d.)

There is no such restriction on filenames.

Finally, remember that the path-based date restriction mechanism can be disabled.

This is accomplished by setting the value of the appropriate setting in the config file ($use_path_date_restrictions) to false. When the value is false, all of the behaviors related to date-based path restrictions are essentially ignored (skipped), with the result that components of the path which appear to be dates are treated like any other element of the path.

For example

http://sample.net/cgi-bin/ode.cgi/dir1/dir2/dir3/2009/01/

If $use_path_date_restrictions is false, '2009/01/' is treated like any other element of the path.

In this case, the script interprets the URL as a request for all posts in the '01' subcategory, of '2009', itself contained in 'dir3' and so on.

Next

As you know, you communicate with Ode by issuing requests in the form of a URL. The query string is an important part of the URL which allows you to pass information and instructions to the server. You don't know ode if you don't know about its query string parameters