Installation

Before you install

Technical skills

Even though ThumbsUp is designed to be easy to install, you should be comfortable with the following operations:

  • Setting up a database
  • Uploading files via FTP
  • Editing PHP and HTML files

System requirements

ThumbsUp 2.x requires a few things in order to work. If in doubt, ask your host.

  • PHP 5+
  • PDO with a driver for your database
  • A database (e.g. MySQL or SQLite)
  • jQuery 1.4 or higher

Setting up the database

Creating the ThumbsUp tables

You can use an existing database or create a new one. ThumbsUp stores everything it needs in two tables: “thumbsup_items” and “thumbsup_votes”. In the database.sql file you'll find the SQL to create these two tables. Here's a screenshot of how to do this via phpMyAdmin.

Note: the table prefix ('thumbsup_' by default) can be changed via the “database_table_prefix” option in config.php.

Configuring the database

To finish off the database part, all that is left to do is to let ThumbsUp know about your database. The config.php file contains a few database related settings you need to edit:

database_dsn The Data Source Name, or DSN, contains the information required to connect to the database. In general, a DSN consists of the PDO driver name, followed by a colon, followed by the PDO driver-specific connection syntax. See the PHP manual for more information.
For example: 'mysql:dbname=yourdatabase;host=localhost'
database_user The database username
database_pass The database password

Uploading ThumbsUp

Use your favorite FTP application to upload the whole “thumbsup” folder to your website.

