Sample Install Documentation

Geeklog addon's by Blaine Lang

Aka: efarmboy
Email: geeklog@langfamily.ca
Version: Nov 10, 2002 (Release Date for Chatterblock 3.0 as a plugin)

Chatterblock 3.0

1.0 Overview

This is a true Geeklog plugin using the GL Plugin API calls.

This is a complete re-write from my earlier Chatterblock release but I have provided a migration script to convert existing 2.x Chatterblock tables so no data is lost. Many new features have been added and it is now a plugin to ease installation. No files have to be edited - all online install and configuration. Please take a min to review the list of changes

New features and Changes include:

• Released as a true Geeklog Plugin with Auto-Install and De-Install once files are placed into their appropriate directory
• Create tables, security groups and automatically adds the menu links
• Block definition automatically created - block will appear upon install completing
• Able to delete/remove plugin from GL Plugin Admin screen
• Language file for translation support and easy personalization of the block and plugin interface
• Extensive online configuration control - It can easily be tuned down for basic look and feel
• Created Chatterlog to view all the stored history - includes ability to change the way messages are ordered/sorted using by clicking on the display header Date and User titles
• Site admin can use Chatterlog to archive, edit or delete messages. Includes the ability to select all messages on the page for bulk archive or delete. Site admins can now also see all private messages - organized into a separate view
• Block supports three display modes:
• Static: the original look with a fixed number of posts
• Smooth Scroller: View messages with a scroller to easily display more messages. Number of messages determined by the number of hours of history set.
• iframe - auto refresh mode: Major new feature that allows the block to operate independent and refresh automatically without requiring a main page refresh. Users can set the refresh interval and amount of history to show. Users will see a highlighted message at top of the Message window to indicate number of private messages.
• Site admins can enable user preferences. Then all registered users will have a User Block menu item "Chatterblock Settings" to set their own preferences for Chatterblock mode, amount of history etc ...
• If Site admin later disables user preferences, the site defaults will override any existing user settings
• Support for smilies - both as public and private messages
• Users can enable a pop-up alert when frame mode is used. This way, you can have the site in the background or minimized but it's still refreshing and checking for new messages in the background
• Chatterblock window now uses icons for 1) Message posted time, 2) IP address of user, 3) Send a private message to user. Hovering over the Time and IP icon will show the related details. This method reduces the screen clutter and leaves more room for just the message. Clicking on the PM icon will use Javascript to enter the "/tell username," text into the Message input field.
• Using CSS styles, the messages will use alternating backgrounds to make it easier to separate messages. I now use tables expensively inside the Chatterblock display frame to format the message display
• Users can delete their last post or access the Chatterlog to edit their post. Only active if last stored message is their post.
• Site admin can easily change what gets name displayed for anonymous users - "guest" is the default
• Site admin can enable anonymous users to enter their name so it appears instead of "guest"
• Site admins can disable the display of IP address information. If disabled, it also will not be displayed in the Chatterlog view
• Site admins can disable "Delete last post" feature
• Site admins can disable access to Chatterlog
• Site search will also return the total number of Chatterblock entries on file

2.0 License

This Geeklog Plug-in, like Geeklog is released under the GNU General Public License. It is a bona fide Open Source / Free Software project.

Like all good open source projects, Geeklog and this Plug-in both depend on the community. Thanks for your continued support, and let us know what we can do to make Geeklog and the Plug-in even better.

3.0 New Installation

Note: You need to manually create the plugin program directories and copy the program files into their appropriate directories

Step 0. Database backup

Make a backup of your current geeklog database using the built-in admin feature. Verify your backup feature is configured correctly and backup file is not 0 bytes (This is worth a check)

Step 1. Copy plugin files into their required directories

Uncompress the archive files into your <geeklog_dir>/plugins directory. It will create a chatterblock directory and associated subdirectories for the files. You will need to move the files in the admin and public subdirectories to their appropriate directory as indicated below.

1.1 public_html/ - Main program files

The files in the public directory under your new plugins/chatterblock folder need to be moved to <geeklog_dir>/public_html/chatterblock directory

You will need to first create the:

<geeklog_dir>/public_html/chatterblock directory

1.2 admin/ - Plugin Install and Main admin program files

The three files in the admin directory under your new plugins/chatterblock folder need to be moved to

<geeklog_dir>/public_html/admin/plugins/chatterblock directory.

You will need to first create the:

<geeklog_dir>/public_html/admin/plugins/chatterblock directory

1.3 Directory and File Permissions

Directory and File owner should be same as webserver

All the files and directories should have Read permissions and directories need execute. Setting all plugin files and directories to have read + execute should not be a security issue but PHP files only need read access to execute. The directories need execute rights in order for them to be searched or accessed

The only plugin Directory or File that needs write access is the <geeklog_dir>/public_html/chatterblock/cache directory and the cb_config file. This file contains the block defaults and is written to via the Plugin admin program

Step 2. Run the install program

2.1 Logged in as admin, In your browser, go to http://your_geeklog_url/admin/plugins/chatterblock/install.php

Note: The installer is designed to back out any database changes if there should be an error. You can monitor the installer by viewing the error.log, file <geeklog_dir>/logs/error.log

2.2 Verify successful operation

• Did you get a successful completion message that your database tables have been created
• The Chatterblock should now be active and displayed as the top right block.
• As admin, you should see the "Chatterblock Admin" menu item in the "Admin Block"

Step 3. Set Chatterblock Admin Options

You should now review the Chatterblock defined defaults using the Admin menu link.

The block has many Site Options and User options - be sure to check them all out. You can disable many of the features if you only want the basic functionality

Step 4. Update Template Files

Each of your sites templates or themes will need to have their CSS style definition files updated. The template files are located under the public_html/layout directory. The styles to add are contained in the cb_style.css file

