LnBlog

Homepage: http://www.skepticats.com/lnblog/

LnBlog: A simple file-based weblog focused on design elegance.
Copyright (C) 2005 Peter A. Geer <pageer@skepticats.com>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

LnBlog is a simple weblog package written in PHP which stores data in text files. It is strives to be easy to use, easy to manage, and feature rich while maintaining a clean, elegant, and modular design. It is built to create sites with a clean, directory-based URL structure and valid XHTML and CSS for style and layout. Plus, it's light on requirements and cross-platform.

Status

Currently, LnBlog is in the active development, which just means that it is functional and tested, but not anywhere close to done yet. There are still lots of features to add, both in the back-end code and in terms of interface elements. You can see the to do list to get an idea of what is currently planned. If you have any comments or suggestions, or if you have any problems or find any bugs, feel free to e-mail me.

Requirements

LnBlog is fairly light on requirements. It does not require any particular operating system or web server and is known to work on Linux/Apache and WinXP/IIS. The only hard and fast requirements are the following:

PHP 4.0 or greater.
Support for Perl Compatible Regular Expression (PCRE), which is enabled by default in most PHP packages.
The ability for scripts to read and write files to the server. To do this, you must either have FTP access to the web server and configure LnBLog to use it, or have PHP's safe mode disabled and appropriate directory permissions set on the web server.

Feature List

Works in Safe Mode when using FTP support.
Anonymous reader comments.
Automatically generated RSS feeds for blog entries and comments.
Send and receive TrackBack pings.
Create multiple user accounts with basic serucity on entires and blogs.
E-mail notification when new comments are posted.
Easily create multiple weblogs.
Create static "articles" in addition to weblog entries.
Change between multiple themes, each of which can have completely a different look and behavior, i.e. different styles, HTML markup, images, and even client-side scripts.
Default themes use valid XHTML Strict for markup and CSS-based page layout.
Flexible theming system that allows HTML templates, scripts, and stylesheets to be tweaked on a per-blog basis.
Support for posting with simple auto-markup, a simple subset of BBcode, or raw HTML code.

Initial Setup

For step-by-step instructions, please see the install guide. If you're more technically inclined, then it's probably safe to just skip to the summary below.

Here's the quick version. Just extract the installation archive and upload the whole LnBlog directory to a location in the publicly accessible portion of your web hosting account. You can them navigate to that directory with your favorite browser to run the configuration scripts. The first script configures file writing. If you have FTP access to the web server, you can use FTP for file writing (this is recommended) by selecting the FTP option and giving the appropriate information below. Otherwise, LnBlog will use PHP's standard filesystem functions, which will require that Safe Mode be turned off and appropriate permissions set on the relevant directories.

After file writing support is configured, you must set an administrator login. This will be used to add new weblogs as well as to log into the ones you create. After that's set, you can log in and start adding new blogs and/or users. There are also administrative functions to modify a blog and update a blog (used when upgrading LnBlog).

Upgrading

Upgrading your LnBlog installation is actually quite easy. If you are paranoid, you will want to make backup copies of the configuration files in your LnBlog directory. These files are named fsconfig.php, passwd.php, and sitemap.htm, and are used to store information global to your installation. They are generally not affected by upgrades, and they are not hard to recreate if destroyed, but I thought I should warn you anyway.

Exception 1: The format of passwd.php has changed between versions 0.2 and 0.3 and you should delete the old one and let the software create a new one. Version 0.3 adds support for multiple users using a mechanism that is incompatible with the previous passwd.php format. After you delete this file, go to your LnBlog administration page and you will be prompted to create a new administrator account.

Exception 2: An additional configuration constant, DOCUMENT_ROOT, has been added to fsconfig.php in verion 0.3.2. You may upgrade by deleting your fsconfig.php and going to the administrative page to recreate it. However, if your site was functioning correctly with the old version, it should continue to do so with the old fsconfig.php file.

To upgrade LnBlog, simply extract the new version from the ZIP archive and upload it to your web host into the same location as the old version, overwriting the old files. Alternatively, you can move or delete the old installation folder and put the new one in its place, provided you copy the above mentioned configuration files into the new installation directory.

