LnBlog

In this installment of the LnBlog walk-through, we'll be taking a look at the administration page and creating a new weblog. This will get you to the point of having a working, if empty, weblog.

Administration Page

When you access the main LnBlog URL again after your initial setup, you will be asked to log in and then taken to the administration page. This is where you will create new users, new blogs, and perform upgrade and administration functions.

Let's briefly go through the links you'll find on this page. In the "Add Features" section, the "configure site-wide plugins" link allows you to control the default plugin settings for your blogs. Plugins can be set up on a per-blog basis, so if you don't specifically change the plugin settings for a certain blog, the ones set here will be in effect. I'll cover plugin configuration in detail in a future installment.

The next link, "configure enabled plugins and load order" allows you to disable installed plugins and to change the order in which they are loaded. The defaults will probably be fine for a new installation, but if you want to, for example, put the blog sidebar panels in a different order, the easiest way to do it is by chaning the plugin load order. As with the plugin settings, loaded plugins are configurable on a per-blog basis.

The "edit system.ini file" and "edit group.ini file" links will simply let you edit the indicated files in a text area. Currently (as of version 0.8.0), the only reason to edit group.ini is to make other users administrators. The system.ini file, on the other hand, does have a few setting that you might be interested in. I'll save that for another day, though. Right now, we're still on the basics.

The "modify site-wide menubar" link is used to add custom links to the site map bar under the page banner. Note that this is also configurable on a per-blog basis, so use this link to create the default site map. Note that the site map is controled by the SiteMap plugin, which has several configuration options. If you do not change the settings, then the default behavior is to dynamically add a link in the sitemap to each blog you create, so you really only need this to add links to sections not managed by LnBlog.

The "add new user" link should be pretty self-explanatory. It just lets you create new users, just like you did in the last installment. The only difference is that any new users you create will not be administrators.

Creating Blogs

That brings us to the "add new blog" link. If you click that, you will be taken to the new blog screen. Here you will enter the options for your first blog.

The first piece of information you need is the blog path. This is the root-relative URL of the blog and the path to the folder it will be created in. For example, if you give "myblog" as the blog path, then LnBlog will store this blog in a folder called "myblog" under the document root on your web server. The resulting URL of your blog would be http://yourhost.com/myblog/. Note that you can specify paths in this box as well, provided the beginning components of the path already exist. For example, you could give blogs/tech/linux as the path, so long as you already have a /blogs/tech/ on your server.

The blog owner is the username of whoever "owns" this blog. The blog owner is considered the administrator of this blog and can change any of the blog's settings. Note that site administrators, like your first user account, can also change any settings on any blog.

The "additional allowed writers" box lets you list specify a list of other usernames who can post new entries to this blog. You should separate the usernames by commas with no spaces. Note that these users will not be able to change any blog settings (unless they are also administrators).

The blog name and description boxes are pretty obvious - they're the name and description for your blog. These will be displayed in the page banner, the RSS feeds, and various other places. Note that the PageHeader plugin defaults to only show the blog name. There is an option to show the description as well.

The theme drop-down box allows you to select a theme for your blog. A theme is a set of templates, style sheets, images, and scripts that determine what your pages look like. Note that it is possible to customize your pages on a per-blog basis or to simply create your own theme, which can be either entirely original, or simply modifications to a few selected files. The themes use XHTML and CSS with a some inline PHP code to insert variables into templates and control display. Theming is a somewhat complicated topic, which I will, yet again, save for another day.

The "maximum number of entries" box determines how many blog entries to show on the front page of the blog. Likewise, the "maximum number of entries in RSS feeds" determines how many entries to show at once in the RSS feeds.

The "send Pingbacks when posting entries" box is used to enable or disable sending Pingback pings to pages your entries link to. By default, Pingback pings will be sent whether your entries accept Pingbacks pings or not. You can disable sending pings when you post your entry, but this sets the default.

The "allow enclosure for entries" box simply turns on and off the text box for entering an enclosure URL for blog entries. Enclosures are the feature of RSS by which podcasting is made possible. If you don't do any podcasting, then you can uncheck this box to remove the extraneous box from the post editor. If the extra text box doesn't bother you, can can safely ignore this option.

