Contents

1. Licensing
2. Package installation
3. Configuration
4. Web site integration
5. Upgrading from previous versions

Licensing

VoxPopuli is available under freeware license. License text can be found on VoxPopuli license page.

Package installation

To install VoxPopuli on your website, you must do the following:

1. Check the version of MySQL server. VoxPopuli was created and tested on MySQL 5.0.51. While it can probably work on MySQL 4.x, we didn't perform such tests.
2. Ensure that you have access to MySQL server on your web server, and your permissions are sufficient to create the database.
3. Copy files from Code subfolder to the target directory on your server.
4. If this is the first installation of the widget,
   1. execute VoxPopuli.sql script on your web server. The script will create a database and necessary tables and records automatically. Note, that the script drops old tables, so if you are upgrading your version of VoxPopuli, don't run this script.
      From command line the script can be executed as shown:
      mysql -u <user> -p < /path/to/VoxPopuli.sql
      You will be prompted for a password.
      
   2. rename "site_specific_tpl" directory to "site_specific".
5. Perform configuration as described below.

Configuration

Widget configuration is performed via vox-config.php file. To configure the widget, open vox-config.php and

1. specify your username and your password to access the database in VOX_USER and VOX_PASSWORD defines.
2. specify administrator's ID and e-mail address if you want to receive notifications about idea submission by e-mail. Note that specifying e-mail is not enough for e-mail notifications to work: you will also need to edit the rewrites file (see Web site integration below).
3. change different variables, defined and described in the file, to modify default behaviour of the widget.

Web site integration

Before you begin: default design of the widget relies on the browser to show the web page in strict or loose modes. Firefox always uses one of these modes, while Internet Explorer, if none of the modes is specified in the web page header, uses Quirks mode.
If your web page design requires Quirks mode on IE, you need to use vox_ie_quirks.css for IE and vox.css for all other browsers. If your web page design includes a <DOCTYPE> directive that enables strict or loose mode, then you can use vox.css with IE as well as other browsers.

To place the widget to your web page, use the following code snippet:

In the code snippet above, when you just install the widget, put 1 (one) as the category number. VoxPopuli.sql script creates the category named Default with the ID of 1. The value of -1 can be used to specify that ideas from all categories should be listed. Later you can edit category list right in the widget.

language is replaced with "en" for English language (default) or other identifier of the language, for which localization file is available.

In installdir parameter you put the path (absolute path starting from home folder of your web site, without the trailing slash) to the directory where the widget code is stored. It is needed to properly resolve references to image files and to the server-side script itself.
Example: "/vox".

"Open" parameter is the name of the page, which is displayed initially. It can be replaced with "all" or "my" (these names are not localized).

For the widget to work, you need to integrate it with your Content Management System. To do this, you need to implement the functions in site_specific/vox-rewrites.php file as written in comments in this file.

To place the widget in "view-only" mode to your web page, use the following code snippet:

Upgrading from previous versions

If you are upgrading from version 1.0 or 2.0 to version 3.0 or later, be sure to update the database structure by running the SQL script contained in voxpopuli-update-to-2.5.sql file. This will create a log table in the database.