Once that's done, you may need to upgrade the files for each individual blog. This is done by going to the administration page and using the "upgrade blog" option. Simply put the relative path to your blog (e.g. myblog, as described in the "Adding New Blogs" section) and click the "Upgrade" button. This will upgrade the configuration files for the blog and add any new pages. You will have to do this separately for each blog that youhave.

Adding New Users

In addition to the administrator account, you can create as many new user accounts as you like. (Disclaimer: LnBlog was not buit to handle large numbers of users. While there is no inherent limit on the number of users, I doubt that the current implementation will scale well. You have been warned.) To create a new account log in to the LnBlog administration page and click the "Add new user" link. Only the administrator account can create new users.

The form to add new users should be fairly self-explanatory. You are required to enter a username, password, and password confirmation. The real name, e-mail, and homepage are all optional. However, please note that the user will (obviously) not receive e-mail confirmation of comments on his posts if you do not give an e-mail address.

Security

LnBlog uses a very simple security based on user ownership. The rules for determining what each user can do are as follows

The administrator can do everything that can be done.
The owner of a blog can modify the blog properties (theme, name, number of posts shown, etc.), can add entries and articles to it,and can modify the entries and articles of other users who post to the blog.
The owner of an entry or article can modify that entry or article, including comments and trackbacks.
A user can only add articles or entries to a blog he owns or one he is explicitly on the write-list for.
Anybody, user or anonymous reader, can add comments.

To put it more succinctly, there's the administrator (can do anything), the blog owner (can do anything with the blog), the other users (can do anything with their own posts - provided they can post), and everybody else (can only post comments). Which role a particular person will take depends on who they are and what blog you're talking about. The owner of one blog may be just a regular reader on another.

Adding New Blogs

Adding new blogs is done on the LnBlog administration page. Only the administrator account can add new blogs.

To add a new blog, just click the "Add new blog" link and fill out the form on the resulting page. The fields define various properties of the blog, and are as follows:

Blog path: The path to the blog on the web server machine. You may specify either an absolute path or a relative path, in which case the path is computed relative to your web root directory. So, if you specify the path "myblog", then the web address of the blog will be http://www.mysite.com/myblog/
Blog owner: The username of whoever owns the blog. This is the user who will be allowed to change these settings later. By default, this is the administrator.
Additional allowed writers: A comma-separated list of usernames other than the owner who can post new entries and articles to this blog.
Blog name: The name of the blog.
Description: A short description of the blog.
Theme: The theme visual used for the blog.
Blog name: The name of the blog.
Maximum number of entries: The maximum number of entries to display on the homepage of the blog. For example, if this is 10, then the main page of the blog will display the last 10 entries.
Maximum number of entries in RSS feeds: The maximum number of entries that will be put in the main blog RSS feed.

Adding Entries

Adding a blog entry is pretty self-explanatory. Just log in and click on the "add entry" link. You will be taken to the entry edit screen, where you can enter the subject for your entry, the entry text itself, and turn comments for this entry on or off. Note that in order to add an entry, you must either be the owner of the blog you're adding it to, or you must be on the allowed writers list for that blog.

There are three possible input modes, which you can change between with the option buttons below the edit area. They are:

Auto-markup: Adds HTML paragraphs and line breaks based on the plain-text input and converts all http:// and ftp:// URLs to links.
LBCode: Use a dialect of the BBCode markup popular in web forums to markup your page. Paragraphs and line breaks are inserted like with auto-markup, but you can also include other supported tags. See the LBCode Syntax section for details.
Raw HTML: The text you type is treated as raw HTML code. No processing is done and there's no guarantee that your page will validate. In other words, this is for people who know what they're doing.

User Comments

LnBlog allows anonymous user comments by default. You can turn off the ability to add comments with a checkbox on the entry edit screen. Comments have a required body text and optional subject, name, e-mail, and homepage fields. For logged-in users, comments will also store the username, so that the up-to-date name, e-mail, and homepage can be displayed automatically. Currently, comments cannot be edited, but they can be deleted by users with permission to modify the entry.

If the owner of a post has an e-mail address specified for his username, then he will receive e-mail notification of any new comments on his posts. The e-mail is send using PHP's mail() function, so that must be correctly configured for your server. The messages themselves are in plain-text format and include the URL of the comment, as well as the comment itself and any personal information entered by the reader.