Next, navigate to this folder with your browser (for example, http://yoursite.com/thumbsup/). You should see a page with a big smiley. Copy the URL from the address bar in your browser to the “url” setting in config.php.

Including ThumbsUp in your website

PHP

At the very top of every page you want to use ThumbsUp on, include the ThumbsUp PHP script:

<?php include './thumbsup/init.php' ?>

Note: ./ is relative to the current directory. You may need to change the path to reflect your current position in the directory structure. You can also use an absolute path, if you know it.

CSS

In the <head> of your HTML page, add the following line of PHP. This will simply create a <link> to the ThumbsUp stylesheet.

<?php echo ThumbsUp::css() ?>

JavaScript

The last ingredient to be loaded is the JavaScript part. Before you load ThumbsUp's JavaScript, you must load jQuery. Add this line to <head> of your HTML page to load jQuery from Google:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>

After that you add the following line of PHP. This will create a link to the ThumbsUp JavaScript file.

<?php echo ThumbsUp::javascript() ?>

Pat yourself on the back, you made it through the installation process! Let's move on, though. The real fun is about to begin still.

Creating ThumbsUp items

The basics

You can create a ThumbsUp item anywhere you want on your page. Do this by adding this bit of PHP code:

<?php echo ThumbsUp::item('item_name') ?>

The item name (in bold) is up to you to choose. Remember that an item name should be unique. Items with the same name point to the same item record in the database.

Choosing a template

By default, when creating an item, the default template (“mini_thumbs”) will be used. You can pick a different default template if you wish. Just change the “default_template” option in config.php.

Picking a different template on the fly is done as follows:

<?php echo ThumbsUp::item('item_name')->template('thumbs_up') ?>

Most templates also have a few options to allow for further customization. In this example, the “align” option is set to “left”:

<?php echo ThumbsUp::item('item_name')->template('thumbs_up')->options('align=left') ?>

To set multiple options at once, merge them using an ampersand:

<?php echo ThumbsUp::item('item_name')->template('thumbs_up')->options('align=left&option2=value2') ?>

Note: for those familiar with PHP arrays, you can also pass on an associative array to the options method, if you prefer. For example: ->options(array('align' => 'left', 'option2' => 'value2')).

List of all templates

Name Demo Options
buttons
16 out of 21 people like this. And you?
  • up: text for the “up” button (default: 'Yes')
  • down: text for the “down” button (default: 'No')
  • question: question displayed after the result (default: 'And you?')
mini_poll
  • up: text for the “up” option (default: 'Yes')
  • down: text for the “down” option (default: 'No')
  • color_up: color for the “up” result graph (default: '#bbb')
  • color_down: color for the “down” result graph (default: '#bbb')
mini_thumbs
+9
  • align: 'left' or 'right' (default: 'left')
thumbs_up
31
  • align: 'left', 'right' or 'center' (default: 'center')
thumbs_up_down
+133 -11
  • align: 'left', 'right' or 'center' (default: 'center')
up_down
+17
  • align: 'left', 'right' or 'center' (default: 'center')

Formatting the results

ThumbsUp allows you to customize how the results for each item are displayed. The “mini_thumbs” template, for example, shows the vote balance by default, e.g. “+12” or “-8”. The “mini_poll” template shows the percentages of up/down votes. Each template has a default format. You can view or edit these formats in config.php.

Here's how to set a custom format for an item:

<?php echo ThumbsUp::item('item_name')->template('mini_thumbs')->format('{+PCT_UP}%') ?>

Format string syntax

A format string is just a short piece of text with some special codes in it. Each code, wrapped in braces, will be replaced with its applicable value. Here's the list of all the available codes:

{UP} The number of up votes
{DOWN} The number of down votes
{PCT_UP} The percentage of votes that is up
{PCT_DOWN} The percentage of votes that is down
{TOTAL} The total number of votes (up + down)
{BALANCE} The vote balance (up - down)

Text that is placed outside of the braces is considered literal text, except for double vertical bars '||' which split up the format string into multiple areas. This is needed for templates like “mini_poll” or “thumbs_up_down”.

Inside the braces you can include a plus or minus sign at the front, e.g. '{+UP}' or '{-DOWN}'. The plus sign will then be prepended to positive values, the minus to negative values. No sign is shown in front of 0-values.

Finally, if you want to show decimals you can do so by appending a dot or comma (depending on where you live) followed by the number of the decimals to display, e.g. '{PCT_UP.1}' or '{PCT_UP,2}'.

Examples

For an item with 10 up votes and 5 down votes, here's what the following format strings would produce:

'{UP}' 10
'{DOWN}' 5
'{+BALANCE}' +5
'{UP} out of {TOTAL} people voted “yes”' 10 out of 15 people voted “yes”
'Percentage of “no” votes: {PCT_DOWN}%' Percentage of “no” votes: 33%
'{-PCT_DOWN}' -33
'{-PCT_DOWN.2}' -33.33
'{-PCT_DOWN,1}%' -33,3%
'Score: {PCT_UP.1}/100' Score: 66.7/100

On the homepage you'll find a few more live examples below each client quote.

Sorting and filtering items

ThumbsUp provides a mechanism to retrieve a list of filtered and sorted items. Let me tell you up front, though, that you'll need some basic PHP knowledge to take advantage of this feature. The idea is simple enough. You basically build a query and ThumbsUp returns an array with the resulting items.

<?php $items = ThumbsUp::items()->get() ?>

The line above will return all items as an array and store them in $items. If no items are found, an empty array is returned.

Sorting items

If you don't specify how to sort the items, they will be ordered by name by default. Use the “orderby” method to customize the sort order. The query below will return all items ordered by the number of total votes from low to high (ascending). You can use any column name to sort on: id, name, closed, date, votes_up, votes_down, votes_pct_up, votes_pct_down, votes_balance and votes_total.

<?php $items = ThumbsUp::items()->orderby('votes_total')->get() ?>

To reverse the sort order add the “desc” keyword after the column name.

<?php $items = ThumbsUp::items()->orderby('votes_total desc')->get() ?>

Finally, if the number of total votes is equal, we want the item with the most up votes to be ordered first. Voilà:

<?php $items = ThumbsUp::items()->orderby('votes_total desc, votes_up desc')->get() ?>

Filtering items

In many cases you wouldn't want to return all ThumbsUp items in the database, but only from a specific group.

Filter on name

By providing ThumbsUp::items with a string, only items with a name that contains that string will be returned.

Tip: you can easily try out a name filter in the admin area to see whether only the desired items pop up.

<?php $items = ThumbsUp::items('[quote]')->get() ?>

Filter on open/closed status

You may want to return only open items:

<?php $items = ThumbsUp::items()->open(TRUE)->get() ?>

Or only closed items:

<?php $items = ThumbsUp::items()->open(FALSE)->get() ?>

Limit the results

If you are only interested in the top 10, you can define this limit and save the database some work.

<?php $items = ThumbsUp::items()->limit(10)->get() ?>

Example

All of the stuff above can be combined to create one specific query. With the query below I am loading the ThumbsUp items for the quotes on the homepage. Closed items are being ignored. The quotes are ordered by the percentage of up votes. I'm only interested in the top three.

<?php $items = ThumbsUp::items('[quote]')->open(TRUE)->orderby('votes_pct_up desc')->limit(3)->get() ?>

This is the contents of $items (generated live):

array (
  0 => 
  array (
    'id' => 1810,
    'name' => '[quote] mozunk',
    'closed' => false,
    'date' => 1396136359,
    'votes_up' => 48,
    'votes_down' => 26,
    'votes_pct_up' => 64.8649,
    'votes_pct_down' => 35.1351,
    'votes_balance' => 22,
    'votes_total' => 74,
  ),
  1 => 
  array (
    'id' => 1809,
    'name' => '[quote] scandic',
    'closed' => false,
    'date' => 1396136359,
    'votes_up' => 41,
    'votes_down' => 30,
    'votes_pct_up' => 57.7465,
    'votes_pct_down' => 42.2535,
    'votes_balance' => 11,
    'votes_total' => 71,
  ),
  2 => 
  array (
    'id' => 1811,
    'name' => '[quote] clarklab',
    'closed' => false,
    'date' => 1396136359,
    'votes_up' => 26,
    'votes_down' => 28,
    'votes_pct_up' => 48.1481,
    'votes_pct_down' => 51.8519,
    'votes_balance' => -2,
    'votes_total' => 54,
  ),
)

It is then up to you or the PHP developer of your website to loop over the returned items and do something useful with it. Here I'm picking the single top quote from the list and outputting the author name in a sentence:

The most appreciated quote is the one from mozunk.

<?php
if ( ! empty($items)) {
	echo 'The most appreciated quote is the one from ',
	     str_replace('[quote] ', '', $items[0]['name']), '.';
}
?>