Ode's themes really are simple. This post tells you everything you need to know to use them effectively (Part 2 of 2).
This is a continuation of 'Everything you need to know to successfully use Ode themes Part 1' which talked a lot about non-dated themes, and how ode handles those. I ended that post with a short introduction to dated-themes and the use_site_look_date setting (which is found in the config file). I'll start by repeating that short introduction and then I'll talk about how Ode behaves differently when dated themes are enabled, i.e. when use_site_look_date is true.
Like the first part, this post is long, and so you may want to read this post with the text_page theme (which is little more flexible and better suited to reading longer content).
Before I get started though, I want to say that I recommend everyone use dated themes. (Of course you're free to ignore this advice.) Dated themes are really no more complicated than non-dated themes and I believe that the added functionality is beneficial. (Keep reading.) Furthermore, even with dated themes enabled, you don't necessarily have to do much with them, but you will make it a little easier on yourself should you choose to embrace dated themes at some point in the future.
Dated themes allow a site maintainer to save previous versions of a theme as changes are made over time. These dated variants of the same theme can be used to recreate the look of the site from any point in time (i.e. you can recall any prior version of a theme).
The config file includes a setting labeled 'use_site_look_date'. This variable acts as a mode toggle (on/off switch).
When use_site_look_date is true the dated themes mechanism is enabled, and when the same setting is false, it's disabled.
Dated themes are identical to non-dated themes with the single exception of the name of the directory enclosing the theme.
Compare:
You will recognize the first as the text_page theme used in the examples throughout Part 1. The second is the same text_page theme but we have appended a dash followed by a date suffix.
The suffix indicates the date when the theme was installed (i.e. copied to some themes directory).
Every dated theme follows this same form:
theme name
a dash
a date suffix with the format YYYYMMDD, with underscores allowed between elements of the date suffix to improve readability.
theme_name-YYYYMMDD
Here is the crucial point:
When config::use_site_look_date is true non-dated themes are ignored. When config::use_site_look_date is false dated themes are ignored.
You can think of use_site_look_date as a switch flipping between dated and non-dated themes. You need to understand that when the setting is true all of the non-dated themes (i.e. any theme not ending in a date suffix) are completely ignored. As far as the script is concerned they don't exist. The same thing is true of dated themes whenever use_site_look_date is false.
What does a dated theme look like?
Expect for the date suffix following the theme name, they are identical to non-dated themes.
Borrowing an example from the first post, let's look at a non-dated theme titled 'text_page'.
text_page/
content_type.text_page
date.text_page
page_no_posts.text_page
page.text_page
text_page.css
The dated version of that theme would look something like
text_page-2010_0421/
content_type.text_page
date.text_page
page_no_posts.text_page
page.text_page
text_page.css
How do you convert a non-dated theme to a dated theme? Just add a valid date suffix to the end of the theme name in the title of the enclosing folder.
text_page/ -> text_page-2010_0421/
content_type.text_page
date.text_page
page_no_posts.text_page
page.text_page
text_page.css
Notice that you do not add the date suffix to any of the components of the theme.
The date suffix is not considered to be part of the name of the theme. The name of the theme 'text_page-2010_0421/ is 'text_page'.
The title of a dated theme consists of
The date suffix may include underscores as separators between components of the date. This is intended to make the date suffix more readable.
Any of the following are valid dated themes:
text_page-20100421
text_page-2010_0421
text_page-2010_04_21
text_page-2010______04__21
By comparison, these are not valid dated themes:
text_page
(Non dated themes are ignored when the use_site_look_date setting is true.)
text_page-20_10_04_21
(The optional underscores can only be placed between elements of the date suffix YYYY, MM, DD.)
text_page-2010_4_21
(The date suffix must match the format YYYYMMDD. Single digit months are not allowed.)
The date suffix should indicate the date when the theme was first put into use.
A simple use case:
Let's say that I'm looking forward to a trip to Europe. I'm planning on posting to my site while I'm on the trip. To celebrate my adventure I want to change my theme so that it looks and feels like a travel journal. Maybe typically I have a pretty no-nonsense tech or development blog. But this trip is a big deal for me, and I'm really getting into it, and I want to channel my excitement and the anticipation into a fun project, so I decide to make the new theme.
The theme I use is titled 'html' but I have dated themes enabled and the current version of the theme is:
html-2010_0101
(By the way, this would indicate that I started using the current version of the theme on Jan 1st, 2010. There may also be other earlier versions available.)
OK, I'm leaving for my trip on May 1st 2010, and returning May 15th. For that two week period I want my site to look like a travel journal. Until then, and after, I want to use the standard theme.
To accomplish this, I could create two additional dated variants of my html theme.
html-2010_0501
html-2010_0516
Assuming there are no other no other themes installed, the themes directory at the root of my site will look like:
themes/
html/
html-2010_0101
html-2010_0501
html-2010_0516
'html-2010_0501' is the new travel journal site, and 'html-2010_0516' is nothing but a copy of the original theme (let's say it also includes a few subtle changes like a new header for example).
On 20100431 a request for the site root like
http://sample.net/cgi-bin/ode.cgi/
would use the standard 'html-2010_0101' theme
As of May 1st, the same request would automatically use the travel journal variant, html-2010_0501.
Finally, as of May 15th, the day after my trip, that request would automatically use the version dated 'html-2010_0516', which resembles the original theme and not the travel journal variant.
So, using dated themes we can postdate theme variants and have the script display the site design we want, when we want. That's a pretty neat trick, but what's more interesting is that we can later ask Ode to show us what the site looked like at some point in the past.
Let's say it's a year later, and I want to reminisce about my trip and maybe share the experience with someone that I've just met. Of course my site is no longer using the elaborate travel journal theme I created. In fact it may look totally different from the standard theme I was using at the time.
I could just ask Ode to show me the posts I made while I was on my trip. That request would look something like:
http://sample.net/cgi-bin/ode.cgi/?start_date=2010_0501&end_date=2010_0515
(Note the use of the start_date and end_date parameters.)
I can also ask Ode to display the site using the same theme that was in use at that time using the site_look_date parameter. (This parameter name explains why the config setting that enables and disables dated themes is called use_site_look_date).
That request would look like:
http://sample.net/cgi-bin/ode.cgi/?start_date=2010_0501&end_date=2010_0515&use_site_look_date=2010_0501
I'm asking Ode to show me the theme that would have been used in answer to the same request on 2010_0501. (I could have chosen any date from 0501 - 0515 since the same theme was in use throughout.)
Of course themes evolve more incrementally for other, more mundane reasons.
With Ode's dated themes, we can preserve that history and roll back the changes whenever we like.
Creating a new dated theme variant, while preserving the original couldn't be any simpler. Better yet it mimics what you already do when you make changes to a theme.
Start with a theme like the one from the example above:
html-2010_0101
Create a copy of the theme you want to change.
You'd want to do this anyway, so that you could easily revert to the old version without having to reverse all of your changes manually.
Rename the copy, changing the date suffix to today's date, or whatever date you want associated with the theme.
That's it. Now, modify the new dated theme. The other is still there, unmodified and intact. It already has the correct date attached (because the suffix specifies the date when the theme was first used, and you took care of setting that date when you created that version).
That explains how to set up dated themes.
Remember that the config setting use_site_look_date must be true or all of your dated themes will be ignored.
But that still leaves a couple of questions:
With the dated themes feature active, requests look almost exactly the same as they do when the feature is disabled.
You can either explicitly request a theme by name
For example
http://sample.net/cgi-bin/ode.cgi/some_post.text_page
http://sample.net/cgi-bin/ode.cgi/index.text_page
Or you can leave the theme name out of the request to use the default theme (set in the config file).
For example
http://sample.net/cgi-bin/ode.cgi/some_post
http://sample.net/cgi-bin/ode.cgi/
(Read part 1 for more info.)
There are a couple of things to note:
If the dated theme folder we want to use is titled:
'text_page-2010_0415'
The correct request is
http://sample.net/cgi-bin/ode.cgi/some_post.text_page
The following is not the right way to make a request for a dated theme
http://sample.net/cgi-bin/ode.cgi/some_post.text_page-2010_0415
Ode will deal with the dates. You don't have to. (After all, how would a visitor know the titles of your dated themes?)
I may have a dozen different dated variant's of the 'text_page' theme, all in the same 'themes' directory. If we just want the current version of the theme, Ode will do the right thing. We just need to tell it the name of the theme we want.
Of course I do want some other version, we can use the site_look_date parameter to Ode.
I said that the following is not the correct way to make a request for a specific dated variant of a theme
http://sample.net/cgi-bin/ode.cgi/some_post.text_page-2010_0415
The proper way to do that is
http://sample.net/cgi-bin/ode.cgi/some_post.text_page?site_look_date=2010_0415
The value of the site_look_date parameter is a 4, 6, or 8 character string of digits, conforming to the format YYYY[MM[DD]].
All of the following describe valid site_look_date formats:
YYYY (2008 )
YYYYMM (200801 )
YYYYMMDD (20080128)
Underscores are allowed between components of the site_look_date string to improve readability.
The following are all valid site_look_date strings:
2010_0128
201001_28
2010_01_28
2010___01_28
Only the 4 digit year is required. The month and day portions of the value are optional. Whenever one or both of these optional components are left off, the script automatically uses a value matching the end of the specific period.
For example the following are all equivalent:
site_look_dat=20101231
site_look_date=201012
site_look_dat=2010
The value of the site_look_date parameter specifies a target date.
It is a request for the version of the theme (whatever theme is specified in the request) that was in use (i.e. current) on the specified day.
For example:
http://sample.net/cgi-bin/ode.cgi/technology/apple/macosx/some_file.html?site_look_date=2010_0201
This address is a request for the post at: '/technology/apple/macosx/some_file'.
It also indicates that the response should use an 'html' theme, and more specifically the 'html' theme that would have been the current theme on February 1, 2010.
I want to make a point of saying that visitors are not expected to know when you introduced new dated theme variants. Ode will keep track of that. Visitors provide the date they're interested in (e.g. what did the site look like on Jan 1st, 3 years ago) and Ode will show them the site as it appeared on that date. The script will negotiate all of the dated theme variants to figure out exactly what theme should be used to satisfy the request.
Note: If a visitor requests a date earlier than the earliest dated variant of the request theme, the script will default to the current version.
The behavior breaks down into 2 distinct cases:
The site_look_date mechanism is enabled but **the site_look_date parameter is not included in the request**.
The non-dated themes are ignored and the script must negotiate the the dated themes to determine the appropriate theme to use.
The absence of the site_look_date parameter is interpreted as an implicit request for the current version of the theme (i.e. the theme closest to the request with the latest date which is not later than today's date).
As it did when working with non-dated themes (discussed in the previous post), the script starts by looking for the named theme closest to the request. If it is unable to find a matching theme it moves one level up the content hierarchy (one level closer to the root) and again looks for a suitable theme.
The script is looking for a dated theme with a name matching the request. As soon as it finds a directory containing at least one matching dated theme, it stops. If there are multiple dated themes in the same directory matching the name of the request, it chooses the theme with the latest date which is also earlier than today's date.
This is considered to be the current version of the request theme.
The site_look_date mechanism is enabled and **the parameter is included as part of the request**.
Again, non-dated themes are ignored and the script must negotiate the dated themes to determine which is the appropriate theme to use.
The goal of the script in this case is not finding the current theme, but the theme that would have been used to answer the same request on the specified date.
Ode proceeds like it did in case 1, looking for suitable themes starting closest to the request. When it finds a directory containing a theme matching the name of the request with a date suffix that is earlier than the requested date, it has found a suitable theme, and so it stops looking.
If there are multiple dated variants of the theme matching the request, the script chooses the one with the latest date which is still earlier than the requested site_look_date. This is the theme that would been used in answer to the same request on the specified date.
What are the minimum requirements for using dated themes?
The use_site_look_date setting in the config file must be true.
There must be at least one dated version of the default theme (set in the config file).
Do not include a date suffix as part of the value of the default theme setting in the config file. The date suffix is not considered part of the theme name. In fact the only place dates suffixes should appear is in the title of the directory enclosing a dated theme.
Visitors do not need to reference dated themes in URIs pointing to your site. The script will automatically return the current version of any requested theme, when a date is not explicitly requested with the site_look_date parameter.
Note: If there is only one dated version of the default theme it should be placed in the 'themes' directory at the root of your Ode site's content directory (i.e. the path specified by the document_root setting in the config file). Themes placed in here apply to the entire site. If you placed the only copy of a dated theme someplace other than the site root, it may not apply to every request on the site.
For example, let's say I have dated themes enabled and my default theme is 'html'.
If I only have a single copy of that theme it should appear in the themes directory at the site root, like
.../ode_site/themes/html-2010_0420
If instead I put that theme in some subdirectory of the root, 'technology' for example
.../ode_site/technology/themes/html-2010_0420
the theme would not be available to requests that don't include the 'technology' category, like
http://sample.net/cgi-bin/ode.cgi/
http://sample.net/cgi-bin/ode.cgi/business/
http://sample.net/cgi-bin/ode.cgi/any_category_not_technology/
For those requests, the script would not find the default theme (because it only searches along the path of the request). As a result, it would resort to using the baked-in error theme which includes a message stating the the requested theme could not be found.
To avoid this situation make sure that there is always at least one copy of the default theme in the themes directory at the site root.
Does that all make sense?
If it does, great. If not, that's ok too. Don't give up. Ode is a community, and on behalf of the community let me say that we're happy to help. You can bring your questions to the project discussion forum, or send me an email (rob at ode-is-simple dot com).