TrackBacks

LnBlog has some very primitive support for Trackbacks. Each entry has a trackback URL and will store and display any trackback pings it receives.

To send a trackback ping, you must be logged in and have permission to modify the blog. You can then click on the "Send trackback ping" link for your blog entry and start the two-step ping process. The first step is to enter the URL you wish to ping. The second is to confirm the ping data and send it.

Due mostly to laziness on my part, LnBlog does not yet support "real" trackback pings. Instead, it uses a simple HTML form with element names conforming to the TrackBack specification to submit the HTTP POST request. As a result of this, you will notice that after the ping, you are directed to the page you pinged, which will probably show you the XML response dictated by the specification. If this is a 0 (zero), that means the ping succeeded. Otherwise, you should hopefully see an error message. Because of the suckiness of this situation, sending a trackback ping will open a new browser window so that you don't have to manually go back to your blog.

LnBlog currently does not support TrackBack URL autodiscovery. There is no bookmarklet to pick up trackback URLs for other blogs and there is no RDF section embedded in LnBlog entries.

LBCode Syntax

LnBlog supports marking up your text with LBCode, which is a variant of BBCode, the markup language used in many popular web-board and forum packages, such as phpBB. I call this dialect LBCode because it makes absolutely no attempt to match the official syntax (if there is such a thing) of BBCode. The primary purpose of LBCode is to let the user write rich text that is valid XHTML 1.0 Strict without having to learn any XHTML or worry about making mistakes while writing. Below is a table of the currently supported tags, with descriptions, example, and the mapping to HTML. Please note that LnBlog does not currently handle LBCode errors gracefully - incorrect syntax will simply be displayed as plain text.