Lastly, the "default markup for entries and articles" box allows you to pick the default mode for writing your entries. You can override this on a per entry basis. The available choices are auto-markup (which is plain text with URLs made clickable), LBCode (which is a variant of BBCode), and raw HTML (no auto-generated code - not even line breaks). The default for new blogs is LBCode, as it is the easiest use, especially if you're familiar with web forums. You can read the LBCode documentation for the full list of supported tags.

When you have filled in all these boxes, click the submit button to create your blog. Note that the path and owner are the only fields that cannot be changed after you create the blog. (Well, technically they can be changed, there's just no graphical interface for it - you have to do it the old-fashioned way, with a text editor and an FTP client.)

You should now be looking at a nice blog page with no entries on it. Next time, we'll briefly go over the how LnBlog handles user security and then we'll move on to filling in that empty blog.

Welcome to te LnBlog walk-through! In this series of entries, I will be walking you through the process of setting up a weblog using LnBlog, from initial installation to advanced customization.

It is my hope that these articles will serve as a guide to help new users get up and running quickly and to help encourage people to try out LnBlog. If you have any questions or feedback, please feel free to post comments or e-mail me privately. I will do my best to answer all questions.

So, without further ado, let's get to it! Today's installment will cover installation and initial configuration. This will take you from zero to the main administration page.

Requirements

LnBlog doesn't have much in the way of requirements. In fact, that's half the point - it's meant to work well on both low-cost shared hosting accounts and full-featured hosting. The only hard and fast requirements are PHP 4.1, the standard Perl-Compatible Regular Expression extention (which nearly every installation should have), and the ability to write files, either through PHP's normal functions or via FTP. Support for the less-common gettext, CURL, and fileinfo or mime-magic extensions is recommended, but not required for proper operation. Things will work better if you have them, but don't worry about it if you don't.

Installation

After downloading a copy of LnBlog, the first order of business is to get it on your web server. To do this, simply extract the LnBlog-version.zip file to your hard drive and upload the resulting folder to your web host. You will probably want to rename the directory to remove the version number, so that upgrading to a newer version will be easier. Note that you need to upload the folder to someplace under your document root directory, i.e. somplace where you can get to it with a web browser.

Initial Configuration

To configure LnBlog, fire up your favorite web browser and point it to the URL corresponding to where you put the LnBlog folder, e.g. http://yourhost.com/LnBlog/. This will launch the file writing configuration screen, seen here. The first section asks you to set the path to the document root directory on your web server. LnBlog will calculate a default value for this. The default should be right for your setup, but you can change it here if it's not. If you're not sure, try the "test document root" link to run a simple test.

The second section on this page asks you to configure file writing. Here, you have two choices. You can either use PHP's native file writing functions, or you can write files through FTP. For shared hosting accounts, especially cheap ones, the recommended setup is to use FTP file writing, because you won't have to worry about safe mode or directory permissions.

If you choose native file writing, no further configuration is required within LnBlog. However, there are a few things to keep in mind. First, native file writing won't work with PHP's safe_mode enabled, so you'll have to get your hosting provider to turn it off for your account. Also, you will have to check the file permissions on the web server and make your LnBlog/userdata folder writable to everyone. Keep in mind that when you create new blogs, you will also have to the directory where you create them writiable to all users. Because file permissions have to be handled manually, native file writing can be harder to manage, especially when using shared hosting accounts.

FTP file writing should not require many manual setup and it works just fine when safe_mode is enabled. However, it does require that you have FTP access to your web space. It also requires some extra configuration. You will need to provide a username and password for a user account which can upload files to your site via FTP. LnBlog will assume that the FTP server is running on the same machine as the web server (hence the name localhost) and will attempt to calculate the root directory for FTP access automatically. This should work for most configurations, but you can also specify these manually if you need to. You can click the "test FTP root" link to get a simple test page that will attempt to connect to the FTP server and calculate the FTP root directory.

Once you have picked your file writing method, click the submit button. If all goes well, you will be taken to the user creation page. This page allows you to create a new user who will serve as the system administrator. That means that this user will be able to create other user accounts, create new blogs, and make changes to any existing blog or post. In other words, an administrator is allowed to do anything that can be done in LnBlog.

As for the fields themselves, you can enter any username you like. The "real" name is the name that will be displayed as the author's name on posts you create, so it is recommended that you specify some name here. An e-mail address is required if you want to get e-mail notifications of replies (i.e. TrackBacks, Pingbacks, and reader comments). The homepage is purely for informational purposes. Lastly, the contact URL allows you to enter an HTML like that allows people to contact you. If you enter a link here, then that will be displayed in your profile instead of your e-mail address.

Once you have successfully created your account, you will be redirected to the login page. Note that this first user account will be automatically marked as the administrator, so you will be able to use this account to log in and administer LnBlog. This includes editing configuration files, creating new users, creating new blogs, and so forth. We'll take a look at the administration page and creating anew blog in the next installment.

In an earlier post, I talked about low-level customization with userconfig.cfg. Well, there's actually an even lower level. That would be userconfig.php.

The principle is simple: userconfig.php is a PHP file that, if it exists, is loaded and executed before anything else. So, in other words, this is the place to put any code you need to modify your PHP configuration or things of that manner.

One handy use of this is setting the time zone. You might want to do that if you're like me and use a web host that's in a different time zone than you are. Sadly, PHP 4 doesn't provide an easy way to format dates to a different time zone. However, if you're using a typical Linux/Apache server, you can simply set an environment variable to take care of this.

To do this, you can just create a userconfig.php file in your userdata and add the following text to it (substituting your own timesone, or course):
<?php
putenv("TZ=US/Eastern");
?>
If you need to add any other special PHP code, such as ini_set() calls, it would go between the PHP tags. Just keep in mind that you can't have any characters or blank space (including blank lines) outside the PHP tags.

Of course, since this file is raw PHP code, it's not a good idea to mess with it too much unless you really know what you're doing. In fact, it's probably a bad idea to use it if you don't have a working knowledge of PHP. It's really only there to make things easier for those rare occasions where you really, genuinely do need to add some code when a page loads.

This short tutorial covers the userconfig.cfg file and how to use it. It also describes the settings needed to enable persistent user login, i.e. carrying logins over from one browser session to another.

LnBlog has a lot of configuration settings. However, not all of them have a nice settings dialog that allows you to change them graphically.

The blogconfig.php file in the root of your LnBlog installation is full of settings like this this. That file has PHP definitions for various configuration constants. They're "constant" in that you can't change them programatically, i.e. inside a plugin or other script, but you can change them using a configuration file. That file is called userconfig.cfg and it is located in your LnBlog/userdata folder.

If you look at the blogconfig.php documentation, you'll see that many of the constants defined there are listed as having a default value. The values of those constants can be changed by adding a line to your userconfig.cfg file. Of course, you could just just edit blogconfig.php, but that file changes with every version of LnBlog, so you'd have to re-do all your chages with every upgrade. Since userconfig.cfg lives in your userdata folder, you can easily carry it over from one version of the software to another.

The format of userconfig.cfg is simple: name=value pairs, one per line. You can add comments by starting a line with a hash (#) character. When LnBlog loads a page, it will read the userconfig.cfg and for each line it will define a constant with the name given before the equal sign and assign it the value after the equal sign. Because this is loaded before other constants are defined, the values set here will take precedence over the defaults.

As an example, let's set some of the values that control user login security. LnBlog's default user authentication settings are, well, a little paranoid. In the current version (0.7.3) and earlier, a login token is stored on the server in a session variable and on the client in a cookie. A user is only authenticated if the client's token matches the server's. This is good because it prevents account hijacking by stealing cookies (the login token incorporates a timestamp and IP address, so simply copying the cookie won't get you authenticated), but it's a little inconvenient, as your login only lasts as long as your HTTP session does.

To fix this, we will add two lines to our userconfig.cfg. Note that this file is case-sensitive. If you do not have a userconfig.cfg file in your userdata directory, create it with a text editor.

Open up your userconfig.cfg in a text editor and add the code below.
AUTH_USE_SESSION = false
LOGIN_EXPIRE_TIME = 2592000
The first line turns off the paranoid authentication check so that LnBlog will only check for a predefined value in a cookie. The second line sets the expiration time of that cookie. The default value (false) expires the cookie when your browser session end. The number indicates the number of seconds after which the login cookie should expire. The value given above is equivalent to 30 days.

There are a number of other userconfig.cfg settings that might prove interesting. ENTRY_DATE_FORMAT is the format string used to display the post date on entries. Another good one is KEEP_EDIT_HISTORY, which determines whether changes to entries and articles should just overwrite the old data or whether the system should keep a backup copy. The COMMENT_NOFOLLOW configuration constant determines whether links in entry comments should have the rel="nofollow" attribute added to them. And lastly, the ANON_POST_NAME and NO_SUBJECT constants determine what name and subject should be given to comments when the user doesn't enter one.

Hopefully that gives you an idea of how to set some of the more esoteric configuration options in LnBlog. In a future posting, I'll describe userconfig.php, which is similar in purpose, but both much more powerful and much harder to use.

Here's a little piece of trivia for all those who don't read the documentation (which, in reality, is almost everybody): you don't need to know the URL of a post to link to a file uploaded to it. LnBlog takes care of that for you.

How does this work? Well, for files uploaded to a post, it's actually quite easy. When you give the link URL, only specify the name of the file. No path, no domain, just the file name. When you submit the post and view it in your browser, you'll see that the link displays the absolute URI of the file. Basically, when your post is displayed, whether in a browser or RSS feed, LnBlog will scan it for links and image references and convert any bare file name (meaning a relative URL with no slashes in it) into an absolute URI based on the URI of the post.

The handy thing about this is that it's so transparent. This conversion works automatically in both HTML and LBCode markup modes and is done on the href attributes of anchor (<a>) tags and the src attributes of image tags. It works very nicely with the new feature in version 0.7.1 that lets you upload files at the same time you make the post. All you need to do is give the file name and the URI calculation is done for you.

This feature was originally added because I was sick of making a post, uploading my files, and then editing the post because I didn't know the full URI of the files until after the post was submitted. I had to do that because LnBlog bases the URI of a post, and hence the path where its files are stored, on the date and time at which it was made.

Of course, I could have just made a single upload directory and put all my files there, but I didn't really like that idea. I wanted to keep things more "semantic" than that. For some files, like releases of LnBlog, it makes sense to put them in a central directory at or near the blog root. However, some files really are only related to one particular post. To me, it makes sense to keep those files with the post they're meant for. And so I decided to take the guess work out of figuring out the URI for that post.

It's time for part 2 of the LnBlog themes tutorial series. In this episode, we'll cover modifying your sidebar. This will include a brief discussion of how theme templates work as well as an introduction to the plugin system. In the process, we will also create a very simple and extremely unimpressive plugin. Note that in this tutorial, unlike the last one, I will assume that you have a basic knowledge of HTML and CSS. This tutorial will also include some PHP code, although I will nto assume a working knowledge of PHP (although if you have one, it will help).

As you may recall from last time, LnBlog's theme system has a concept of paths. This applies not only to images and style sheets, as we saw before, but also to template. In other words, LnBlog will look for a given template first in your blog's templates directory, second in the templates directory of your current theme, and lastly in the templates for the default theme. This means that you can easily modify the templates for each of your blogs individually or for all of them at a time.

Modifying the template

Let's start by making a copy of your LnBlog/themes/default/templates/include_sidebar.php file and saving it on your local hard drive so we can play with it. If you open up the file in a text editor, you'll notice that there's almost nothing in it. It should just look like this: activateEventFull($tmp=false, "sidebar", "OnOutput"); $EVENT_REGISTER->activateEventFull($tmp=false, "sidebar", "OutputComplete"); ?> Of course, if you don't know PHP, that's probably doesn't mean anything to you. In fact, it probably doesn't mean much even if you do know PHP. That's because this code is part of LnBlog's event system

As you may already know, the default page banner, menubar, and sidebar in LnBlog are all implemented as plugins. If you open up your include_banner.php or include_menubar.php, they'll contain similar code. Basically, this code raises an event, i.e. it tells LnBlog's event manager that something interesting is happening and any plugin that's interested in this event better get it's act together. The event manager them checks a list of plugins that signed up to be notified when this event happens and tells them to do their thing.

Now, since this is a template, we can actually ad HTML code right into it. For illustrative purposes, I'll add some of my favorite links to the sidebar. Here's what the resulting code looks like: <?php global $EVENT_REGISTER; $EVENT_REGISTER->activateEventFull($tmp=false, "sidebar", "OnOutput"); ?> <h3>Recommended Links</h3> <ul> <li><a href="http://blogs.msdn.com/oldnewthing/">The Old New Thing</a></li> <li><a href="http://www.securityfocus.com/">Security Focus</a></li> <li><a href="http://www.larkware.com/">The Daily Grind</a></li> </ul> <?php $EVENT_REGISTER->activateEventFull($tmp=false, "sidebar", "OutputComplete"); ?> Notice that I broke the PHP code into two blocks and put the HTML in between them. Since tempaltes are actually PHP files, anything inside the <?php ?> tags is treated as PHP code, and anything outside them is treated as HTML. If you're sharp, you probably noticed that I did this because of the event code: I put my markup between the OnOutput and OutputComplete events.

If you save this file and upload it to your blog's templates directory, you'll see your list of links in the sidebar. However, you'll notice that the links are at the bottom of the sidebar. That's because all the plugins are loaded by the OnOutput event. If you move the HTML code above that event, then all your links will end up at the top of the sidebar. But what if you want your links in the middle somewhere? Maybe you want your links between your articles and your RSS feeds. Well, that's why this isn't the recommended way to add to the sidebar.

A simple sidebar plugin

However, there is good news. Writing a simple plugin to display some links in the sidebar is easy. Really easy. In fact, it's about a dozen lines of boiler-plate PHP code with your HTML inserted in the middle. And once you have the plugin written, it will be detected by the plugin manager and you will be able to change where it appears in the sidebar by changing its load order in the plugin loading configuration page.

Here's a plugin version of the links in the example above: <?php class MyLinks extends Plugin { function MyLinks() { $this->plugin_desc = "Shows my favorite links in the sidebar"; $this->plugin_version = "0.1.0"; } function show_links() { ?> <h3>Recommended Links</h3> <ul> <li><a href="http://blogs.msdn.com/oldnewthing/">The Old New Thing</a></li> <li><a href="http://www.securityfocus.com/">Security Focus</a></li> <li><a href="http://www.larkware.com/">The Daily Grind</a></li> </ul> <?php } } $plug = new MyLinks(); $plug->registerEventHandler("sidebar", "OnOutput", "show_links"); ?> This is about the simplest plugin you can have. It is a simple PHP class with a constructor that defines the version number and a short description, and a single method that dumps some HTML output to the screen. Note at the bottom that you have to create an instance of the class and register the method with the event manager.

Now is probably a good time to mention that plugins use a path mechanism too. In other words, you can have plugins that apply only to a single blog, just like you can with theme template and style sheet. Just make a "plugins" directory in the blog's directory and put the plugins there. They will be treated just like a regular plugin, but no other blog will be able to see them.

So, now let's install your new plugin. Copy the above code and paste it into a new file named sidebar_mylinks.php. Note that it is very important that you not have any blank lines or spaces outside the PHP <?php >> tags, as this will cause error messages due to the way PHP handles output. Now, create that plugins directory in you blog's directory on the server and upload the sidebar_mylinks.php file into it. If you open up your blog in a web browser, you should see the new links. If you change the load order of your sidebar_mylinks plugin from the plugin loading page, then the link section will move in the sidebar.

If you want to have several independant sidebar sections, you can make copies of this plugin to achieve that. Just change the HTML code, the plugin_desc on the fourth line, and change all three instances of the name MyLinks to MyOtherLinks, or something like that (the exact name doesn't matter, so long as no two plugins have the same name). If you're feeling adventurous, you can also adapt this to add markup to the banner or menubar by changing the "sidebar" parameter in the registerEventHandler line to "banner" or "menubar".

You can download files for this tutorial here. In the next installment, we'll go into theming the content areas of a page, including templates for blog entries. We'll also cover modifying the associated style sheets and possibly adding some images.

It's been a long time since I posted anything, so I figured I'd put up a little informal documentation on the theme system. After all, who wants to be stuck with just the default themes? The answer is: me, because I'm the one who designed them. But I'm sure other people would like to personalize the look of their site a bit.

Today, let's talk about setting a custom page banner. That seems to be one of the first things most people change on their blog. Plus it's fairly easy to do in LnBlog and doesn't require a great deal of HTML or CSS knowledge. So let's get started!

For this exercise, you'll need two things. The first is a banner image. It can be anything you want, so long as a web browser can display it and it's a suitable size. Since I'll be assuming you use the default LnBlog theme, which is not fixed-width, I'd recommend a JPEG image that's at least 1024 pixels wide and around 160 pixels high. For illustrative purposes, I'll use this picture of the hills. If you have a moderately high resolution digital camera, you can probably take a decent picture yourself and use the GIMP or some other image editor to cut out an appropriately sized image.

The second thing you'll need is a copy of your banner style sheet to work on. This one is easy: just go into your LnBlog/themes folder, find the directory for your theme, and copy the styles/banner.css file to someplace on your local hard drive so that you can edit it.

Now that we've got a stylesheet and an image, setting the banner background is easy. Just open up your copy of the banner.css file, find the #banner section, and change it so it looks like this: #banner { width: 100%; border: 1px solid black; background-image: url(../images/horizon.jpg); background-repeat: no-repeat; max-width: 1281px; max-height: 160px; } This gives us a banner box with a thin border and our horizon image as the background. Note that the max-width and max-height are set to the width and height of the image. This keeps the box from expanding to larger than the size of the picture and looking funny.

As long as we're in the style sheet, we might as well consider the text. Let's say, for the sake of argument, that you wanted to change the alignment of the default banner text. Let's say you want to put the blog name on the left side of the banner and the description on the right. Well, in that case, you would look for the #banner h1 style for the name and the #banner h3 style for the description. If you look just below the section we just modified, you'll see something like this: #banner h1, #banner h2, #banner h3 { text-align: center; vertical-align: middle; color: white; } This sets the default style for the first three levels of heading. We can override the alignment by simply creating additional styles below that section, because in CSS, styles later in the file take precedence over earlier ones. So, let's add the following: #banner h1 { text-align: left; margin-left: 10%; } #banner h3 { text-align: right; font-style: italic; margin-right: 10%; } This gives us a left-aligned heading, and a right-aligned, italicized description. (If you don't see a blog description, you can turn it on in the plugin configuration page, under the "pageheader" plugin option.) Note the margins are set so that the text doesn't bump up against the edge of the banner.

So at this point, we have our image and our stylesheet. Now what? Well, we install them on the server, of course! But where to put them?

This is where the flexibility of LnBlog's theme system come in. You see, we actually have several options. First, we can always put them in our theme directory, overwriting the old style sheet. The second possibility is creating a new theme. The third is applying this only to a single blog. Changing the files for the default themes isn't really recommended, so we'll stick to the second and third options.

Creating a new theme, especially one this simple, is quite easy. Just go into your LnBlog/themes directory and create a new folder with whatever name you want the theme to have. Then, inside that folder, create four more folders with the following names: images, styles, scripts, and templates. Now copy your banner image into the images directory you just made and put the banner.css file in the styles directory. Now, if you edit your blog setting and change the theme to the one you just created, you should see your new banner.

The process for applying your custom banner to a single weblog is very similar. You would simply open up the directory for that weblog and create an images directory and a styles directory. Copy your image and style sheet to the corresponding directories and the changes will automatically take effect for that blog.

By now, you've probalby noticed the pattern here. When constructing a page to send to the client web browser, LnBlog uses a search path mechanism to find files. There are four kinds of files: images, styles, scripts, and templates. LnBlog looks for each type of file in a directory of the same name, located in the current blog's folder, the current theme's folder, or the default theme's folder. The search takes place in that order, so if you don't have a particular file in your blog or in your theme, the default will always be there. The idea is to make it easy to create small variations on existing themes. The down side, of course, is that it's somewhat more difficult to create custom themes from scratch. But, then again, given that you have to get all the template variable right in order for things to work, it's usually easier to just start from an existing theme anyway.

Next time, we'll talk about templates and how the enevt-driven plugin system interacts with them.