I witnessed a peculiar thing as I was testing this theme on my web host's server...

Originally, I used <p id="content_header"> to hold the ASCII fish header image, and set #content_header to preserve whitespace with white-space:pre. However, I noticed that in Internet Explorer 6–8 the ASCII fish was not drawn completely; it's as if the characters comprising the ASCII fish were being shot out of a fire hose, which overwhelmed IE's rendering pipeline and hosed the fish before it got done rendering.

This bug only rears its ugly head when the page is loaded from a remote web server; it renders fine when the page is loaded from your hard drive or local server.

The fix was very simple: I just changed <p id="content_header"> to <pre id="content_header"> and removed the white-space:pre property from #content_header. You can still reproduce the bug by going back in time to the Monochrome beta page.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Mauris vel magna. Mauris risus nunc, tristique varius, gravida in, lacinia vel, elit. Nam ornare, felis non faucibus molestie, nulla augue adipiscing mauris, a nonummy diam ligula ut risus. Praesent varius. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

Read the rest of this post

After solving a strange rendering bug in IE, I'm finally done with my first Ode theme. It's called Monochrome, and it was inspired by the monochrome monitors that introduced me to an exciting new digital world when I was a child. I don't know how many hours of my childhood were lost in those green scanlines, but they paved the way to a decent career.

Read the rest of this post

Start posting to your site.

Remember that posts are plain text files under Ode's document directory ending with the the post file extension. (The default post file extension is 'txt'.) You can use any plain text editor you like to create posts for your Ode site.

Ode treats the first line of the file as the title of the post and everything after the first line as the body.

I recommend leaving a blank line between the title and body but this isn't required.

Edit this theme

The first release includes a single HTML theme and an RSS 2.0 theme to support feeds. (More themes are on the way including an Atom feed for those of you who prefer that syndication format.) Given a standard installation (i.e. assuming you didn't do anything particularly fancy or unusual when setting up Ode), you will find two copies of each of the html and rss2 themes in the 'themes' directory at Ode's document root.

html
html-2010_0301

rss2
rss2-2010-0301

The two copies are identical. The script uses one or the other depending on the value of the 'use_site_look_date' setting in the config file. If use_site_look_date is true then the dated version is used (e.g. html-2010_0301) and the non-dated version is ignored. (The opposite is true when use_site_look_date is disabled).

Themes are pure HTML and CSS. The entire page layout is described by a single file that looks like any other (X)HTML file to your text editor or web design app.

There is no need for you to change how you work with HTML/CSS for Ode.

Here is the complete structure for the default html theme:

html/
    content_type.html
    date.html
    page.html
    page_no_post.html
    logic.css

    images/
        background_wrapper.jpg
        mascot_header.png
        ode_mascot110x50.png
        ode_tag.png
        ode_title.png

Of these files, page.html and logic.css are almost entirely responsible for the look and layout of the site. You'll want to edit these two files to redesign this theme to change the look of your site.

(You can have any number of themes, and you can apply a different default theme for any category.)

Keep up with the documentation

There is much more to Ode than the little blurb above about posting might suggest. Most of the features and functionality of the script are fairly invisible.

I will begin putting up documentation immediately after I'm done with the first release (which means I'm working on getting documentation up now). It is important that you check the documentation, if only to familiarize yourself with Ode's features.

The primary source for documentation about Ode is:

http://ode-is-simple.com/home/documentation

I may supplement this with a forum or wiki (most likely a forum), and I'm still deciding how to handle documentation for addins.

