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 for it. The database table is simply an INT named id
and a TEXT named body
.
See file DATABASE for a better 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 as a header followed by a blank line followed by body text. Here is an example:
date: Jun-17, 2010 title: Post Format
This post format is too weird!
Now, immediately, several people just yelled 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 how the data is just 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:
- Add a new post "header" of something like
color: red
. - 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 = 1");
Which reads that string back. This string is then turned into a useable 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 for data well and your code will be simple.
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 display comments for that post; and draft:
so that the post will not be displayed. the code was designed for it to be fairly easy 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. We just put that in and the values are strings. We may add more functionality in the future.