PolarBlog Documentation

Last Updated: January 15, 2006

Contents
Introduction
Features
Requirements
Installation
Upgrading
Configuration
Main Display
Administration
A. Acknowledgements
B. Personal Weblog Compatibility
C. Enabling Left Navigation
D. Comment IP Blocking
E. Entry & Comment Auto-Linking
F. Posting via POP3 Email

Introduction  top

PolarBlog is an easily configurable embedded weblog solution.  There are two primary target audiences for PolarBlog:

  1. Those who want a blog that can easily be integrated with their existing web site's look and feel.
  2. Users of Personal Weblog who are looking to easily migrate to a more feature rich solution without losing their existing Personal Weblog entries.

Because PolarBlog's look is all CSS based, it can also be configured to look and function as an independent entity that is not themed like the rest of a web site.

There are two factors that have driven the development of PolarBlog:

  1. My needs and desires out grew my previous solution.  (Click here for the full explanation.)
  2. I couldn't find another solution I liked and I wanted to easily migrate my existing blog entries.  When in doubt, do it yourself!
Features  top

Standard Features  top
Optional Features  top
Requirements  top
Installation  top

The majority of the instructions in the New Installation section below apply to all installations.  Users migrating from Personal Weblog (PWL) should follow these steps also and will be advised within when they should proceed to the Migrating from Personal Weblog section.  Before beginning a migration installation you are highly recommended to read the Personal Weblog Compatibility section.

New Installation  top
  1. Download the latest PolarBlog release.
  2. Familiarize yourself with the changes made to PolarBlog by reviewing the CHANGES file.
  3. If you are installing PolarBlog on a Gentoo Linux system, you should review this mailing list message.
  4. Untar the archive in your web directory.  A directory will be created of the format "PB_vXX", where "XX" is the version number.  (e.g. "PB_v10" for PolarBlog V1.0)
  5. Either rename the directory to "polarblog" (or another name of your choosing) or create a "polarblog" symbolic link to the current release directory.
  6. In order for RSS to work you need to give the "polarblog" directory read/write permission: chmod 777 polarblog
  7. Go to the PolarBlog CSS directory: cd polarblog/css
  8. Copy/enable one of the distribution CSS files: cp standard.css.dist standard.css  You can edit this CSS file as required after completing the installation.  If you would like to use the left navigation option, please see the Enabling Left Navigation appendix.
  9. Go to the PolarBlog configuration directory: cd polarblog/config
  10. Copy the distribution configuration file: cp config.php.dist config.php
  11. Edit your configuration file (config/config.php) as necessary.  At the minimum you must set the following configuration settings for PolarBlog to function: You can learn more about these configuration options as well as all of the configuration options in the PolarBlog Configuration section below.

    Note: The database DB_USER for normal PolarBlog operation only needs to have INSERT, SELECT and UPDATE privileges.  For the installation process the DB_USER must also have the ability to ALTER, CREATE, DROP and INDEX tables.

    Note: The installation process will create all the required database tables.  You only need to create and specify the database for PolarBlog to use.

  12. If you are migrating from Personal Weblog (PWL), you should now go to the Migrating from Personal Weblog instructions below.  If you are creating a new installation, please read on.
  13. Point your web browser to http://your-domain.com/polarblog/install.php
  14. Select "New Installation"
  15. You must now enter the following information:
    1. Database Table Prefix - Unless you have a compelling reason to change this, you should leave this at the default of "pb_".  If you do change it here, you will also need to change the "DB_PREFIX" setting in the configuration file before you can use PolarBlog.
    2. Admin Username - The username you would like to use to login and administer your PolarBlog system.  This is also your default login for posting entries.
    3. Admin Password - The password for your Admin account.
    4. Admin Password Verify - The Admin password again for verfication.
    5. Password Hint - A description that will jog your memory as to what your password is should you ever forget it.  Passwords are encrypted in the database and cannot be recovered!
    6. Admin Post As - The name you would like your Admin entries posted as.  For example: "Posted by Kevin"
    7. Admin Email - A valid email address for the Admin account.
  16. Verify the information you entered above and click the Submit button to create your initial PolarBlog database configuration.
  17. If the database configuration succeeded without any problems, You now MUST DELETE install.php!  Failure to do so could possibly leave your database subject to potential corruption by others!  You do not need to run any of the Upgrade Options you see listed on the installation screen.
  18. If your database configuration was not successful, you should be looking at a screen describing the error(s).  Save this information and correct the problem(s) it identified.  If you need further assistance, post a message describing the problem you are having and the error message(s) you received to the PolarBlog Mailing List.
  19. If your web server supports .htaccess files, you are highly advised to review the .htaccess File section below and implement the recommendations there as necessary.
  20. Pointing your web browser to: http://www.your-domain.com/polarblog/ should now display your new PolarBlog installation.
  21. You may now want to adjust your configuration as described below as well as edit the CSS to meet your needs.  Enjoy!

Migrating from Personal Weblog  top

