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
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.
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.
Note: make sure you use a single (sub)domain, either with or without “www”. Using both will cause problems due to cross-domain ajax-requests. Here’s the .htaccess code to force the correct domain.
Including ThumbsUp in your website
PHP
At the very top of every page you want to use ThumbsUp on, include the following ThumbsUp PHP script. This should come before the doctype or any whitespace.
<?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. If you aren’t already loading jQuery on your page, add this line to <head> of your HTML page to load jQuery from Google:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/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 |
|
|
| mini_poll |
|
|
| mini_thumbs |
|
|
| thumbs_up |
|
|
| thumbs_up_down |
|
|
| up_down |
|
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' => 2149,
'name' => '[quote] scandic',
'closed' => false,
'date' => 1574807614,
'votes_up' => 230,
'votes_down' => 62,
'votes_pct_up' => 78.7671,
'votes_pct_down' => 21.2329,
'votes_balance' => 168,
'votes_total' => 292,
),
1 =>
array (
'id' => 2148,
'name' => '[quote] mozunk',
'closed' => false,
'date' => 1574807614,
'votes_up' => 241,
'votes_down' => 81,
'votes_pct_up' => 74.8447,
'votes_pct_down' => 25.1553,
'votes_balance' => 160,
'votes_total' => 322,
),
2 =>
array (
'id' => 2137,
'name' => '[quote] clarklab',
'closed' => false,
'date' => 1582860428,
'votes_up' => 131,
'votes_down' => 62,
'votes_pct_up' => 67.8756,
'votes_pct_down' => 32.1244,
'votes_balance' => 69,
'votes_total' => 193,
),
)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 scandic.
<?php
if ( ! empty($items)) {
echo 'The most appreciated quote is the one from ',
str_replace('[quote] ', '', $items[0]['name']), '.';
}
?>