You may want to wait until I get the documentation online before you really start to settle in (so that you have a better idea about what you're settling into).

In addition to the single two column theme included with the initial release I will be posting simple one and three column designs shortly.

Interested in writing your own addins?

You may want to wait until I get a chance to post the associated documentation (alternatively you could dig through the annotated version of the source.)

Thinking about migrating an existing site to Ode?

You will probably want to wait until I release the Indexette addin.

As you may already know, Ode uses the filesystem as a content database. Posts (i.e. the content of the site) are discrete text files that exist under the site's document root. On its own, Ode traverses the filesystem examining the post files to find which are suitable for a given request. It builds a page to return to the client by combining the content of these posts with a theme, which dictates the look and layout of the site.

This arrangement works quite well, however there are a couple of inherent issues. One of which is the fragility of post dates.

On its own, Ode uses the modification dates of the corresponding files as post dates. This is a simple solution and may work well enough if you are meticulous about how you work with your post files so that these modification dates don't change unexpectedly. If that sounds like it might be troublesome, I assure you it can be.

The modification time is updated automatically every time the content of a file is modified. So if you create a post, and then a day later notice a typo and correct it, the modification date will change to the time you corrected the typo, and the post date will change as well. The modification time may also be changed when a file is copied (This behavior varies from platform to platform and may depend on a number of different factors).

Indexette preserves the original modification time of the file (which is essentially the creation date of the post), storing this crucial info within the post itself as a tag. The addin changes the behavior of the script so that the tag value is used as the post date, breaking the dependence on the file modification dates.

Everyone is encouraged to use Indexette, or something like it.

If you're seeing this message in your browser and everything looks ok to you (theme wise) then you're either done installing Ode or you're very close to being finished. Congratulations on getting this far :)

That wasn't so hard, was it? (If it was, let know about whatever problems you ran into by sending an email to rob @ ode-is-simple dot com).

Still having problems?

Post formatting problems

This post should be broken up into a number of paragraphs and headings. If instead you're seeing all of the text run together in one big lump, that means that the Markdown addin isn't working.

The first release of Ode (1.0) includes a single addin titled 'Markdown', which is no more than a small interface between Ode and the text-to-HTML conversion tool called Markdown written by John Gruber.

• Check the path to the addins directory in the configuration file.

• Verify that the Markdown addin is installed.

  There should be a directory titled '00Markdown' inside the addins directory. The Markdown directory should contain a file called 'Markdown_addin'. (There is no need to edit this file.)

• Check your permissions.

  All of the directories leading to the Markdown addin should be readable and executable by the CGI user (the owner of the web server process).

  The Markdown addin itself must be readable by the CGI user.

Theme related issues

Broken path to associated CSS file

If the layout of the page looks broken then chances are the theme is having trouble finding the associated CSS file. That's easy to fix. Open the 'page' theme file in your preferred editor and locate the stylesheet link (which is in the head section of the page). You want to change the value of the 'href' attribute to point to the location of CSS file for your installation.

Broken path to images

If the page looks almost right but you're missing images (Ode's mascot in the header at the top of the page for example), then you need to update the links to images on the page. This is just as easy to fix as the CSS problem. Open the 'page' theme file in your preferred editor and find all of the <img> tags. (Searching for '<img' should allow you to locate them quickly). For each, update the value of the 'src' attribute to point to the location of the associated image file. Assuming you're using the default theme, you should only need to change the path to 'mascot_header.png' in the 'content_header' div.

One of the goals of this project is to blur the line between developer and expert end-user. To that end I'd like to invite everyone with an interest in the project to write your own addins, or otherwise pitch in and help with the development efforts.

This requires two things:

1. An understanding of how Ode works

2. Some knowledge of the Perl language and general programming concepts

3. An understanding of how Ode works

I will do everything I can to help you understand how Ode works. I consider documentation to be a fundamental aspect of this project - every bit as important as the code itself. I will not slough off the documentation effort, both as a matter of principle and because I believe that emphasizing documentation is the single best way to nurture the long term success of the project and grow a healthy and vibrant community.

As evidence of that commitment, consider the annotated version of the source included with the project, which is a line by line running commentary of the script discussing not only what the code is doing but why. As I update Ode, I start with the annotated version, and then generate the leaner unannotated version from it. So, I can say confidently that every subsequent release will include its own annotated source file.

It's important to understand that though the annotated source code does contain the source, the emphasis here is on the annotations and not the code. As should be plainly obvious, the annotations are a great deal longer than the source code itself. I hope it is just as obvious that this work represents a very significant amount of time and effort. Please don't make the mistake of disregarding this as nothing but code. It's an attempt at a narrative approach to the task of developing the software. As such, it is an integral aspect of this project.

The annotated source is just the beginning. There will also be diagrams describing the execution flow of the script, addin interface specifications, sample themes and wireframes, and more. I also plan on having the usual sorts of support resources (including possibly a forum, mailing list(s), a wiki, etc).

At a moment a lot of these resources are not available. It's coming, and in fact a lot of these materials are already complete (or close to being completed). Regardless, whenever you have questions about Ode and cannot find answers on your own feel free to send me an email (rob at ode-is-simple.com).

1. Some knowledge of the Perl language and general programming concepts

For anyone new to porgramming, Ode is, in my opinion, a perfect place to start. In fact, Ode was written as an academic project designed to serve as a suitable first introduction to programming and intended to address what I believe to be key failings with the way we introduce new students to programming and the field of computer science.

This was the basis of my masters thesis. Consider this excerpt from the introduction:

There are two important objectives that we must achieve in order to be successful in attracting new students.

First, as I've already discussed, there's a disconnect between the work students imagine they may want to do with a CS education and what they're able to accomplish early in their academic career(s). We need to bridge this gap by providing projects that can help them recognize the relevance of what they're learning to work that is intrinsically motivational. The job of bringing new students to the field is as much a matter of encouragement and inspiration as it is education.

