#=========================================================================== #= Project: PluggedOut Blog #= File : readme.txt #= Version: 1.9.9i (2006-08-31) #= Author : Jonathan Beckett #= Email : email@example.com #= Website: http://pluggedout.sourceforge.net/development/ #= Website: http://sourceforge.net/projects/pluggedout/ #= Support: http://pluggedout.sourceforge.net/development/forums/index.php #=========================================================================== #= Copyright (c) 2005 Jonathan Beckett #= You are free to use and modify this script as long as this header #= section stays intact. This file is part of PluggedOut Blog. #= #= 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 CMS files; if not, write to the Free Software #= Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA #=========================================================================== Contents ======== - Introduction - Internet Links for the Blog Project - Requirements - Installation Steps - Overview of Themes - Overview of Plugins / Includes - Development & Support - About the Developer - Contact Information - Credits Introduction ============ PluggedOut Blog is an open source Online Diary/Journal solution written by Jonathan Beckett. It is intended as a "starting point" for you to build on top of for your own solution - although you must retain the comments at the top of each page and the accompanying files (such as this one) detailing things like the project homepage for the benefit of others. If you are new to the world of web development, PluggedOut Blog has a development discussion board (the URL is provided below) for users of the script to request help and to swap tips with each other. It is important that the blog script is not seen as a "solution". You may not be able to just "plug it in and go", so should not complain if you find your web host causes complications. If nothing else, please use PluggedOut Blog to help you learn about PHP and MySQL. It is highly recommended that you use a database administration tool like PHPMyAdmin to setup your database if you don't already have one (it makes things much easier for anybody but MySQL gurus). If you do get stuck, please do visit the support forums detailed in this file - there are lots of people helping each other there, and of course I am on hand in the forums too. Regards PluggedOut Development Team Internet Links for the Blog Project =================================== PluggedOut Blog Project Homepage - http://pluggedout.sourceforge.net/ PluggedOut Blog Development Homepage - http://sourceforge.net/projects/pluggedout/ PluggedOut Blog Example Installation - http://www.noidea.us/blog/ PluggedOut Blog Wiki (User Guide, FAQ etc) - http://pluggedout.sourceforge.net/ PluggedOut Blog General Support Forum - http://pluggedout.sourceforge.net/development/forums/viewforum.php?f=26 PluggedOut Blog Themes Forum - http://pluggedout.sourceforge.net/development/forums/viewforum.php?f=27 Requirements ============ - PHP >= 4.x - MySQL >= 4.x - Apache or IIS (really any web server that will run PHP/MySQL) Installation Steps ================== 1. Place the unzipped files somewhere into your web root. Be careful to make sure your extraction software maintains the directory structure present within the ZIP file when you extract. 2. Make sure the uploads directory is readable and writeable (use CHMOD), and that the themes directory, it's subdirectories and the files within are read and writable. Make sure the rss.xml file is writable. 3. Copy lib/config.sample.php to lib/config.php. Change the new lib/config.php script to suit your database settings. 4. Run the admin/install.php script through your browser - this creates all the tables required for the project. 5. That's it! You can now access the blog via the path you installed it in your webserver. To add and edit entries, visit the URL on your system similar to the one depicted below; http://yourdomain/admin/index.php The default login created for the system (that you can change as soon as you are logged in is as follows; username : admin password : password Overview of Themes ================== Most people are going to want to modify the Blog script heavily to suit the look and feel they want. Blog supports themes through chunks of HTML stored in a simple file system within subfolders of the "themes" directory. To create a theme, just copy the "default" theme folder to a differently named folder (the name of the folder is the name of the theme), and start fiddling with the html files contained. * There is a very good diagram in the /docs directory showing you how the theme template files fit together. In general, the theme files can all be thought of as being "glued" together by the system when people ask for a page. The bits and pieces of HTML in the various HTML files are added together like so; 1. The system gets the blog entries from the database 2. The system puts the data from the blog entries into entry_view_item templates - substituting the data for markers within the template. The available markers for entries are; <!--entryid--> The database ID of the entry <!--entry_url--> The URL required to view the specific entry <!--title--> The title of the entry <!--body--> The body of the entry <!--user_added--> The user who added the entry <!--user_edited--> The user who edited the entry <!--comment_count--> The number of comments against the entry <!--comment_url--> The URL required to view the comments <!--entry_categorylist--> The list of categories an entry is filed against The date added and date edited can both be substituted in via markers similar to those below (modify them for "edited") <!--date_added--> Date in yyyy-mm-dd hh:mm:ss format <!--date_added_daynum--> Day of the Month (1 to 31) <!--date_added_dayname_long--> The long dayname (e.g. "Wednesday") <!--date_added_dayname_short--> The short dayname (e.g. "Wed") <!--date_added_monthnum--> The month number (1 to 12) <!--date_added_monthname_long--> The long monthname (e.g. "March") <!--date_added_monthname_short--> The short monthname (e.g. "Mar") <!--date_added_yearnum--> The year number (e.g. 2005) <!--date_added_hour--> Hour of the day (0-23) <!--date_added_minute--> Minute of the hour (0-59) <!--date_added_second--> Seconds of the minute (0-59) 3. The system glues all the item templates together and puts them into the entry_view_section, putting the entry_view_sep template between each entry_view_item template. (the same basic process applies for entry_list as entry_view) 4. The system builds the category list by picking up the category_list template, and filling it with categorylist_item templates, which can have the following substitutions; <!--url--> The URL needed to show the entries within the category <!--name--> The name of the category The basic ideas described here are followed throughout the templates, with the final chunks substituted into the page template. If you have questions about making themes, feel free to post to the PluggedOut Blog development forum. Overview of Plugins / Includes ============================== You can put your own PHP files in the "/includes" directory, and call them from blog entries or tempaltes by writing a BBCode tag as follows; [include:your_function_name] ... where "your_function_name" is the name of a function residing in a PHP file within the includes directory. There are a couple of example functions distributed with the Blog script to get you started. There is also a sample include, show-rss.php, which relies on the plugins/magpierss directory. see doc/show-rss-include-README.txt. Development & Support ===================== If you want to help with PluggedOut Blog or want some support, feel free to visit the Blog discussion forums at the following URL... http://pluggedout.sourceforge.net/development/forums/viewforum.php?f=26 About The Developer =================== The PluggedOut Blog script was written by Jonathan Beckett. In the daytime he is a professional software and website developer, working in both the Windows and Linux worlds. He's usually got time to reply to emails, but he would encourage you to visit the PluggedOut Blog support forum if you are stuck. Contact Information =================== - Name : Jonathan Beckett - Location : Marlow, Bucks, United Kingdom - E-Mail : firstname.lastname@example.org - URL : http://www.pluggedout.com Credits ======= The PluggedOut Blog project uses a couple of scripts from other developers to help provide various elements of functionality. Kai Blankenhorn, Scott Reynen and Dirk Clemens http://www.bitfolge.de Developers of the RSS functionality used by the Blog project to ouput valid RSS data streams. Andrew Burns http://www.neodynium.com Andrew has given me assistance on many an occasion with regular expression syntax.