Including Viewer Remarks in Generated Albums

Items on this page

• Introduction
• Sample album with Viewer Remarks enabled
• Requirements
• Quick start guide
• Creating a MySQL/PostreSQL database
• Setting up the Viewer Remarks Feature
• Administration Console
• International Language Support
• Customizing the Date and Time Format
• Security
• Troubleshooting

Introduction

When the Viewer Remarks feature is enabled, viewers of generated albums can post remarks about album images. These remarks can be viewed by all who view the album. Remarks appear in the lower part of the page just above the horizontal shadow bar. The Remarks pane can be set to open:

• only when the words “[Hide/Show]” are clicked
• always
• only when a Viewer Remark is present

Viewer Remarks can be enabled for slide image pages, index pages, or both.

The Viewer Remarks feature has an Administration Console that permits those with the assigned adminstrative password the right to edit or delete a single remark and delete all remarks for a given image.

Two security features can be enabled to help thwart “forum spam”:

• CAPTCHA security image (requiring the end user to type a random generated code visible against a dark background)
• moderation (requiring the administrator to approve a remark before the remark is visible to users

Viewers may embed <b></b> or <strong></strong> tags to create bold text and may embed <em></em> or <i></i> tags to create italicized text. All other html tags are stripped from messages, for security reasons.

Sample Album with Viewer Remarks enabled

There is a sample album with a working example of the Viewer Remarks feature. Please feel free to add, edit, or delete comments. To enter administrative mode, use ‘admin’ for the username and ‘1111’ for the password.

Requirements

The web server on which the album is located must support the programming language PHP and either the MySQL or PostgreSQL database program. Users who run their own web servers should know this. Most users use an external web host; check the web host’s control panel or ask the host’s technical support to see if these requirements are met (most web hosts provide this functionality).

Quick Start Guide

The follow steps must be taken to create an album with the Viewer Remarks feature:

1. Create a MySQL or PostgreSQL database on the web server (1 time only)
2. Set up the Viewer Remarks Feature on the BPP-Viewer Remarks tab
3. Generate an album (note that one cannot see Viewer Remarks locally by using the “View Album” button on the JAlbum “Generating album” window)
4. Upload the album to the web server

Note: When generating an album with the Viewer Remarks feature, the page extension must be set to .php on the JAlbum Advanced-Naming tab and ‘Write UTF-8’ must be set on the JAlbum Advanced-General tab. BPP will not generate the album unless this is done.

Creating a MySQL or PostgreSQL database

Users running their own webservers should consult the appropriate documentation to figure out how to create a MySQL/PostgreSQL database on their server.

Users with an external web host will most likely use their web host’s control panel to create a MySQL/PostgreSQL database. If needed, consult the web host’s documentation or the host’s technical support. There are typically three steps that need to be taken:

1. Create the MySQL/PostgreSQL database, specifying a database name
2. Create a MySQL/PostgreSQL username with associated password
3. Add the username created in step 2 to the list of authorized users for the database set up in step 1 (this step is automatic with some web host control panels)

Important: three pieces of information are needed from the MySQL/PostgreSQL database creation process: the MySQL/PostgreSQL database name, the database username, and the username password. Write these down (and keep the information for future reference)! Typically, there is no way to recover a database user password via a web host’s control panel. At many webhosts, the database name and database username will in the form hostusername_dbname and hostusername_dbusername, where hostusername is the username used to access the webhost’s control panel.

Create the MySQL/PostgreSQL database before an album using the Viewer Remarks feature is generated. (Note: to avoid difficulty with some web servers, lower case should be used for the database name, username, and password.)

A single MySQL/PostgreSQL database can be used to hold Viewer Remarks for multiple BluPlusPlus albums. Each album should have its own unique table name.

Flash videos showing how to set up a MySQL database in three of the more popluar web host control panels are available via the links below:

• cPanel
• Plesk
• ensim

Note: The appearance of the control panels at a particular webhost may differ from the appearance of those shown in the videos, but the functionality should be similar.

Setting up the Viewer Remark Feature

The Viewer Remarks feature is enabled and set up on the BluPlusPlus Viewer Remarks tab. The following fields must be completed (to avoid difficulty with some web servers, lower case should be used for all fields):

Server-based info (once set up, this will not change from album to album)

• Database type—choose either MySQL or PostgreSQL
• Database URL—under most circumstances, the default value (“localhost:3306” for MySQL/“localhost:5432” for PostgreSQL) can be used; if the webhost specifies a different location for the MySQL/PostgreSQL database, enter it here
• Database User Name—the database username specified when the MySQL/PostgreSQL database was created
• Database Name—the database name specified when the MySQL/PostgreSQL database was created
• Database password—the database password specified when the MySQL/PostgreSQL database was created

Album-based info (can change from album to album)

• Table name—the desired database table name
  Note: Though not required, it is recommended that each album have a unique table name. That way, if an album is taken down from the server it is possible to delete all the viewer remarks for a given album without affecting the remarks for other albums
• Admin Username—the desired username used to enter Admin mode
• Admin Password—the desired password used to enter Admin mode
• Date Format—the format (in standard PHP format--see below) desired for the posting date for remarks
• Date Suffix—any suffix (e.g. “ EST” for Eastern Standard Time) to be appended after the remark timestamp
• CAPTCHA checkbox—if desired, check this box to enable CAPTCHA security images
• Moderation checkbox—if desired, check this box to require that remarks by approved by an administrator before being visible to users
• ‘To’ E-mail—if the optional ‘Notify via E-mail’ is enabled, the address to which remark notifications should be sent
• ‘From’ E-mail—if the optional ‘Notify via E-mail’ is enabled, the address from which remark notifications will sent

Note that some webhosts, for security reasons, only allow auto-generated emails to be sent to the same domain as the domain of the hosted website (for example, if the website is at domain ‘yourdomain.com’ notification emails could be restricted to go only to ‘someaddress@yourdomain.com’; ‘someaddress@aol.com’ may not function correctly). If notification emails sent to an external address do not arrive, this may be the reason.

Some users may not find this convenient, as it may be desirable to send notification emails to an email address NOT at the website domain. As most webhosts offer email support and offer email forwarding support, a workaround would be to create an email address at the website domain and setup forwarding from that address to an external address.

Administraton Console

To access the Administration Console, type ‘admin’ in the Name field and the admin password set up when the album was generated in the Message field.

With the Administration Console, a remark may be deleted, edited, or approved (if Moderation is enabled); all remarks for a given image can also be deleted in admin mode. Via the ‘Remarks to display’ drop-down menu, one can choose “All remarks for page”, “All remarks in album”, “Unapproved remarks for page”, or “All unapproved remarks for album”. Note: if Moderation is not enabled, the two drop-down menu entries referring to unapproved remarks and the checkboxes for approving remarks will not appear.

International Language Support

In order to enable full support for remarks left in international languages with non-Western character sets, the “Encoding” drop down menu on the JAlbum Advanced-General tab must be changed to “UTF-8”. If the album contains folders and/or images named using international languages with non-Western character sets, the “URL-encode links” box should be checked on the JAlbum Advanced-Naming tab (this second requirement is not specific to the Remarks feature but is necessary for JAlbum to handle non-Western file/folder names).

Customizing the Date and Time format

The date display format defaults to the US standard: month.day.year. The time display format defaults to Hours:Minutes (in 24 hour time).

The default date/time format string is “m.d.Y H:i”. The periods between the format characters indicates that periods are to be used as separators. If slashes were used instead of periods, a date would be displayed as “month/day/year”. To change to “day/month/year” format use “d.m.Y H:i”.

Note that the time shown is the server’s time, not the local time of the person viewing the album.

A few examples of date/time display formats should give an idea of some of the possibilities:

The following (complicated) table gives all possible format characters for date and time display:

Security

The parameters needed to make the Viewer Remarks feature work (MySQL/PostgreSQL database name, database username, database user password, admin login, and admin password) are all stored in plain text in a file that can be opened on a local computer. However, they are not accessible when pages are viewed from a web server. Even attempting to load the connection script file directly will only result in seeing a blank page. While there are no guarantees, security for viewer remarks should be quite good.

Troubleshooting

The most common problem that occurs is that the generated album cannot connect to the MySQL/PostgreSQL database. The indication of this is that either when a slide image page loads or when one clicks “Show/Hide” to toggle the Viewer Remarks, only a vaguely worded error message appears. The usual cause of this is either (a) incorrectly setting up the MySQL database, database user, or user password, or (b) entering this information incorrectly in the BPP-Viewer Remarks tab. The following are some possible error messages and their causes:

• Unknown Database ‘xxx_yyy’—The database name specified does not exist or the database name was not entered correctly in the BPP-Viewer Remarks tab
• Access denied for user: 'xxx_yyy@localhost' (Using password: YES)—One of following is usually the issue:
  • The username specified does not exist (it was never set up)
  • The username specified exists but was not entered correctly in the BPP-Viewer Remarks tab
  • The password entered on the BPP-Viewer Remarks tab does not match the password created when the username was set up
  • The username and password were correctly setup and entered on the BPP-Viewer Remarks tab but the username was not added to the list of authorized users for the database (this must be done in the web host’s control panel)
• Unknown MySQL Server Host 'xxxyyy'—The hostname is incorrect. Check the webhost’s documentation. Many webhost’s control panels will give a PHP “connection string” to help users connect to the database. That “connection string” can be examined to help determine the correct values for the database hostname and the database username. In the example below, one can see that “localhost” is the correct hostname, and “camner_chattest” is the correct username.

  

• Client does not support authentication protocol requested by server; consider upgrading MySQL client—This error occurs when MySQL version 4.1.x or greater is combined with PHP 4.x. MySQL 4.1 implemented a new, more secure method of connecting to a database that is not supported by PHP 4.x. Either downgrading MySQL to version 4.0.x or upgrading PHP to version 5.x will solve the problem. Those with external web hosts may not be able to implement either solution.