Plugin / Gwolle Guestbook

Installation

Installation

• Install the plugin through the admin page “Plugins”.
• Alternatively, unpack and upload the contents of the zipfile to your ‘/wp-content/plugins/’ directory.
• Activate the plugin through the ‘Plugins’ menu in WordPress.
• Place ‘[gwolle_gb]’ in a page. That’s it.

As an alternative for the shortcode, you can use the function show_gwolle_gb(); to show the guestbook in your templates.
It couldn’t be easier.

Updating from an old version

With version 1.0 there have been some changes:

• Gwolle Guestbook uses the Shortcode API now. Make sure your Guestbook page uses ‘[gwolle_gb]’ instead of the old one.
• The entries that are visible to visitors have changed. Make sure to check if you have everything visible that you want and nothing more.
• CSS has changed somewhat. If you have custom CSS, you want to check if it still applies.

License

The plugin itself is released under the GNU General Public License. A copy of this license can be found at the license homepage or
in the gwolle-gb.php file at the top.

Known Issues

On some websites sending the data from the form doesn’t work correctly. Some field data is being sent and some not.
If you are affected by this issue and can debug this to find the real problem, please do so and report it on the support forum.
Disabling AJAX for the form is a good workaround.

Hooks: Actions and Filters

There are many hooks available in this plugin. Documentation is included in the zip file in /docs/actions and /docs/filters. Examples are included. If you have a need for a hook, please request this in the support forum.

Add an entry with PHP code

It is not that hard to add an entry in PHP code.

<?php
    $entry = new gwolle_gb_entry();

    // Set the data in the instance, returns true
    $set_data = $entry->set_data( $args );

    // Save entry, returns the id of the entry
    $save = $entry->save();
?>

The Array $args can have the following key/values:

• id, int with the id, leave empty for a new entry.
• author_name, string with the name of the autor.
• author_id, id with the WordPress user ID of the author.
• author_email, string with the email address of the author.
• author_origin, string with the city of origin of the author.
• author_website, string with the website of the author.
• author_ip, string with the ipaddress of the author.
• author_host, string with the hostname of that ip.
• content, string with content of the message.
• datetime, timestamp of the entry.
• ischecked, bool if it is checked by a moderator.
• checkedby, int with the WordPress ID of that moderator.
• istrash, bool if it is in trash or not.
• isspam, bool if it is spam or not.
• admin_reply, string with content of the admin reply message.
• admin_reply_uid, id with the WordPress user ID of the author of the admin_reply.
• book_id, int with the Book ID of that entry, default is 1.

Format for importing through CSV-file

The importer expects a certain format of the CSV-file. If you need to import from a custom solution, your CSV needs to conform.
The header needs to look like this:

<?php
array(
    'id',
    'author_name',
    'author_email',
    'author_origin',
    'author_website',
    'author_ip',
    'author_host',
    'content',
    'datetime',
    'isspam',
    'ischecked',
    'istrash',
    'admin_reply',
    'book_id',
    'meta_fields'
)
?>

The next lines are made up of the content.

There are some gotchas:

• Date needs to be a UNIX timestamp. For manually creating a timestamp, look at the timestamp generator. When using a formatted date, the plugin will try to read it correctly. If it fails it will use today’s date.
• Use commas for field separators. If you use Office software like Excel (which is hell) or LibreOffice Calc, set this correctly.
• Use double quotes around each field. When no quotes are used the import process can break when having quotes or commas inside the content of the entry.
• The file should be encoded as UTF-8 without BOM to correctly enter special characters.
• Make sure you use UNIX line-endings. Any decent text-editor can transform a textdocument (CSV file) to UNIX line-endings.

With version 1.4.1 and older, the field datetime was called date.

You could make a test-entry, export that, and look to see what the importer expects from the CSV.
There is also an example CSV file included in the zipfile of the plugin under ‘/docs/import_example/’.

If you want to prepare a CSV file from other software, plaese be aware that Microsoft Excel is terrible in dealing with CSV files. You will not manage to create a working CSV file with this. Please use LibreOffice Calc for this.