BLOG:CMS Manual (v3.0)

# Table Of Contents

- About BLOG:CMS
- License: GPL
- Installation
- Modifying skins and templates (separate file)
- Security Aspects
- Performance Aspects
- Importing from other tools
- What's allowed/disallowed in comments?
- XML-RPC Interface
- Troubleshooting (FAQ)
- Tips & Suggestions (separate file)
- Known Problems
- Version History (separate file)
- Credits & Thanks

# About BLOG:CMS

BLOG:CMS is a Content Management System (CMS): a powerful set of PHP scripts that allow you to maintain one or more weblogs or online journals. A short summary of the most important features is given below:

- Runs on your own server
- One or more weblogs, even on the same page
- Plugin-interface to add extra functionality
- Comments
- Archives
- Categories
- Search
- Multiple authors
- Future items
- Drafts
- Extensive administration area
- Media library and file upload
- Fully customizable skins and templates
- Skin import/export
- Banlist against commenting system abuse
- RSS syndication
- Easy installation
- Easy backups
- XML-RPC interface (implementing the Blogger API and metaWeblog API)
- XHTML-ready
- Tools to import Blogger and GreyMatter blogs
- ...

Requirements in order to run BLOG:CMS: (If you don't know if you fit the requirements, ask your system administrator)

- PHP (version 4.0.6 or higher)
- Access to a MySQL database (version 3.23.38 or higher)
- Some HTML and CSS knowledge, to edit skins and templates

BLOG:CMS is intended for the people that want full control and 'tweakability' over their sites. If you're just looking for a very simple way to put up a site, or don't know any HTML, you might want to use a 'simpler' service such as Blogger.

# License

BLOG:CMS: PHP/MySQL Weblog CMS (http://blogcms.com/)
Copyright (C) 2003-2005 BLOG:CMS
Copyright (C) 2002-2003 The Nucleus Group

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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Your possession of this software signifies that you agree to these terms. Please delete your copy of this software if you don't agree to these terms.

# Installation

Installing BLOG:CMS is done through some steps:

## 1. Unzip

Unzip all files to a directory of your computer. Make sure the path names are used when unzipping. You should end up with the following directory structure (* stands for a number of files):

    /*                         (main files for site)
    /admin/*                   (main files for admin-area)
    /admin/javascript/*        (javascript helper scripts)
    /admin/libs/*              (BLOG:CMS core libs)
    /admin/language/*          (definitions of languages)
    /admin/plugins/*           (plugin-dir)
    /admin/xmlrpc/*            (XML-RPC interface)
    /admin/documentation/*     (Documentation + admin-area help)
    /admin/styles/*            (stylesheets for docs & admin-area)
    /admin/forms/*             (skeletons for commentforms etc)
    /extra/*                   (extra goodies)
    /skins/*                   (skins directory [imported skins will go here])
    /media/*                   (media library directory [emtpy])

## 2. Upload files

Upload all files to your server, using your favorite FTP program. Make sure to upload .php files in ASCII mode! It might not work otherwise.

### Optional:

1. To make your install process even easier, you can change the file permissions on config.php to 666. This way, the install script will be able to update it automatically instead of you having it to do manually. (Quick guide on how to change file permissions)
2. If you want to use file upload, you'll need to add write permissions to the /media/ directory. This is needed in order to allow PHP to write uploaded files into that directory. The directory should be chmodded to 777 (Quick guide on how to change file permissions). (If you have root access, you can instead `chgrp` the directory to the user that is running the `httpd` process (usually `httpd` or `nobody`, then `chmod 775` the directory).

## 3. Run install.php

Open your web browser open the URL below, where you adapt the yoursite and yourpath parts.

    http://www.yoursite.com/yourpath/install.php

This install-script will prompt you for some information, and perform most of the installation for you. When everything has succeeded, install.php will provide you with further instructions. (you'll still need to delete some files manually)

Note: When you open install.php in your browser and you see the text "If you see this text in your browser...", or you are prompted to download 'install.php', then your web server does not support PHP, and you won't be able to run BLOG:CMS there.

## 4. Done!

You should now be able to visit your site at http://yoursite.com/weblog/ (or whatever URL maps to the location where you uploaded the BLOG:CMS site main files)

## 5. Important!

Please note that this will install only weblog part of BLOG:CMS, not forum, wiki and photo gallery. For installing and configuring those, please refer to Online Installation Manual.

# Security Aspects

## mySQL passwords

Since BLOG:CMS needs to connect to a mySQL database from a PHP-script, the password for that database must be stored inside a PHP-file. On multi-user systems, this might cause an unevitable security risk: On some systems, other users will be able to read your login information. You might want to contact your system operator to find out how secure it is to store sensible information inside PHP-scripts.

The problem above is common to all PHP scripts that need to connect to a database. As a user, there's usually nothing you can do about it in order to make things 100% secure. We just want you to be aware of this potential danger.

## Cookies

BLOG:CMS uses cookies to store user login information. This could cause a security risk when your cookies are stolen. Although your password is not derivable from the cookie (the values stored in the cookie are the username and a randomly generated string), there could be ways to 'fake' the cookie on another computer and thus to get logged in.

## Media dir

When you want to enable file upload, you'll need to set the permissions of the media dir to 777, which means that everyone on that server will be able to delete/add/... files. The reason why this is needed, is that PHP mostly runs as the httpd user, and that user needs to be able to access this dir and write to it. Here also, there's no way around this.

# Performance Aspects

Contradictory to some other weblog/online journal scripts, BLOG:CMS does not generate a static version of all items (unless you install NP_Cache.php plugin, provided in a default download package). This means that every time a page is requested, the PHP parser is called and the database is accessed to dynamically create the requested page.

For small web sites, this should not cause any problem. For web sites that get dozens of hits per second, the effect on the systems performance isn't really known. So far, no problems have been reported by BLOG:CMS users (some are running pretty big sites on it, with 30 or more weblogs on a single installation).

# Importing From Other Tools

BLOG:CMS contains some conversion scripts under `/convert/` that allow you to import the data from your 'old' weblog tool into your BLOG:CMS weblog. No data is destroyed during this process.

# What's allowed/disallowed in comments?

BLOG:CMS has some built-in rules concerning comments:

- words longer than 90 characters are not allowed (why: layout might get messed up when people do that)
- the actual comment should be at least 3 characters long
- comments cannot be longer than 5000 characters
- guests need to enter a username of at least 2 characters
- guests cannot use quotes or newlines in username/email
- each sequence of 3 newlines in the body gets replaced by a single newline (why: layout)
- HTML tags are replaced by entities
- the comment is trimmed (leading and trailing whitespace is left of)
- URLs are 'hreffed'. To avoid layout mess-ups, the URLs are shortened.

As for now, all of these rules and parameters are hardwired into the code.

# XML-RPC Interface

The URL for the BLOG:CMS XML-RPC interface is:
http://www.yourserver.com/yourpath/nucleus/xmlrpc/server.php

XML-RPC is a format for remote calls using XML messages. Sounds complex, but implementing an XML-RPC interface into an application allows other services to communicate with it.

Currently, the Blogger API and the metaWeblog API are implemented. If you want an examples of such a client, try w.Bloggar, a client for machines running Windows.

# Troubleshooting (FAQ)

Below, some of the most common problems with and questions about BLOG:CMS are answered. Please read these first before you ask for help. In many cases, the solution can be found here.

I get an error: Cannot send headers. Headers already sent...
This problem is usually caused by whitespace at the beginning or end of `config.php`. Check if it has spaces or newlines before the starting `<?` or after the ending `?>`. If there are, remove them. The problem can also have to do with spaces in the language file or one of the installed plugins.
When I try to run install.php, I'm prompted if I want to download install.php
Your web server is not set up to support PHP scripts. You won't be able to install BLOG:CMS on such a system.
When I try to visit my website, I get a 'Connection Error'. Why?
The reason why this error is shown is that BLOG:CMS cannot connect to your database server for one reason or another, or it cannot select the database. One possible reason is that your login information in config.php is incorrect. Another is that the mySQL server is down.
I can't get my update file to work!
File permissions need to be set correctly in order for the update file to work. The update file also needs to exist prior to changing the blogsettings. (e.g. you can create an empty file and upload it). About the file permissions, make sure the update file is chmodded to 666 and the directories are chmodded to 755. (Quick guide on changing file permissions)
I don't want the XML-RPC interface to be available
You can simply delete the xmlrpc/ directory without causing trouble.
I don't want RSS syndication (headlines) to be available
You can safely delete the xml-rss.php (headlines.php) file and the 'xmlrss' (headlines) skin/template

# Known Problems

Some known issues/bugs:

- Ctrl + Shift + A shortcut might conflict with ICQ/Trillian
- When PHP is running in SAFE mode, it's very likely that there will be problems when using the media directory (BLOG:CMS will not be able to automatically detect image sizes, or disallow uploading)
- The notify-address option in blogsettings has a preset limit of 255 chars, which means you can't put too many e-mail addresses in there.
- Live preview doesn't work correctly in Mozilla

# Credits & Thanks

## Core development

- Radek Hulan
- Wouter Demuynck
- Appie Verschoor

## Code submissions / Patches

- Andrew Brampton
- Terry Chay
- Rodrigo Moraes
- Aleto

## Libraries etc

- Plugins are written by their respective authors.
- Thanks should go out to the people that wrote language-files for BLOG:CMS. You can download extra language files on the Nucleus website.
- The XML-RPC interface uses the 'XML-RPC for PHP' implementation from Useful Inc..
- The backup/restore code is largely inspired on the code used in phpBB.
- The JavaScript code used for the instant preview was originally inspired on the code used by Mijn Kop Thee (dutch) and milov.nl.
- The globe bullet next to links in the admin screen, comes from QBullets