Sample Install Documentation
Geeklog addon's by Blaine Lang
Email: geeklog AT langfamily DOT ca
Version: Nov 10, 2002 (Release Date for Chatterblock 3.0 as a plugin)
This is a true Geeklog plugin using the Geeklog 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 Geeklog 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
- 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
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:
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
You will need to first create the:
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"
2.3 Check the install logging in the <geeklog_dir>/logs/error.log file
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
Customize the fonts and colors to please.
Step 5. Create the staticpage help file
5.1 Create a new staticpage which will be used for the Chatterblock users help
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
5.3 You will use the URL to this staticpage as the URL for the Block helpfile
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
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
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
8. *IMPORTANT* Set the option in the install script to not attempt to create new tables
$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.
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
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
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