Description	Code	Example	HTML equivalent
Bold text	[b]bold[/b]	bold	<strong>bold</strong>
Italic text	[i]italic[/i]	italic	<em>italic</em>
Underlined text	[u]underline[/u]	underline	<span style="text-decoration: underline">underline</span>
Abbreviation	[ab=Full phrase]abbreviation[/ab]	abbreviation	<abbr title="Full phrase">abbreviation</abbr>
Acronym	[ac=Full phrase]acronym[/ac]	acronym	<acronym title="Full phrase">acronym</acronym>
Block quotation	[quote]Quotation[/quote]	Quotation	<blockquote>Quotation</blockquote>
Source code	[code]Source code[/code]	`Source code`	<code>Source coden</code>
Short quotation	[q]Quote[/q]	Quote	<q>Quote</q>
Hyperlink	[url=http://www.google.com]Google[/url]	Google	<a href="http://www.google.com">Google</a>
Image	[img=http://www.google.com/images/logo.gif]Google logo[/img]		<img src="http://www.google.com/images/logo.gif" alt="Google logo" title="Google logo" />
Number list	[numlist] []First item []Second item [/numlist]	First item Second item	<ol> <li>First item</li> <li>Second item</li> </ol>
Unordered list	[list] []First item []Second item [/list]	First item Second item	<ul> <li>First item</li> <li>Second item</li> </ul>

Notes on LBCode

The line breaks between items in numbered lists and unordered lists are not optional. You must put each item on a single line and you must put the beginning and ending tags on their own line.
When you give just a file name (i.e. a path containing no '/' characters) as the target for an [img] or [url] tag, LnBlog will automatically convert it to an absolute URI to a file in the entry directory when it is displayed. This feature is provided for two reasons: because you will not know the absoute URI of a blog entry until after you post it and because the post can be displayed at its permanent location, in which case the relative link is valid, or in another place (the front page of the blog or an RSS feed), where the relative link is not valid.
In Mozilla-based browser, [ac] and [ab] both do the same thing. They are both provided because there is a semantic difference, i.e. that an abbreviation is simply a shortening of a phrase using the initial letters, whereas an acronym is such a shortening that actually spells a pronounceable word. However, while the <abbr> tag is often the semantically correct one, Internet Explorer 6 doesn't support it, so you should use this tag with care.
In the [img] tag, the text between the opening and closing tags is required. This is because it is used as the text for both the ALT attribute, which is required in XHTML, and the TITLE attribute, which gives you the tooltips in Mozilla-based browsers. Since Internet Explorer incorrectly uses the ALT text for tooltips, you'll actually get the same tooltip in all browsers.
In Mozilla-based browsers, the <q> tag renders quotation marks automatically. However, this depends on the CSS2 :before and :after pseudo-elements, which are not supported by Internet Explorer, so use this with care. Note that in the default LnBlog stylsheets, the <q> tag is rendered with italic text, so that even in Internet Explorer, it can be distinguished from normal text.
The current LBCode handler does not deal gracefully with multiline tags. So if, e.g., you have a multiline block quotation or code block, the LBCode handler will still put <br /> tags in for the line breaks.

LBCode Editor

When posting using LBCode markup, you can use LnBlog's simple Javascript-based LBCode editor to insert the codes for you. The editor is simply a series of buttons and two text boxes, labeled "text" and "attribute." The "text" box is used to enter the contents of an LBCode tag, i.e. the actual text the goes between the opening and closing tags. The "attribute" box is used to enter any attribute for the opening tag. such as the URL for an image or link, or the phrase that an appbreviation or acronym stands for.

To use the editor, just type in the text and attribute you want and click the appropriate button. If you want to add a word in bold, type your word into the box labeled "text" and click the bold button. If you want to add a link, put the link text in the "text" box and the URL for the link in the "attribute" box and click the URL button. The corresponding markup will be added to your post at the current cursor position or at the end, depending on your browser's Javascript support. Inserting at the cursor position works on Opera 8.0, Firefox 1.0.3, and sorta-kinda works in Internet Explorer 6.0. I haven't tried it on other browsers, so your mileage may vary.

An extra feature of the editor is that the abbreviation and acronym buttons will save any attributes you use during your post and add them automatically. So, for example, if you enter the abbreviation with the text "GNU" and the attribute "GNU's Not UNIX," then if you mention GNU later in your post, you can just enter "GNU" for the text and leave the attribute blank. When you hit the abbreviation button, the attribute "GNU's Not UNIX" will be added automatically.

CMS Features

While LnBlog is a technically a weblog package, it also includes several "mini-CMS" features. These exist mostly for the sake of maintaining the design consistency of the site and making it slightly easier to manage. The following sections describe these.

Adding Articles

An article in LnBlog is just a blog entry with a different URL and different display template. It's basically a cheap and easy way to add static content that meshes with the overall look and feel of the blog, but doesn't require any extra work. You still get BBCode support and revision history, but the URL structure is pneumonic and comments are turned off by default. You can enter the last component of the article URL when you first post it or go with the default, which is to use the subject with all letters converted to lower case, spaces converted to underscores, and all other characters removed. In addition, articles have a "sticky" attribute that you can set. This will cause a link to the article to be displayed in the sidebar (provided you're using one of the default themes).

Uploading Files

LnBlog provides pages to upload files to the root of the current blog or to the current entry or article. Currently, you can only upload one file at a time. You should also note the file size limit when trying to upload a file. To change this, must change the values of the PHP configuration variables upload_max_size and post_max_size by creating a .htaccess file (if you use Apache) or by modifying the system php.ini file.

Sitemap Editing

Part of LnBlog's basic page layout includes a sitemap, also refered to as the menubar. In the default theme, this is the bar just under the banner with your blog name. It is intended for global site navigation, e.g. to go from one blog to another or to other sections of your website. Needless to say, you will want to customize it for your own site.

There are two ways to edit the menubar: globally for al LnBlog blogs, or locally to just the current blog. To edit the global sitemap, use the link on the LnBlog administration page where you will see a link to the sitemap editor. To change the sitemap for a particular blog, log in and use the link in the administration section of the blog sidebar. Note that setting a sitemap for the blog will override the global sitemap.

The sitemap editor is a simple Javascript form that creates a list of links. Just enter the text you want for the link, the tooltip (what to display when hovering the mouse over the link), and the target URL for the link, either relative or absolute. When you click the "Add Link" button, a line will be added to the output box with the HTML code for the information you specified. When a page is displayed, LnBlog will read this file and put each line into a list item to be displayed in the menubar. Please note that, currently, if you want to create a more complicated menu layout, you will have to modify the menubar template.

License Information

LnBlog: A simple file-based weblog focused on design elegance.
Copyright (C) 2005 Peter A. Geer <pageer@skepticats.com>

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.