Begin by following the instruction in the Installation section above.  You will be told when to come to this section and perform the following items.

  1. Your existing PWL installation should continue to function after completing this migration process.  This will allow you to continue to use PWL until you are ready completely switch to PolarBlog.
  2. In order to protect yourself in the unlikely event that something does go wrong, Backup your PWL database!  Also, should you decide you'd rather continue with PWL you will be able to restore your database.
  3. You should again edit your configuration file and set the "DB_PREFIX" value to what you are currently using for PWL.  If you are not using a DB prefix for PWL, you should set this to an empty string.
  4. If your web server supports .htaccess files, you are highly advised to review the .htaccess File section below and implement the recommendations there as necessary.
  5. Point your web browser to http://your-domain.com/polarblog/install.php
  6. Select "Migrate from Personal Weblog (PWL)"
  7. You must now enter the following information:
    1. Database Table Prefix - This should be displaying the DB_PREFIX value you just entered in your configuration file.  If not, you need to go back and correct that before continuing.
    2. Admin Username - The username you would like to use to login and administer your PolarBlog system.  This is also your default login for posting entries.  PolarBlog does not use the same login credentials as your existing PWL installation.  Also, all existing entries in your PWL database will be associated with this user.  Later on you can add additional users and assign existing entries to them if you so desire.
    3. Admin Password - The password for your Admin account.
    4. Admin Password Verify - The Admin password again for verfication.
    5. Password Hint - A description that will jog your memory as to what your password is should you ever forget it.  Passwords are encrypted in the database and cannot be recovered!
    6. Admin Post As - The name you would like your Admin entries posted as.  For example: "Posted by Kevin"
    7. Admin Email - A valid email address for the Admin account.
  8. Verify the information you entered above and click the Submit button to migrate your PWL database to a PolarBlog database configuration.
  9. If the database migration succeeded without any problems, You now MUST DELETE install.php!  Failure to do so could possibly leave your database subject to corruption by others!
  10. If your database configuration was not successful, you should be looking at a screen describing the error(s).  Save this information and correct the problem(s) it identified.  If you need further assistance, post a message describing the problem you are having and the error message(s) you received to the PolarBlog Mailing List.
  11. If your web server supports .htaccess files, you are highly advised to review the .htaccess File section below and implement the recommendations there as necessary.
  12. Pointing your web browser to: http://www.your-domain.com/polarblog/ should now display your new PolarBlog installation.
  13. You may now want to adjust your configuration as described below as well as edit the CSS to meet your needs.  Enjoy!
  14. When you are ready to switch to PolarBlog and no longer need PWL, reinstall the install.php file and run the "Post PWL Migration Cleanup" option.  This will remove the "vars" table as it is no longer required.  Don't forget to DELETE install.php when you are finished!  You can then delete the files associated with PWL from your server.

Upgrading from a previous version  top