FILE: /path/to/geeklog/plugins/chatterblock/cb_style.css

Customize the fonts and colors to please.

Step 5. Create the staticpage help file

5.2 Copy and paste the HTML code from the included /plugins/chatterblock/helpfile.html file

Given the amount of information, it may be best to set the staticpage to display only with left blocks

Don't check off the "Add to menu" option

Step 6. Final Install Notes

6.1 Modify the alert.html file - to display your site information if you enable pop-up alerts

6.2 The block was automatically created during the install. You may want to edit the Title, location or access rights

6.3 Enter the URL for the Block help file to point to the staticpage created in step 5

6.4 All Block related titles and text is can easily be changed to personalize the block. Refer the the plugin language file

4.0 Upgrade from version 2.1 and 2.2

Completing this process will not delete any existing messages in your Chatterlog database.

1. Ensure you make a backup of your database first. Check the backup file and ensure its > 0 bytes in size.

2. Disable the existing Chatterblock - not delete, just disable it.

3. Remove the Chatterblock table definitions in lib-database.php

4. Remove the Chatterblock related functions in lib-custom.php

function phpblock_Chatterblock() function cb_getnamebyuid($uid) function cb_getuidbyname($name)

5. Install the plugin files as described in this Install step 1 here - but don't execute the plugin install yet

6. Change or modify table names used by the plugin

FILE: /path/to/geeklog/plugins/chatterblock/config.php is where the table names are defined

You can change the plugin to match your table name or modify your table name to match the new default names used by the plugin

Originally there was just one table so I called it chatterblock. Now there are two so I am now recommending a standard naming convention of two letters for the blockname followed by an underscore and the table name. Hence we have:

 $_TABLES['cb_chatterlog'] - Table to store the log of all the user posts

 $_TABLES['cb_userprefs']  - Table to store user preferences.

7. Run the upgrade script to modify the main chatterblock table and create the userprefs table

              FILE: /path/to/geeklog/public_html/admin/plugins/chatterblock/upgrade_v2.php

8. *IMPORTANT* Set the option in the install script to not attempt to create new tables

   FILE: /path/to/geeklog/public_html/admin/plugins/chatterblock/install.php 

$plugin_createtables = false; // Set to true if plugin tables should be created

9. Run the plugin install program and complete the install steps as described from here

10. Now enable your block again and it should now be upgraded with existing data intact.

   All of your chatter history can be seen by accessing the Chatterlog.

Return to index

5.0 List of Plugin Files with Descriptions

Core Plugin Files – The <geeklog_dir>/plugins/chatterblock directory

1. FILE: /path/to/geeklog/plugins/chatterblock/config.php DESCRIPTION: The plugin database configuration file

2. FILE: /path/to/geeklog/plugins/chatterblock/functions.inc DESCRIPTION: Implements the Geeklog Plugin-API functions

3. FILE: /path/to/geeklog/plugins/chatterblock/cb_style.css DESCRIPTION: Plugin CSS styles to be appended to your theme style.css files

4. FILE: /path/to/geeklog/plugins/chatterblock/helpfile.html DESCRIPTION: HTML help file to be used for block help file

5. FILE: /path/to/geeklog/plugins/chatterblock/language/english.php DESCRIPTION: plugin language definitions with the english file provided

6. FILE: /path/to/geeklog/plugins/chatterblock/templates DESCRIPTION: plugin Install/De-Install display template files

Return to index

Plugin Admin Files – The geeklog_dir>/public_html/admin/plugins/chatterblock directory

7. FILE: /path/to/geeklog/public_html/admin/plugins/chatterblock/install.php DESCRIPTION: Chatterblock plugin install and De-Install utility

8. FILE: /path/to/geeklog/public_html/admin/plugins/chatterblock/index.php DESCRIPTION: Main code for the plugin admin functions

9. FILE: /path/to/geeklog/public_html/admin/plugins/chatterblock/upgrade_v2.php DESCRIPTION: Program used only to upgrade database tables from v2.2 to v2.3

Return to index

Plugin Public Files - The <geeklog_dir>/public_html/chatterblock directory

10.FILE: /path/to/geeklog/public_html/chatterblock/cb_main.php DESCRIPTION: Plugin main library file - functions

11.FILE: /path/to/geeklog/public_html/chatterblock/cb_chatlog.php DESCRIPTION: Chatterlog main program

12. FILE: /path/to/geeklog/public_html/chatterblock/cb_userprefs.php DESCRIPTION: Program used to display and modify user settings

13. FILE: /path/to/geeklog/public_html/chatterblock/cb_iframeDisplay.php DESCRIPTION: Program called as the iframe source when this mode is active

14.FILE: /path/to/geeklog/public_html/chatterblock/help.html DESCRIPTION: Chatterblock formatted HTML file to display help file for smilies

15.FILE: /path/to/geeklog/public_html/chatterblock/alert.html DESCRIPTION: Formatted HTML displayed in the alert popup

16.FILE: /path/to/geeklog/public_html/chatterblock/cache/cb_config.php DESCRIPTION: Chatterblock default settings config file

17.FILE: /path/to/geeklog/public_html/chatterblock/images/ DESCRIPTION: Directory contains all required image files

18.FILE: /path/to/geeklog/plugins/chatterblock/includes/cb_function.php DESCRIPTION: Plugin miscellaneous functions

19.FILE: /path/to/geeklog/plugins/chatterblock/includes/cb_redirect.php DESCRIPTION: Plugin function that is included to handle redirect message

20.FILE: /path/to/geeklog/plugins/chatterblock/includes/popupbasic.js DESCRIPTION: Plugin Javascript that includes the chatAlert()function to display the popup

Return to index