The limited, uninspired work that often characterizes introductory programming courses sends the wrong message to new students, suggesting that they're unprepared to face more difficult work that lies ahead of them and leaving them feeling insecure about their abilities as new programmers. An ideal solution would introduce students to foundational topics and do so in a way that builds confidence and piques their interest by affording them the opportunity to do work they find rewarding. I claim that the web is a perfect bridge between the world of CS and mainstream computer technologies.

First, we don't have to wonder if the web is engaging. It is experiencing phenomenal growth and attracting a lot of interest generally, and among those people who we might hope to attract to the field.

Secondly, not only is the web popular but it is legitimately relevant to Computer Science and represents a tremendously valuable resource for the community. Today, the web is becoming a distributed platform for building applications, with the elegance of a modern framework and the capabilities of a service-oriented architecture; one that is already here, widely used, and global in scale. Furthermore, many familiar CS problems are making their way to the web, which suggests that it may be a useful platform for vetting our ideas related to these problems. For example, the emergence of open standards has led to the accessibility of large data sets, and the opportunity to confront the real world problems associated with accessing that data over a highly distributed application.

Interested in getting an early start?

First realize that there are two different versions of each release of Ode, 'ode.cgi' and 'odeannotated.cgi'. Both executable (i.e. working scripts) and functionally identical. The difference between the two is hinted at in the file names. ode.cgi is a pretty typical perl script with minimal commenting, while 'odeannotated.cgi' contains extensive annotations.

To give you some idea of what I mean by extensive, while ode.cgi is approx 193 KB and 6,000 lines, ode_annotated.cgi is approx 1.3 MB and 36,000 lines. Those approximately 30,000 extra lines are a running description of what the code is doing and why.

There is also a third file, 'odeannotated.html', which is an html formatted version of 'odeannotated.cgi' with anchor tags corresponding to lines in the unannotated version of the script. This makes it essentially an HTML formatted index allowing you to jump between the two versions.

Let's say you find yourself digging through the script, and you have a question about a particular line, line 879 for example. You can drag and drop the HTML file to a web browser and append a pound sign and the line number to the end of the URL ('#879' in this case). The browser will jump right to the corresponding line in the annotated script, where you'll find information that might help answer your question.

The annotated source means that you're never on your own trying to decipher the code.

Now that I've said all that, do not jump right into the annotated source. That's not where you want to begin.

Pick up the book 'Learning Perl "Learning Perl page at o'reilly.com"' published by O'Reilly.

Consider this the unofficial guide to Perl for Ode. Just about everything you need to know to understand Ode at the source code level is contained in this relatively short 352 page book (there are probably closer to approximately 250+ pages of actual content). Reading just 10 pages a day, you'll be finished in about a month. I think that's pretty exciting.

When I say that 'Learning Perl' is the unofficial guide to Perl for Ode I mean that quite literally. I developed the project with that specific book in mind, being careful to limit what I did with the script to topics covered by the book. (To be completely honest, there are a couple of topics are covered in the 'Intermediate Perl' book but you can worry about that later - I'd guess that you won't even notice.)

Why? I wanted to have a single reference that could serve as a common resource, i.e. a shared knowledge base, for all members of the community. I chose an introductory book because I wanted the project to be accessible to the widest possible audience (also, we can do everything we need to do with the information in Learning Perl).

Is 'Learning Perl' the only introductory Perl book available? No, it's not. There are quite a few others available. (I've read at least a couple of of them.) Regardless, Learning Perl is the one and only guide to Perl for Ode.

The advantage of using one book is that it simplifies what would otherwise make for difficult and time consuming instruction and discussion.

What does this mean to you?

Discussion related to Learning Perl is considered on-topic for this project. Feel free to ask questions about the book, and even reference page numbers (the most recent edition, currently the 5th, is preferred). In fact, I encourage you to discuss information in the book even if it's not directly related to Ode.

Also, expect that answers to your questions might make reference to the book.

Why did I choose 'Learning Perl'?

It is widely available and mature. Also, I am very familiar with it and find it to be both accessible and reliable (factually accurate).

I highly recommend you pick up a copy if you don't already own it. Currently, the list price of the print edition is $39.99 with a ebook version available for $31.99. You do not need to pay this much. You can typically find any computer book at 30% - 40% off of the list price. So you should expect to pay something closer to $25.00 for the book new. (One option is to join O'Reilly's free membership program which offers savings of up to 40% off the price of books purchased directly from the publisher through oreilly.com.) If you'd rather not buy the book, you should be able to find a copy at your local library (or put in a request it). For what it's worth, I recommend you buy your own copy if you can.