If you are upgrading from an older version of PolarBlog, this section contains instructions on any necessary steps that must be taken to install the newer version.  You should review the PolarBlog CHANGES file to see a complete list of changes made in the release.  The following are the standard upgrade procedures:

  1. Download the latest PolarBlog release.
  2. Untar the archive in your web directory.  A directory will be created of the format "PB_vXX", where "XX" is the version number.  (e.g. "PB_v10" for PolarBlog V1.0)
  3. Copy your configuration file (config/config.php) to its place in this new release directory tree.
  4. Copy your CSS file (css/*.css) to its place in this new release directory tree.
  5. Follow the instructions below for your specific upgrade and then continue here.
  6. In order for RSS to work you need to give the "polarblog" directory read/write permission: chmod 777 polarblog
  7. If you are upgrading from a version less than (<) 1.2.2, you must run the "e;Upgrade PolarBlog" option from the installation utility.
  8. DELETE the install.php file!  Failure to do so could possibly leave your database subject to corruption by others!
  9. Either rename the directory to "polarblog" (or another name of your choosing) or create a "polarblog" symbolic link to the current release directory.

.htaccess File  top

If your PHP installation is running with register_globals ON (very common hosted/ISP systems), it is HIGHLY RECOMMENDED that it be turned off for PolarBlog.  It is recommend that use_trans_sid (more info/why?) which allows session ID's to be appended to a URL also be disabled as it too is a potential security risk.  If your hosting provider (ISP) supports .htaccess files (as most do), then you can create a .htaccess file in your PolarBlog directory. This file should have 644 (u+rw,g+r,o+r) permissions and contain the following:

	  php_flag register_globals off
	  php_flag session.use_trans_sid off

You may also want to add the following PHP specific directives for additional security.  Ideally, these directives should be in a separate .htaccess file in your web server's root document directory (htdocs, public_html, www, etc.).  This will cause any PHP errors to be logged to the specified file and not displayed on your web site.

	  php_flag display_errors off
	  php_flag log_errors on
	  php_value error_log /path/to/file/not/in/web/space/php_error.log

Note: The "error_log" file must be writable by your web server.


Configuration  top

Standard Configuration  top

There are a number of user configurable options that affect the way PolarBlog looks and behaves.  All user adjustable settings are contained in the "config.php" file located in the "config" sub-directory.  For a new installation you will need to copy "config.dist.php" to "config.php".  Below is a listing of the various configuration options, their default values and an explanation of what each option does.

Paths & Session Configuration  top
Configuration Option Default Value
BASE_URL  top http://www.your-domain.com/
  This is the default URL of PolarBlog.  This value is automatically set and in most cases should not need to be changed.
LIB_PATH  top /your/path/to/public_html/polarblog/lib/
  This is the full directory path to the PolarBlog libraries.  This value is must be uniquely set for each installation.
JS_URL  top BASE_URL/js
  This is the URL to the PolarBlog JavaScript libraries.  This configuration option was added in PolarBlog V1.1.0.
PB_SESSION_PATH  top /tmp/
  This is the full directory path to where PolarBlog session files are stored.  This is a major security risk, particularly if you are using PolarBlog on a virtually hosted server. It is HIGHLY RECOMMENDED that this be set to a directory within your user directory space if you are running on a virtual host.  The directory permissions must be set such that the web process can read and write to this directory to maintain your session data.  It is best to choose a directory outside of your web space.  If you do need to create it within your web directory, you should create a ".htaccess" file to prevent a browser from being able to view the contents of the directory.
PB_SESSION_NAME  top PolarBlog
  This is the name of your PolarBlog session.  It should not need to be changed, but if you feel the need you can do so here.

Database Configuration  top
Configuration Option Default Value
DB_PREFIX  top pb_
  This PolarBlog database table prefix value.  This value is appended to all table names.  If you are not migrating from PWL, this should not need to be changed, but if you feel the need you can do so here.  For those that are migrating from PWL you need to set this value to whatever you are using in PWL.  This may include setting it to an empty string if you did not specify a database prefix in PWL.
DB_HOST  top localhost
  This is the name of your MySQL host server.  This value is must be uniquely set for each installation.
DB_NAME  top mysql_database
  This is the name of the MySQL database where you are installing PolarBlog.  This value is must be uniquely set for each installation.
DB_USER  top mysql_user
  This is the username for the MySQL database where you are installing PolarBlog.  This value is must be uniquely set for each installation.
DB_PASSWD  top mysql_password
  This is the password for the MySQL database where you are installing PolarBlog.  This value is must be uniquely set for each installation.
DB_CONNECT  top standard
  This is connection type you want to the MySQL database server where you are installing PolarBlog.  This should be set to either "standard" or "persistent".  Persistent connections can provide a significant performance advantage for some installations, but please read the PHP manual regarding persistent database connections and the mysql_pconnect function before using this option.  For most installations you should not need to change this setting.
DB_PORT  top 3306
  This is the port number for the MySQL host server where you are installing PolarBlog.  For most installations you should not need to change this setting.

Localization  top

PolarBlog provides the ability to localize your configuration to display all system text, dates and times in your local format.  Localization support was added in PolarBlog V1.3.0.

Configuration Option Default Value
I18N_LANG  top en_US
  This defines the language and country for your PolarBlog installation.  For information on how to set this language and country option, please see this language code and this country code information.  If you are changing this setting you may need to also change the I18N_CHARSET and $config['rss']['encoding'] settings.
I18N_CHARSET  top iso-8859-1
  This defines the character set that your PolarBlog will utilize.  For information on setting this option, please see this character set information page.  If you are changing this setting you may need to also change the I18N_LANG and $config['rss']['encoding'] settings.
I18N_DATE_SEPARATOR_FORMAT  top %A, %B %e, %Y
  This enables and sets the date format for the entry date separator bar.  If you don't want the date separator bar, comment out this setting.  For information on the available date format options, please see the PHP strftime function.  This option supercedes the deprecated DATE_SEPARATOR_FORMAT option.
I18N_DATE_FORMAT  top %I:%M%p %B %e, %Y
  This sets the date format for each PolarBlog entry.  For information on the available date format options, please see the PHP strftime function.  This option supercedes the deprecated DATE_FORMAT option.
setlocale()  top Commented out
  If you are using PolarBlog in a language other than English, you may need to enable and configure this PHP function for your system.  If it is required, typically you would set this to the same value as your I18N_CHARSET setting: setlocale(LC_ALL, 'es_ES') for Spanish or setlocale(LC_ALL, 'de_DE') for German.  For more information see the PHP setlocale() manual page.

Output Compression  top

PolarBlog provides the ability to GZip your content output that is sent to the user's browser if it supports compression.  Output Compression support was added in PolarBlog V1.4.0.

Configuration Option Default Value
USE_GZ_OUTPUT  top FALSE
  This enables GZip output compression.  Your PHP installation must be compiled with Zlib support in order to use this option.
GZ_LEVEL  top 6
  This sets the GZip output compression level.  This setting can be from 0 (no compression) to 9 (maximum compression).  The default value of 6 provides a good balance between very good compression and speed.
GZ_DEBUG  top FALSE
  This enables the outputting of informational debug headers in the GzContent class and should only be enabled for debugging purposes.

Display Configuration  top
Configuration Option Default Value
BLOG_NAME  top PolarBlog
  This is the name of your blog.  This configuration option was added in PolarBlog V1.2.0.
USE_PINGER  top TRUE
  This boolean setting enables/disables sending a ping notification to Ping-O-Matic! when you add or update an entry.  This configuration option was added in PolarBlog V1.2.0.
DEFAULT_DISPLAY_CNT  top 5
  This sets the number of entries to display on each mail display page.
DEFAULT_RECENT_CNT  top 10
DEFAULT_ARCHIVE_CNT  top 100
  This sets the number of entries to display on the index/archive page.  This configuration option was changed in PolarBlog V1.2.0 from 20 to 100.
DATE_SEPARATOR_FORMAT  top h:ia T, j M Y
  This option was deprecated in PolarBlog V1.3.0.  This option has been replaced by I18N_DATE_SEPARATOR_FORMAT.This enables and sets the date format for the entry date separator bar.  If you don't want the date separator bar, comment out this setting.  For information on the available date format option, please see the PHP date function.
DATE_FORMAT  top h:iA T, j M Y
  This option was deprecated in PolarBlog V1.3.0.  This option has been replaced by I18N_DATE_FORMAT.This sets the date format for each PolarBlog entry.  For information on the available date format options, please see the PHP date function.
TIME_ADJUST  top 0 * 3600
  This value will offset entry and update times by this amount of time in seconds.  The default is "zero times 3600 seconds", or none.  If you change the zero to an integer value it will offset all entries by this many hours.  (e.g. 1 = 1 hour, -2 = -2 hours)  The "times 3600" multiplier makes this value an hour setting (3600 second = 1 hour).  Removing this will change the offset to seconds.  For most installations you should not need to change this setting.
USE_POST_BY  top TRUE
  This boolean setting enables/disables the "Posted by" line in the entry header.
USE_LOGIN_LINK  top FALSE
  This boolean setting enables/disables the "Administration" menu when you are not logged in.  By default, to login you must append "?login=1" to the URL.  By enabling this option the Adminstration menu is always displayed and a "Login" link is provided when you are not logged in to PolarBlog.  This configuration option was added in PolarBlog V1.0.1.
BOOLEAN_SEARCH  top FALSE
  This boolean setting enables/disables MySQL boolean full-text search mode.  This option will allow boolean searches to be performed in PolarBlog.  You must have MySQL V4.01 or greater to use this option.  Please see this MySQL manual entry for information on how this works.  If you have an older version of MySQL or simply do not want to allow boolean searching, please see this MySQL manual entry for information on standard full-text searching.  This configuration option was added in PolarBlog V1.1.0.
USE_GOOGLE_LINK  top TRUE
  This boolean setting enables/disables the link to Google search for the entry topic in the entry footer.  This configuration option was added in PolarBlog V1.3.0.
USE_WORD_COUNT  top TRUE
  This boolean setting enables/disables the word count display in the entry footer.  This configuration option was added in PolarBlog V1.3.0.
DOCTYPE  top XHTML Strict
  This defines the doctype to use with PolarBlog.  You can specify either 'HTML Strict', 'HTML Transitional', 'XHTML Strict' or 'XHTML Transitional' as the DOCTYPE value.  If you enter an invalid value, PolarBlog will automatically default to 'XHTML Strict'.  More information on DTD's may be found on this W3C page.  This configuration option was added in PolarBlog V1.0.1.
CSS  top standard.css
  This defines the CSS to use with PolarBlog.  PolarBlog includes two stylesheets in the distribution: standard.css.dist and left_nav.css.dist.  You can use one of these or create your own based on one of these style sheets.  The standard CSS displays your entries in the content pane on the left and blog controls on the right.  The left_nav CSS shrinks and shift the content pane to the right and provides a left panel where you can insert your own custom navigation.  Please see the Enabling Left Navigation appendix for more information on using the left side navigation.
USE_NAV  top FALSE
  This boolean setting enables/disables the displaying of the left navigation panel.  Please see the Enabling Left Navigation appendix for more information on using the left side navigation.
NAV_FILE  top nav.html
  This is the name of a HTML or PHP file to use for the left navigation panel.  The USE_NAV option must be enabled for this option to be utilized.  Please see the Enabling Left Navigation appendix for more information on using the left side navigation.
PAGE_TITLE  top PolarBlog
  The page title element that appears at the top of the browser.  This configuration option was added in PolarBlog V1.0.2.
TOP_HEADER  top <h1>Top Header</h1>
  The header text/HTML that appears at the top of every page.  If you don't want this header to display, simply comment out this definition.
SUB_HEADER  top Sub Header
  The header text/HTML that appears at the top of the main/entry content pane.
BLOG_TAGLINE  top Tagline message...
  A brief tagline (blog description) of text that appears just below the SUB_HEADER in the main/entry content pane.  If you don't want this header to display, simply comment out this definition.  If you don't want this header to display, simply comment out this definition.
ENTRY_LINK  top >>> Recent Entries
  The link text in the control panel to return to the recent entries when the entry index is currently displayed.  See also ARCHIVE_LINK.
ARCHIVE_LINK  top >>> Entry Index
  The link text in the control panel to display your entry index (archive) of previous entries when displaying your recent entries.  See also ENTRY_LINK.
USE_TOPIC_LINKS  top TRUE
  Enable the displaying of blog topic links in the right control panel.  This configuration option was added in PolarBlog V1.4.0.
PREV_ICON  top BASE_URL/gfx/prev_star.gif
  The path to the previous page navigation icon.
PREV_TEXT  top TRUE
  Enables/Disables the "Previous" text that appears to the right of the PREV_ICON.
NEXT_ICON  top BASE_URL/gfx/next_star.gif
  The path to the next page navigation icon.
NEXT_TEXT  top TRUE
  Enables/Disables the "Next" text that appears to the left of the NEXT_ICON.
EDIT_BODY_ROWS  top 15
  The number of rows in the entry editor's entry "body" text area.
EDIT_MORE_ROWS  top 15
  The number of rows in the entry editor's entry "more" text area.
EDIT_COLS  top 85
  The number of columns in the entry editor's entry "body" and "more" text areas.
DISPLAY_ENTRY_DEFAULT  top TRUE
  This boolean option allows you to control whether the "Display Entry" checkbox is checked or unchecked by default when adding a new entry.  This configuration option was added in PolarBlog V1.1.0.
PREVIEW_WIDTH  top 910
  This controls the width of the popup window when previewing an entry.  A value of 745 is recommended if you are using the left navigation style sheet.  This configuration option was added in PolarBlog V1.2.0.
PREVIEW_HEIGHT  top 600
  This controls the height of the popup window when previewing an entry.  This configuration option was added in PolarBlog V1.2.0.
TOPIC_ICON_WIDTH  top 32
  This controls the width of the topic icon in an entry.  If this value is undefined (commented out), the icon will display in its native width.  This configuration option was added in PolarBlog V1.4.0.
TOPIC_ICON_HEIGHT  top 32
  This controls the height of the topic icon in an entry.  If this value is undefined (commented out), the icon will display in its native height.  This configuration option was added in PolarBlog V1.4.0.
USE_TIMER  top FALSE
  This enables/disables the timing of entry and calendar generation and outputs HTML comments with its results.  This is a performance debugging option and should not be left enabled all of the time as its usage slightly degrades the performance of PolarBlog.  This configuration option was added in PolarBlog V1.7.0.

Comments Configuration  top

PolarBlog provides an optional fully nested commenting system to allow your readers to provide feedback on your posts.  Below are the configuration directives that allow you to enable and configure the commenting system in PolarBlog.  This commenting system was added in PolarBlog V1.1.0.

Configuration Option Default Value
USE_COMMENTS  top TRUE
  Enables/Disables the commenting system.
COMMENT_ROWS  top 75
  The number of columns in the comment editor's text area.
COMMENT_COLS  top 15
  The number of rows in the comment editor's text area.
COMMENT_DATE_FORMAT  top %l:%i%p %e, %b %Y
  This sets the date format for each PolarBlog comment entry.  For information on the available date format options, please see the MySQL date and time functions.
COMMENT_INDENT  top 30
  The number of pixels to indent comments.  This is the number of pixels from the left margin, not from the entries left margin.  The left margin for entries is 20 (210 for left_nav) by default (in the CSS).  So the default of 30 will indent comments 10 pixels from the entries left margin. (30 - 20 = 10).  If you are using the left_nav CSS a value of 210 will achive the same effect.
COMMENT_INDENT_INCREMENT  top 10
  The number of additional pixels to indent comment replies.  All first level replies to a comment will be indented by this value.  All subsequent replies to replies will be indented by this many more pixels.  This creates the nesting of comments to help readers follow a conversation thread.  See this entry for an example of this in action.
COMMENT_TAGS  top <em><i><b><strong><br><code><pre><ol><ul><li>
  HTML tags to allow in comments.  HTML (or their XHTML equivalent) tags not listed here will automatically be stripped from user comments.  This allows users to add some stylizing to their posts, but prevents them from inserting potentially evil and dangerous tags such as <script>.  You are advised to use extreme caution if you add additional tags to this option.
COMMENT_MAIL  top FALSE
  Enables/Disables the sending of email notification on comments and comment replies.  You should configure and test the Mailer Configuration before leaving this enabled permanently.
COMMENT_BLOCK_FILE  top NULL
  A fully qualified file path to a file containing IP addresses and/or IP masks of IP addresses that should be blocked from posting comments to you blog.  See the Comment IP Blocking appendix for further information on using this setting.  This configuration option was added in PolarBlog V1.4.0.
POP3 Configuration  top

PolarBlog provides an optional POP3 entry posting system.  Below are the configuration directives that allow you to enable and configure the POP3 posting system in PolarBlog.  More information using this option are covered in the Posting via POP3 Email appendix.  This feature was added in PolarBlog V1.7.0.

Configuration Option Default Value
POP3_MODE  top FALSE
  Enables/Disables the POP3 entry posting feature.  Set to FALSE to disable the feature or set it to the SAPI name you intend to access.  Generally this will probably be "cli" or "apache".  For other options see PHP SAPI Name comment.  More information on what you should set this value to are covered in the Posting via POP3 Email appendix.
POP3_HOST  top NULL
  The POP3 email server hostname to which you want to connect.
POP3_PORT  top 110
  The POP3 email server port to which you want to connect.  Unless you know otherwise, you should use the default provided.
POP3_USER  top NULL
  The POP3 username for the email account you are connecting too.
POP3_PASSWD  top NULL
  The POP3 password for the email account you are connecting too.
POP3_MAIL  top FALSE
  Enables/Disables the sending of email replies on requests for available blog topics.  More information on what you should set this value to are covered in the Posting via POP3 Email appendix.
POP3_TOPIC  top 0
  The default topic ID for entries posted via the POP3 Email interface.  More information on what you should set this value to are covered in the Posting via POP3 Email appendix.
Mailer Configuration  top

PolarBlog offers the ability to send the PolarBlog owner and commentors (that provide an email address) an email message when comments or replies to comments are posted.  Below are the configuration directives that allow you to configure the mailer to provide this option in PolarBlog.  The configuration settings in this section will have no effect unless the COMMENT_MAIL directive above is set to TRUE.  For addtional detailed information on using and configuring the mailing system, please see the PHPMailer homepage.

MAIL_TYPE  top smtp
  The method to use to send email.  Valid values for this setting are 'mail', 'sendmail', or 'smtp'.
MAIL_HOST  top smtp.yourdomain.com
  Sets the SMTP hostname.  If your SMTP server is the same as your hostname, you can safely comment out this setting.  If you are unsure, try commenting it out first and then enabling and configuring it if necessary.
MAIL_FROM  top you@yourdomain.com
  The email address that notifications should use for the email "From" value.
MAIL_FROM_NAME  top Your Name
  The real person name that notifications should use for the email "From" value.
MAIL_BCC_REPLY  top TRUE
  If enabled, a notification email will be blind copied to the MAIL_FROM (MAIL_FROM_NAME) on all comment replies.  This allows you, the blog owner to be made of aware of replies to others comments on in your blog.  If the comment that is being replied to does not have an email address and this option is enabled, the message will be sent to you instead of blind copying it.
MAIL_DEBUG  top FALSE
  If enabled this will display all error that occur while attempting to send an email notification.  You should only enable this setting if you are attempting to debug mailer problems as it will display this debug information on your blog.
Controls Configuration  top

PolarBlog offers the ability to provide text and tag icon links to external sites.  Below are instructions on how you can enable these in PolarBlog.  The content that is displayed is contained in a configuration array (Very originally named "$config"!).  Instruction on how to add/edit this array is discussed below the configuration definitions.

Configuration Option Default Value
USE_TAG_GROUPS  top TRUE
  Enables/Disables the use of tag icons for links to other sites, "Powered by", validation services and RSS syndication of the blog.  See the configuration array below.
USE_OTHER_BLOGS  top TRUE
  Enables/Disables the use of tag icons for links to other blogs.  See the configuration array below.
OTHER_BLOGS_TITLE  top Other Blogs
  The header text in the control panel for the link listing of other blogs.  See also USE_OTHER_BLOGS and the configuration array below.

The $config Array

The configuration array is a multi-dimensional array that uses the first key value to define a particular section.  The sections of the configuration array are tags, blogs and rss.  Each section is structured slightly differently and is discussed below.

tags:  The tags configuration ($config['tags']) section can contain as many sub-levels groups within it as you desire.  The first sub-level ($config['tags'][0], $config['tags'][1], etc.) is a grouping option.  When displayed, each group will be displayed sequentially in numeric order and separated by a horizontal rule (<br />).  The second sub-level ($config['tags'][0][0], $config['tags'][0][1], etc.) contains an array of each display item.  Each of these item arrays consists of three elements: url, title and image ($config['tags'][0][0]['url'], $config['tags'][0][0]['title'], $config['tags'][0][0]['image']).  The url is, well the URL to the external resource!  The title is what is displayed when a user hovers over the linked tag image.  And the image is just that, the image tag that is displayed in the control panel for the item.  By default this section contains tags that link to PolarBlog, your blog's RSS feed and CSS, HTML and RSS validation services.

blogs:  The blogs configuration ($config['blogs']) section can contain as many sub-levels items within it as you desire.  Each of these item are an arrays ($config['blogs'][0], $config['blogs'][1], etc.) that consists of three elements: url, title and desc ($config['tags'][0][0]['url'], $config['tags'][0][0]['title'], $config['tags'][0][0]['desc']).  The url is, well the URL to the blog you are referencing!  The title is what is displayed in the control panel.  The desc is a brief description of the blog's content. (i.e. the tagline.)  When a user hovers over a one of displayed title, the title and description are displayed.

rss:  The rss configuration ($config['rss']) section contains three sub-levels; required, optional and feed settings ($config['rss']['required'], $config['rss']['optional'], $config['rss']['feed']), and configures your RSS syndication (XML) file.  The default configurations settings for required are:

You should change the title and description as necessary.  For most installations you should not need to change the link setting.

The default configurations settings for optional are:

You should set each of these as appropriate for your installation.  You should not change docs, but you can delete it.  In the copyright setting, "::YEAR::" is a token value that will replace be replaced by PolarBlog with the current year when an RSS file is generated.  You can learn way more than you will probably ever want to know about these and other RSS settings by reading the RSS Specification.

The other feed configurations settings are:

If you are changing this setting you may need to also change the I18N_LANG and I18N_CHARSET settings.


Optional Configuration  top

PolarBlog offers the ability to utilize some external applications to enhance its functionality.  Below are configuration setting that will allow you to utilize them with PolarBlog once they are installed.

Configuration Option Default Value
USE_SMARTYPANTS  top FALSE
  Enables/Disables the use of SmartyPants-PHP.  SmartyPants-PHP is a function library that translates plain ASCII punctuation characters into "smart" typographic punctuation HTML entities. Please see the SmartyPants-PHP site for more information on using this optional feature.
SMARTYPANTS_LIB_PATH  top LIB_PATH/smartypants-php/
  The library path to SmartyPants-PHP.  Please see the SmartyPants-PHP site for more information on using this optional feature.
USE_SPELLER  top FALSE
  Enables/Disables the use of Speller Pages.  Speller Pages is a JavaScript library that acts as a web based front-end to GNU Aspell to provide spell checking of PolarBlog entries. Please see the Speller Pages and GNU Aspell sites for more information on using this optional feature.
SPELLER_PATH  top /speller/
  The path to Speller Pages.  Please see the Speller Pages site for more information on using this optional feature.
USE_GIGGLE  top FALSE
  Enables/Disables the use of phpGiggle.  phpGiggle provides automatic linking of key words and phrases in PolarBlog entries. Please see the phpGiggle site for more information on using this optional feature.
GIGGLE_LIB_PATH  top /speller/
  The library path to phpGiggle.  Please see the phpGiggle site for more information on using this optional feature

PolarBlog Main Display  top

The PolarBlog Main Display is the default page that is displayed when the blog page is visited.  There are a number of sections to this page as described below.



Entries  top

The entries in the blog are displayed in the main panel and if enabled, there will be a date separator between daily entries (see DATE_SEPARATOR_FORMAT).  Additionally, each entry has a number of features:


Control Panel  top

The PolarBlog Control Panel contains the following elements...



Administration  top

Login  top

To login to your PolarBlog you need to append "?login=1" to the URL.  This will then display a login form where you can submit your Username and Password.  If your login authentication fails, you will simply be returned to the login screen, this time with your username already filled in.  Once you successfuly login, you will see an Administration menu in the control panel.

Administration Menu  top

The Administration menu contains of the following options:


Add Entry  top

Adding entries to PolarBlog is as easy as completing the Add Entry form and submitting it.  This form consists of:


Edit Topics  top

To add or edit a topic in PolarBlog, click on Edit Topics in the Adminstration Menu to display the initial topics screen:

Once you choose to add or edit a topic, you are then presented with the Topic add/edit screen:


Edit Users  top

To add or edit a user in PolarBlog, click on Edit Users in the Adminstration Menu to display the initial users screen:

Once you choose to add or edit a user, you are then presented with the User add/edit screen:


Logout  top

This option will immediately log you out of your current PolarBlog session.


A. Acknowledgments  top

PolarBlog would not exist if not for the contributions and support of a number of people and their work.

B. Personal Weblog Compatibility  top

PolarBlog provides a migration path for most current Personal Weblog users.  That being, users that are utilizing the most common installation configuration.  These parameters are:

In order to provide entry linking compatibility with PWL, the following PWL variables are automatically remapped in PolarBlog.  This allow links that had previously been created to existing PWL entry to seamlessly be remapped to their PolarBlog equivalent.

An attempt has been made to provide a reasonable amount of compatibility with PWL during the migration phase.  After installing PolarBlog and performing the database migration, your PWL installation should still continue to function on the public side.  If you desire to add entries during this transitional phase you are advised to do so via PolarBlog.  This is because the entry creation process is not compatible between the two systems.  As such, you are advised to backup your PWL database tables before beginning the migration process should you decide to return to PWL and not use PolarBlog.

C. Enabling Left Navigation  top

This section outlines how to enable the left navigation option in PolarBlog.

  1. Copy the css/left_nav.css.dist file to css/left_nav.css.
  2. Create an HTML or PHP file to contain your navigation menu. (ex. nav.html, nav.php)  This file can be located anywhere, but it is recommended that you put it in your PolarBlog root directory.  This file should be edited to provide your required navigation links as necessary.
  3. Change your CSS configuration directive to "left_nav.css"
  4. Change your USE_NAV configuration directive to "TRUE".
  5. Change your NAV_FILE configuration directive to the name of the file you created above.  If the file is in a location other than the PolarBlog root directory, you must set this to its fully qualified path.
  6. Edit and adjust your navigation file as necessary.
D. Comment IP Blocking  top

This section outlines how to use the comment IP blocking option in PolarBlog.

  1. Create a text file to contain IP addresses you would like to block.  This file can be located anywhere, but it is recommended that you put it outside your web directory.
  2. Set the COMMENT_BLOCK_FILE configuration directive to the fully qualified file path of the file you just created.  (e.g. /home/my_dir/ip_block.lst)
  3. Edit your IP block file to contain complete IP addresses (e.g. 192.100.50.10) or an IP masks (e.g. 192.100.50.*, 192.100.*, 192.*) of IP addresses or address blocks you would like to prevent from commenting on your blog entries.
  4. Any IP address that is listed in the block file, or matches an IP mask will be prevented from posting comments to your blog.  Additionally, if someone visits your site from one of these address, the "Add Comment  link will not be displayed.
E. Entry & Comment Auto-Linking  top

This section outlines how to use the entry & comment auto-linking option in PolarBlog.

F. Posting via POP3 Email  top

This section outlines how to configure and use the posting via POP3 email option in PolarBlog.

Enabling the Feature
As of V1.7.0, PolarBlog provides the ability to post entries via email from multiple email accounts.  In order to use this feature, you must set the values in the POP3 Configuration section appropriately.  The first item, POP3_MODE by default disables the feature.  In order to use this feature you need to first determine if you have the command line interface (CLI) on your system.  From the command prompt on your webserver, enter "php -v".  If you get a "command not found" message, you either don't have the CLI version of PHP or it is not with your search path.  You should see something similar to this:

PHP 4.3.11 (cli) (built: Sep 13 2005 15:06:40) Copyright (c) 1997-2004 The PHP Group Zend Engine v1.3.0, Copyright (c) 1998-2004 Zend Technologies with Turck MMCache v2.4.6, Copyright (c) 2002-2003 TurckSoft, St. Petersburg, by Dmitry Stogov with Zend Extension Manager v1.0.4, Copyright (c) 2003-2004, by Zend Technologies with Zend Debugger v3.5.2, Copyright (c) 1999-2004, by Zend Technologies

Note the "cli" in parenthesis following the version number…this is the Server API (SAPI) value and what you should use for the POP3_MODE value if you would like to enable this option.  I you don't have the CLI version of PHP, you may still be able to use this feature.  Create a small test script on your webserver and run it to find your SAPI value:

	<?php
	  echo 'Your PHP SAPI value is "' . php_sapi_name() . '".';
	?>

If you are running mod_php on an Apache web server, this value is likely to be "apache".  If your are using CGI PHP, this string will be "cgi".  If you are having problems or running a different server, the above test script should help you find the appropriate value.  Also, you may want to consult the php_sapi_name() manual page and this comment.

Once you have set the POP3_MODE, you then should set the POP3_HOST, POP3_PORT (if necessary), POP3_USER and POP3_PASSWD values.  This is basically the same as you would setup a POP3 mail client that you want to retrieve mail from.  A dedicated POP3_USER mailbox is required to use this feature.

If you would like to have the ability for users to retrieve a list of topics and their ID values via email, then you should enable the POP3_MAIL option.  You must also have setup the Mailer Configuration to use this option.  The POP3_TOPIC value should also be set to the default topic ID you would like entries to be posted to if a topic ID is not provided.  Generally this would be the topic ID to which you most often post.  (More on this below.)

Configuring Users
In addition to enabling the use of this feature, you must also configure each individual users that you would like to allow to use this feature.  There are two new user settings releated to this feature.  The first is the "Allow POP3 Posts?" option which is off by default.  To allow a user to post via their "Email" address you must enable this option.  The second option you may need to edit is the "POP3 Email(s)" setting.  This is a comma delimited list of other valid (secondary) email addresses from which this may post to PolarBlog.  This is primarily to allow a user to post from multiple email addresses and/or a mobile device.  See the Edit Users section for more information on configuring users.

Emailing a Blog Post
To post to the blog, you send an email from one of the valid accounts as specified in your user setup.  The subject of the email will become the Title of your post.  The body of your message then becomes the contents of your post.  There are two optional keyword tokens in the PolarBlog POP3 email interface that have special meaning and will be parsed and removed from your posting.  They are "TOPIC:" which is followed by an integer number representing the topic ID under which you want this post to appear.  If you omit this token, your post will be made under the default POP3_TOPIC ID.  The other token is "::MORE::".  Any text entered after this token will make up the "Read more…" section of your posting.  If you omit this token, your entire message will appear in the body of your post.  Your posting will be time stamped with the current time when it is automatically posted.  The following is a simple example of an email message to be posted to your blog:

	From:    John Doe 
	To:      POP3_USER@your-domain.com
	Subject: This is the Title of your post!

	 TOPIC:2
	 This is a simple test message.
	 ::MORE::
	 This is the more section.

Retrieving Topics via Email
If you have enabled the POP3_MAIL option, you can retrieve a list of topics from your PolarBlog installation by sending an email from a valid user account.  This email should simply contain the EXACT subject "GET TOPICS".  The body of the message may be empty as it is not utilized for this feature.  You will then be emailed back a message with a subject of "BLOG_NAME Topics" and the body will contain a list of topics and their ID's:

	 Id    Topics
	 ------------
	  0    General
	  1    Web Site
	  2    Sports
	 10    Entertainment

To specify that your message is posted under a specific topic, you use the "TOPIC:" keyword token.  For example, to post your message to the "Entertainment" (ID 10) topic instead of the default "General" (ID 0 as specified in the POP3_TOPIC configuration setting) topic, you would put "TOPIC:10" in your message body.

Automated Email Posting Pickup
In order for your email message to be posted to PolarBlog, you have to setup a scheduler to access and process your mailbox.  Typically this would mean enabling a cron job on a Unix/Linux system.  If you have setup the POP3_MODE as "cli", the following example would check and post any messages at the top of every hour:

	0 * * * * php -f /path/to/polarblog/pop3_post.php

If you are using any other POP3_MODE setting you will need to use the "wget" command (or similar) to process your email posts.  So this same example crontab entry using wget would look like:

	0 * * * * wget -q -O/dev/null http://www.your-domain.com/path/to/blog/pop3_post.php

All email in the POP3_USER mailbox will be processed when this job runs.  Any email from a valid user email (see above) that is not a request for a list of topic ID's will result in a post to your blog.  Any mail not from a valid user email address (i.e. SPAM) will automatically be rejected and deleted.  After a valid post or topic list request, those emails will also be deleted.

PolarBlog is copyright 2004-2005 Kevin L. Papendick.  Portions of the database schema are copyright 2002 Mark Pulford.  Other sub-components packaged with PolarBlog are copyrighted by their respective owners.