Documentation Index

Internal Post Format

Posts

A THIS post (also called an entry or a record) is stored in the database as text, which is weird, we know, but there is a reason. The database table is simply an INT named id and a TEXT named body.

See file DATABASE for an explanation of the database design (which includes a discussion of some of it's shortcomings).

The text format is just like the RFC for Mail Transport Something or Other, one or more colon delimited word identifiers and text in a "header", followed by a blank line, followed by the text body. Here is an example:

    date: Jun-17, 2010
    title: Post Format
    This post format is too weird!

Immediately, several people just emailed at us to put title, date in the database like normal people! Well, we do things differently than everybody else for a reason. The Admin code to create a post is a TEXTAREA like this:

    +-----------------------------+
    | date: Jun-17, 2010          |
    | title: Title                |
    |                             |
    | Place content here.         |
    +-----------------------------+

The code puts in that default text (the date is automatically generated to the current date). And that is exactly how the data is stored in the database.

This is to be able to customize the database without customizing the database.

If you want to add a field to the header, say, um, color — you want to add a color to all your posts. To do so requires about three steps:

  1. Add a new line in the header of something like color: red.
  2. Modify your web template that displays a post to use the color.

Wait, that's only two. That's right. Two steps. That's all.

"Wait a minute," someone shouts from down the hall. "It can't be that simple!" Well, let's see.

First, a post is written to the database as the text from the TEXTAREA:

    $data "date: Jun-17, 2010\ntitle: Title\n\nPlace content here\n";

Here is our write to the database function:

    mysql_query("INSERT INTO data (body) VALUES ('$data')");

This is our read from the database function:

    mysql_query("SELECT body FROM data WHERE id = $id");

Which reads that string back. This string is then turned into an array:

    $record['date'] = 'Jun-17, 2010';
   
$record['title'] = 'Title';
   
$record['body'] = 'Place content here';

(The code handles things like colons in a header, empty fields, etc.)

The HTML web template used to display the record is something like this:

    <div>
    <span>{$record['title']}</span>
    <span>{$record['date']}</span>
    <div>{$record['body']}</div>
    </div>

(Which actually has class identifiers and really nice CSS.)

To add color, simply modify the template, say, something like this:

    <div>
    <span>{$record['title']}</span>
    <span>{$record['date']}</span>
    <div style="color:{$record['color']};">{$record['body']}</div>
    </div>

That is all.

One of our mottos is: design your data well and your code will follow.

Of course, you probably see the flaw. There actually are three steps. Which leads to the next section.

Functionality

In the case of the colorizing we need to support older posts that would not have the color field. Currently, the HTML template display code will display non-existent record data as empty strings, so records without a color: header will be like so:

    <div>
    <span>Title</span>
    <span>Jun-17, 2010</span>
    <div style="color:">Place content here.</div>
    </div>

A harmless "flaw" actually. But what to do is to add a section at the end of CONFIG.INI file like this:

    [headers]
    color = red

The code to read a record uses that data to make up defaults for any missing data.

There are other places in the code that tests for certain post headers. There is nocomments: to not display comments for that post; and draft: so that the post will not be displayed. The code was designed to be changed to handle new post headers.

Notes
  1. The actual implementation is:
      CREATE TABLE data (id INT AUTO_INCREMENT UNIQUE, body MEDIUMTEXT).
  2. Eric S. Raymond: "Under Unix, this is the traditional and preferred textual metaformat for attributed messages or anything that can be closely analogized to electronic mail. More generally, it's appropriate for records with a varying set of fields in which the hierarchy of data is flat (no recursion or tree structure)."
  3. You do need to make sure that the headers are properly formatted and the the body is separated by two newlines (as the record will not be parsed properly without them). We will eventually put in some code to check for that.
  4. With the data properly escaped.
  5. We just put that in and the values are strings. We may add more functionality in the future.