Tutorialzine » PHP

An AJAX Click to Appreciate Badge

Martin Angelov — Wed, 28 Jul 2010 17:33:42 +0000

When you publish something online, there are not that many ways to determine whether people like what you have to say. Comments, the cornerstone of blogging, are too demanding, and users often prefer not to post one. If you’ve dropped by Behance, you’ve probably noticed their appreciate badge, which is a neat solution to this exact problem. With it people share their appreciation for somebody’s work.

Today we are implementing such a badge, which you can include in every page of your website with a bit of jQuery magic. So go ahead and download the zip from the button above (PSD included!) and continue with the tutorial.

The Database Schema

The script we are doing today uses two tables. The first holds one record for each of the pages which have the appreciate button enabled. The second one stores the IP of the person that voted along the unique ID of the page. This way we can easily determine whether the person has previously voted for the page and display the appropriate version of the button (active or disabled).

Table Schema appreciate_pages

The hash field holds an MD5 sum of the URL of the page. This way we add an UNIQUE index which will speed up the selects we run on the records, as well ensure there are no duplicate records in the table. The appreciated column holds the number of appreciations of the pages.

Table Schema appreciate_votes

The appreciate_votes table contains the IP of the person that has voted (in the form of an integer), and the id of the page from the appreciate_pages table. The timestamp is automatically updated to the current time when an insert occurs.

You can create these two tables by running the code from tables.sql in the SQL section of phpMyAdmin from the downloadable archive, part of this tutorial.

Step 1 – XHTML

Lets start with the XHTML part of the tutorial. The markup of the page is extremely simple. To have the appreciate button functioning, you just need to provide a container in which the button is inserted, and an optional element, which holds the total number of clicks on the button. You can safely omit the latter one, leaving you with only one div to code.

page.html





An AJAX Click To Appreciate Badge

In the page above, you can see that I am including two stylesheet files. The first is styles.css, which is used to style the page, and appreciate.css, which is located in the plugin directory, and is responsible for the styling of the appreciate button.

Before the closing body tag, you can see that I also include the jQuery library from Google’s CDN repository, the plugin.js file and script.js, which uses the plugin to create the button on the page. You will only need to change the contents of script.js to make the script working on your pages.

Click To Appreciate - looks good on both dark and light backgrounds

Step 2 – PHP

PHP handles the database interactions and is on the backend of the AJAX requests. Most of the script logic is located in c script.php which you can see below. But first lets take a look at connect.php, which handles the database connection.

appreciateMe/connect.php

$db_host = 'localhost';
$db_user = 'YourUsername';
$db_pass = 'YouPassword';
$db_name = 'NameOfDB';

@$mysqli = new mysqli($db_host, $db_user, $db_pass, $db_name);

if (mysqli_connect_errno()) {
	die('Could not connect to the database');
}

$mysqli->set_charset("utf8");

Up until now, we’ve always used the old mysql extension for database connections under PHP, as it is a bit easier to use and I wanted to keep the code compatible with PHP 4. However, with the recent announcement that WordPress (our favorite blogging engine) will be dropping support for that version of PHP, I decided that it is time to also make the switch to the new version – MySQLi (MySQL improved).

As you can see from the code above, the only major difference with the old way we connected to a database, is that here we create a MySQLi object instead of using the mysql_ functions. Also, as you will see in a moment, when we query the database a MySQL resource object is returned, which in turn has its own set of methods. This might sound intimidating, but it will become perfectly clear once you see it in action.

appreciateMe/script.php

/* Setting the error reporting level */
error_reporting(E_ALL ^ E_NOTICE);
include 'connect.php';

if(!$_GET['url'] || !filter_input(INPUT_GET,'url',FILTER_VALIDATE_URL)){
	exit;
}

$pageID			= 0;
$appreciated	= 0;
$jsonArray		= array();
$hash			= md5($_GET['url']);
$ip				= sprintf('%u',ip2long($_SERVER['REMOTE_ADDR']));

// $result is an object:
$result = $mysqli->query("SELECT id,appreciated FROM appreciate_pages WHERE hash='".$hash."'");

if($result)
{
	list($pageID,$appreciated) = $result->fetch_row();
	// fetch_row() is a method of result
}

// The submit parameter denotes that we need to write to the database

if($_GET['submit'])
{
	if(!$pageID)
	{
		// If the page has not been appreciated yet, insert a new
		// record to the database.

		$mysqli->query("
			INSERT INTO appreciate_pages
			SET
				hash='".$hash."',
				url='".$mysqli->real_escape_string($_GET['url'])."'"
		);

		if($mysqli->affected_rows){

			// The insert_id property contains the value of
			// the primary key. In our case this is also the pageID.

			$pageID = $mysqli->insert_id;
		}
	}

	// Write the vote to the DB, so the user can vote only once

	$mysqli->query("
		INSERT INTO appreciate_votes
		SET
			ip = ".$ip.",
			pageid = ".$pageID
	);

	if($mysqli->affected_rows){
		$mysqli->query("
			UPDATE appreciate_pages
			SET appreciated=appreciated+1 WHERE id=".$pageID
		);

		// Increment the appreciated field
	}

	$jsonArray = array('status'=>1);
}
else
{
	// Only print the stats

	$voted = 0;

	// Has the user voted?
	$res = $mysqli->query("
		SELECT 1 FROM appreciate_votes
		WHERE ip=".$ip." AND pageid=".$pageID
	);

	if($res->num_rows){
		$voted = 1;
	}

	$jsonArray = array('status'=>1,'voted'=>$voted,'appreciated'=>$appreciated);
}

// Telling the browser to interpret the response as JSON:
header('Content-type: application/json');

echo json_encode($jsonArray);

The script handles two different types of AJAX requests – read only request (which returns a JSON object with information about the number of appreciations of the page, and whether the current user has clicked the button), and write requests (which save the visitor’s vote to the database, and if necessary, save the page URL and hash as well).

As you an see in the code snippet above, one of the first things that the script does is to calulate the MD5 hash of the page. This is used as a unique key in the database, as URLs have unlimited length which is incompatible with MySQL’s UNIQUE keys. As an MD5 hash is unique for most practical purposes, we can safely use it in our selects and inserts, instead of the long URL addresses.

In the last line of the code, we convert the $jsonArray array into a valid JSON object with the inbuilt json_encode PHP function, and output it with a applicatoin/json content type.

Click To Appreciate - Inactive

Step 3 – jQuery

Inside the appreciateMe directory you can find the plugin.js file. You must include it in the page you wish to show the Appreciate button on. It uses AJAX to request data from the PHP backend and uses the response it receives to create the markup of the button.

appreciateMe/plugin.js

function(){

	$.appreciateButton = function(options){

		// The options object must contain a URL and a Holder property
		// These are the URL of the Appreciate php script, and the
		// div in which the badge is inserted

		if(!'url' in options || !'holder' in options){
			return false;
		}

		var element = $(options.holder);

		// Forming the url of the current page:

		var currentURL = 	window.location.protocol+'//'+
					window.location.host+window.location.pathname;

		// Issuing a GET request. A rand parameter is passed
		// to prevent the request from being cached in IE

		$.get(options.url,{url:currentURL,rand:Math.random()},function(response){

			// Creating the appreciate button:

			var button = $('',{
				href:'',className:'appreciateBadge',
				html:'Appreciate Me'
			});

			if(!response.voted){
				// If the user has not voted previously,
				// make the button active / clickable.
				button.addClass('active');
			}
			else button.addClass('inactive');

			button.click(function(){
				if(button.hasClass('active')){

					button.removeClass('active').addClass('inactive');

					if(options.count){
						// Incremented the total count
						$(options.count).html(1 + parseInt(response.appreciated));
					}

					// Sending a GET request with a submit parameter.
					// This will save the appreciation to the MySQL DB.

					$.getJSON(options.url,{url:currentURL,submit:1});
				}

				return false;
			});

			element.append(button);

			if(options.count){
				$(options.count).html(response.appreciated);
			}
		},'json');

		return element;
	}

})(jQuery);

The script basically creates a new method in the main jQuery object. This differs from the plugins that we usually do, in that this type of plugins are not called on a set of elements (no need to select elements). You can just call $.appreciateButton() while passing a configuration object as a parameter. This is exactly what we’ve done in script.js add a button to the page:

script.js

$(document).ready(function(){

	// Creating an appreciate button.

	$.appreciateButton({
		url		: 'appreciateMe/script.php',	// URL to the PHP script.
		holder	: '#main',				// The button will be inserted here.
		count	: '#countDiv'			// Optional. Will show the total count.
	});

});

The configuration object, which is passed as a parameter, has to contain a url and a holder properties, whereas count is optional. Notice that I’ve specified the path to script.php relatively, as appreciateMe is a child directory of the one the page is currently in.

However, if you plan to add the script to a site with a variable path structure, you should probably specify an absolute path. Either add a leading slash, or provide a complete URL with http://.

Step 4 – CSS

Now that we have all the markup and code in place, it is time to turn to the styling. The CSS rules that style the appreciate badge are located in appreciate.css. You could optionally copy these rules to your main stylesheet file, if you’d like to avoid the extra request, but beware that you will need to change the paths to the background images.

appreciateMe/appreciate.css

.appreciateBadge{
	width:129px;
	height:129px;
	display:block;
	text-indent:-9999px;
	overflow:hidden;
	background:url('sprite.png') no-repeat;
	text-decoration:none;
	border:none;
}

.appreciateBadge.active{
	background-position:left top;
}

.appreciateBadge.active:hover{
	background-position:0 -129px;
}

.appreciateBadge.inactive{
	background-position:left bottom;
	cursor:default;
}

There are three versions of the appreciate badge image. A default one, a hover one, and an inactive one. All three of these reside in the same file – sprite.png, one below the other. With this technique you can switch between the versions instantaneously by offsetting the background image of the hyperlink.

styles.css

#main{
	margin:80px auto;
	width:130px;
}

#countDiv{
	color:#eee;
	font-size:35px;
	margin-right:120px;
	position:absolute;
	right:50%;
	top:265px;
}

You can find the rest of the styles, which refine the looks of page.html, in styles.css. Only two sets of styles affect the appreciate button directly. The #main div, which contains the button and centers it on the page, and #countDiv in which the total number of appreciations is inserted.

With this our Click to Appreciate Badge is complete!

Conclusion

Before being able to run this script on your server, you first have to replace the MySQL credentials in connect.php with your own. Also, you will need to run the contents of tables.sql in the SQL tab of phpMyAdmin, so the two tables are created. Lastly, depending on your URL paths, you may have to change the URL property of appreciateMe/script.php in the script.js JavaScript File.

Simple AJAX Commenting System

Martin Angelov — Wed, 30 Jun 2010 18:02:24 +0000

This time, we are making a Simple AJAX Commenting System. It will feature a gravatar integration and demonstrate how to achieve effective communication between jQuery and PHP/MySQL with the help of JSON.

Step 1 – XHTML

First, lets take a look at the markup of the comments. This code is generated by PHP in the Comment class, which we are going to take a look at in a moment.

demo.php


    
        
        
        
    

    Person's Name
    30 Jun 2010
    Comment Body

The avatar div contains a hyperlink (if the user entered a valid URL when submitting the comment) and an avatar image, which is fetched from gravatar.com. We will return to this in the PHP step of the tut. Lastly we have the name and time divs, and the comment body.

The other important element in the XHTML part is the comment form. It is sent via POST. All fields except for the URL field are required.

demo.php


	Add a Comment
	
    	
        	Your Name
        	

            Your Email
            

            Website (not required)
            

            Comment Body

The form is submitted via AJAX. The validation is performed entirely in the backend by submit.php, as you will see in the jQuery step of the tutorial. Every field has a corresponding label element, with an appropriate for attribute.

Simple AJAX Commenting System

Step 2 – PHP

PHP handles the communication with the MySQL database and generates the markup of the comments. It is also on the receiving end of the AJAX requests and inserts the comment data to the comments table. You can see the code that prints the comments to the page below.

demo.php

/*
/	Select all the comments and populate the $comments array with objects
*/

$comments = array();
$result = mysql_query("SELECT * FROM comments ORDER BY id ASC");

while($row = mysql_fetch_assoc($result))
{
	$comments[] = new Comment($row);
}

The MySQL query selects all the entries from the database and fills the $comments array with objects of the comment class, which you will see below. This array is outputted later in the execution of the script.

demo.php

/*
/	Output the comments one by one:
*/

foreach($comments as $c){
	echo $c->markup();
}

Each comment has a markup() method, which generates valid HTML code ready to be printed to the page. You can see the definition of this method and the class below.

The class takes a row from the database (fetched with mysql_fetch_assoc() ) and stores it in the private variable $data. It is available only to the methods of the class and cannot be accessed from outside.

comment.class.php – Part 1

class Comment
{
	private $data = array();

	public function __construct($row)
	{
		/*
		/	The constructor
		*/

		$this->data = $row;
	}

	public function markup()
	{
		/*
		/	This method outputs the XHTML markup of the comment
		*/

		// Setting up an alias, so we don't have to write $this->data every time:
		$d = &$this->data;

		$link_open = '';
		$link_close = '';

		if($d['url']){

			// If the person has entered a URL when adding a comment,
			// define opening and closing hyperlink tags

			$link_open = '';
			$link_close =  '';
		}

		// Converting the time to a UNIX timestamp:
		$d['dt'] = strtotime($d['dt']);

		// Needed for the default gravatar image:
		$url = 'http://'.dirname($_SERVER['SERVER_NAME'].$_SERVER["REQUEST_URI"]).
				'/img/default_avatar.gif';

		return '

			
				
					'.$link_open.'
					
					'.$link_close.'
				

				'.$link_open.$d['name'].$link_close.'
				'.
				date('d M Y',$d['dt']).'
				'.$d['body'].'
			
		';
	}

This script uses gravatar to present avatars in the comments. For those of you, who have not used gravatar, this is a really useful service, which lets you associate an avatar with your email address. The avatar image can easily be fetched by passing an md5() encoded hash of your email address to gravatar.com. This is exactly what we do on line 48.

Notice line 39 above it – the script tries to figure out the URL at which it is located, and determines the exact address of the default_avatar.gif image. This gif is passed to gravatar along the md5 hash, so if no avatar was found for this particular email, the fallback image is displayed instead.

comment.class.php – Part 2

	public static function validate(&$arr)
	{
		/*
		/	This method is used to validate the data sent via AJAX.
		/
		/	It return true/false depending on whether the data is valid, and populates
		/	the $arr array passed as a paremter (notice the ampersand above) with
		/	either the valid input data, or the error messages.
		*/

		$errors = array();
		$data	= array();

		// Using the filter_input function introduced in PHP 5.2.0

		if(!($data['email'] = filter_input(INPUT_POST,'email',FILTER_VALIDATE_EMAIL)))
		{
			$errors['email'] = 'Please enter a valid Email.';
		}

		if(!($data['url'] = filter_input(INPUT_POST,'url',FILTER_VALIDATE_URL)))
		{
			// If the URL field was not populated with a valid URL,
			// act as if no URL was entered at all:

			$url = '';
		}

		// Using the filter with a custom callback function:

		if(!($data['body'] = filter_input(INPUT_POST,'body',FILTER_CALLBACK,
						array('options'=>'Comment::validate_text'))))
		{
			$errors['body'] = 'Please enter a comment body.';
		}

		if(!($data['name'] = filter_input(INPUT_POST,'name',FILTER_CALLBACK,
						array('options'=>'Comment::validate_text'))))
		{
			$errors['name'] = 'Please enter a name.';
		}

		if(!empty($errors)){

			// If there are errors, copy the $errors array to $arr:

			$arr = $errors;
			return false;
		}

		// If the data is valid, sanitize all the data and copy it to $arr:

		foreach($data as $k=>$v){
			$arr[$k] = mysql_real_escape_string($v);
		}

		// Ensure that the email is in lower case (for a correct gravatar hash):
		$arr['email'] = strtolower(trim($arr['email']));

		return true;

	}

The validate() method above (also part of the class) is defined as static. This means that it can be evoked directly like Comment::validate(), without the need of creating an object of the class. What this method does, is validate the input data which is submitted via AJAX.

This method uses the new filter functions, which are available as of PHP 5.2.0. These allow us to easily validate and filter any input data that is passed to the script. For example filter_input(INPUT_POST,’url’,FILTER_VALIDATE_URL) means that we are checking whether $_POST['url'] is a valid URL address. If it is, the function returns the value of the variable, otherwise it return false.

This is really useful, as up until now, we had to use custom regular expressions to validate data (and have series of if statements). Also, another advantage is that this data is fetched before any configuration-specific transformations (like magic quotes) are applied.

We also have the option of specifying a custom function which is going to apply some more advanced modifications of the data, as you can see from lines 31 and 37.

comment.class.php – Part 3

	private static function validate_text($str)
	{
		/*
		/	This method is used internally as a FILTER_CALLBACK
		*/

		if(mb_strlen($str,'utf8')<1)
			return false;

		// Encode all html special characters (<, >, ", & .. etc) and convert
		// the new line characters to 
 tags:

		$str = nl2br(htmlspecialchars($str));

		// Remove the new line characters that are left
		$str = str_replace(array(chr(10),chr(13)),'',$str);

		return $str;
	}

}

The last method is validate_text, which we are passing as a callback function in the two filter_input calls above. It encodes all special HTML characters, effectively blocking XSS attacks. It also replaces the newline characters with
line breaks.

submit.php

/*
/	This array is going to be populated with either
/	the data that was sent to the script, or the
/	error messages:
/*/

$arr = array();

$validates = Comment::validate($arr);

if($validates)
{
	/* Everything is OK, insert to database: */

	mysql_query("	INSERT INTO comments(name,url,email,body)
					VALUES (
						'".$arr['name']."',
						'".$arr['url']."',
						'".$arr['email']."',
						'".$arr['body']."'
					)");

	$arr['dt'] = date('r',time());
	$arr['id'] = mysql_insert_id();

	/*
	/	The data in $arr is escaped for the mysql insert query,
	/	but we need the unescaped text, so we apply,
	/	stripslashes to all the elements in the array:
	/*/

	$arr = array_map('stripslashes',$arr);

	$insertedComment = new Comment($arr);

	/* Outputting the markup of the just-inserted comment: */

	echo json_encode(array('status'=>1,'html'=>$insertedComment->markup()));

}
else
{
	/* Outputting the error messages */
	echo '{"status":0,"errors":'.json_encode($arr).'}';
}

submit.php receives the comment form data via an AJAX request. It validates it and outputs a JSON object with either the XHTML markup of the successfully inserted comment, or a list of error messages. jQuery uses the status property to determine whether to display the error messages or add the comment markup to the page.

You can see two example responses below.

Successful response

{
    "status": 1,
    "html": "Html Code Of The Comment Comes Here..."
}

The html property contains the code of the comment, similar to markup in step one.

Failure response

{
    "status": 0,
    "errors": {
        "email": "Please enter a valid Email.",
        "body": "Please enter a comment body.",
        "name": "Please enter a name."
    }
}

On failure, jQuery loops through the errors object, and outputs the errors next to the fields that caused them.

Fancy CSS3 & jQuery Submit Form

Step 3 – CSS

Now that we have all the markup properly generated and displayed on the page, we can move on to styling it.

styles.css – Part 1

.comment,
#addCommentContainer{

	/* Syling the comments and the comment form container */

	padding:12px;
	width:400px;
	position:relative;
	background-color:#fcfcfc;
	border:1px solid white;
	color:#888;
	margin-bottom:25px;

	/* CSS3 rounded corners and drop shadows */

	-moz-border-radius:10px;
	-webkit-border-radius:10px;
	border-radius:10px;

	-moz-box-shadow:2px 2px 0 #c2c2c2;
	-webkit-box-shadow:2px 2px 0 #c2c2c2;
	box-shadow:2px 2px 0 #c2c2c2;
}

.comment .avatar{

	/*
	/	The avatar is positioned absolutely,
	/	and offset outside the comment div
	/*/

	height:50px;
	left:-70px;
	position:absolute;
	width:50px;
	background:url('img/default_avatar.gif') no-repeat #fcfcfc;

	/* Centering it vertically: */

	margin-top:-25px;
	top:50%;

	-moz-box-shadow:1px 1px 0 #c2c2c2;
	-webkit-box-shadow:1px 1px 0 #c2c2c2;
	box-shadow:1px 1px 0 #c2c2c2;
}

The .comment divs and the #addCommentContainer are styled at once because they share most of the styling. A number of CSS3 rules are applied, including rounded corners and a box-shadow. Needless to say, these do not work in older browsers, but as they are purely presentational, the script will still work without them.

styles.css – Part 2

.comment .avatar img{
	display:block;
}

.comment .name{
	font-size:20px;
	padding-bottom:10px;
	color:#ccc;
}

.comment .date{
	font-size:10px;
	padding:6px 0;
	position:absolute;
	right:15px;
	top:10px;
	color:#bbb;
}

.comment p,
#addCommentContainer p{
	font-size:18px;
	line-height:1.5;
}

#addCommentContainer input[type=text],
#addCommentContainer textarea{

	/* Styling the inputs */

	display:block;
	border:1px solid #ccc;
	margin:5px 0 5px;
	padding:3px;
	font-size:12px;
	color:#555;
	font-family:Arial, Helvetica, sans-serif;
}

#addCommentContainer textarea{
	width:300px;
}

label{
	font-size:10px;
}

label span.error{
	color:red;
	position:relative;
	right:-10px;
}

#submit{

	/* The submit button */

	background-color:#58B9EB;
	border:1px solid #40A2D4;
	color:#FFFFFF;
	cursor:pointer;
	font-family:'Myriad Pro',Arial,Helvetica,sans-serif;
	font-size:14px;
	font-weight:bold;
	padding:4px;
	margin-top:5px;

	-moz-border-radius:4px;
	-webkit-border-radius:4px;
	border-radius:4px;
}

#submit:hover{
	background-color:#80cdf5;
	border-color:#52b1e2;
}

In the second part of the stylesheet, we style the comment and form elements. Notice the input[type=text] selector, which selects elements depending on the type attribute.

Step 4 – jQuery

Now lets continue with jQuery, which is the last step of this tutorial. After including the library to the bottom of the page (best for the perceived performance of the page) we can start coding the script file.

script.js

$(document).ready(function(){
	/* The following code is executed once the DOM is loaded */

	/* This flag will prevent multiple comment submits: */
	var working = false;

	/* Listening for the submit event of the form: */
	$('#addCommentForm').submit(function(e){

 		e.preventDefault();
		if(working) return false;

		working = true;
		$('#submit').val('Working..');
		$('span.error').remove();

		/* Sending the form fileds to submit.php: */
		$.post('submit.php',$(this).serialize(),function(msg){

			working = false;
			$('#submit').val('Submit');

			if(msg.status){

				/*
				/	If the insert was successful, add the comment
				/	below the last one on the page with a slideDown effect
				/*/

				$(msg.html).hide().insertBefore('#addCommentContainer').slideDown();
				$('#body').val('');
			}
			else {

				/*
				/	If there were errors, loop through the
				/	msg.errors object and display them on the page
				/*/

				$.each(msg.errors,function(k,v){
					$('label[for='+k+']').append(''+
						v+'');
				});
			}
		},'json');

	});

});

Starting from the top, we have the $(document).ready() call, which binds a function to the DOM content loaded event. The working variable acts as a flag, which tells the script if an AJAX request is in progress (thus preventing double posting).

In the callback function for the POST AJAX request, we check the status property to determine whether the comment was successfully inserted. If it was, we add the received markup to the page after the last comment with a slideDown animation.

If there were problems, we display the error messages by appending an error span to the appropriate label element (the for attribute of the label contains the id of the input that caused the error).

With this our Simple AJAX Commenting System is complete!

Conclusion

To be able to run this script on your server, you need to create the comments table in your MySQL database. You can do this by executing the SQL code found in table.sql from the SQL tab of phpMyAdmin. After this you need to enter your MySQL connection details in connect.php.

You are free to modify and use this code any way you see fit.

What do you think? How would you improve this script?

Combined Facebook, Twitter & RSS Social Stats with jQuery, PHP & YQL

Martin Angelov — Wed, 19 May 2010 21:50:43 +0000

As we increasingly depend on more and more social services, there rises the need to provide a simple way to let our website visitors take part of our diverse social presence.

In this tutorial we are going to create a simple widget, which combines the number of your RSS readers, twitter followers, and fans of your facebook fan page, to give a rough estimate of your social popularity.

We are using jQuery and the tipTip plugin, object-oriented PHP, and Yahoo’s YQL, while demonstrating a number of interesting web development techniques.

Step 1 – PHP

YQL is a free Yahoo web service, which enables us to communicate with numerous third-party APIs through a consistent SQL-like language (and hence the name). It is basically a gateway that sits between you and the other APIs.

This is especially important here, as we are using Yahoo’s YQL for three very different tasks:

Fetch your RSS subscriber count with FeedBurner’s awareness API (which comes in the form of an XML file that has to be parsed).
Note: You have to enable the awareness API to use this widget with your own feed. This is done from the Publicize Tab on your feed settings page;
Use twitter’s API to get your number of followers;
Use Facebook’s new Graph API (link) to get information about the number of fans of your facebook fanpage.

If it weren’t for YQL, we’d have to research and implement three very different solutions, which would slow us down significantly.

includes/subscriber_stats.class.php

class SubscriberStats{

	public	$twitter,$rss,$facebook;
	public	$services = array();

	public function __construct($arr){

		$this->services = $arr;

		$yqlQueries = array();

		// Forming the Feedburner Awaraness API URL from the passed feed URL:
		$feedBurnerAwarenessAPI = 'http://feedburner.google.com/api/awareness'.
		'/1.0/GetFeedData?uri='.end(split('/',trim($arr['feedBurnerURL'],'/')));

		// Building an array with queries:

		if($arr['feedBurnerURL'])
			$yqlQueries[] = '
				SELECT * FROM xml
				WHERE url=\''.$feedBurnerAwarenessAPI.'\'
			';

		if($arr['twitterName'])
			$yqlQueries[] = '
				SELECT * FROM twitter.user.profile
				WHERE id=\''.$arr['twitterName'].'\'
			';

		if($arr['facebookFanPageURL'])
			$yqlQueries[] = '
			SELECT fan_count FROM facebook.graph
			WHERE id=\''.end(split('/',trim($arr['facebookFanPageURL'],'/'))).'\'
			';

		// Combing them into a YQL multiquery:
		$multiQuery =
		'SELECT * FROM query.multi WHERE queries = "'.join(';',$yqlQueries).'"';

		// Executing the query:
		$result = json_decode(
			file_get_contents('http://query.yahooapis.com/v1/public/yql?q='.
			urlencode($multiQuery).'&format=json&diagnostics=false&'
			'amp;env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys')
		)->query->results->results;

		// The results from the queries are accessible in the $results array:

		$this->rss = $result[0]->rsp->feed->entry->circulation;
		$this->twitter = $result[1]->item->meta[5]->content;
		$this->facebook = $result[2]->json->fan_count;
	}

	public function generate(){

		$total = number_format($this->rss+$this->twitter+$this->facebook);

		echo '
			
				'.$total.'

				
					
					
				

				
					
					
				

				
				
					
				
			
		';
	}
}

When we create an object of this class, the construct method is called, and a YQL query is created and executed.

To request the data from YQL’s servers, we just use file_get_contents() with the query passed as a parameter of the URL address. This returns a JSON object (basically a JavaScript object) which we can decode into a native PHP array with the in-build json_decode() function.

The results of these queries are saved locally and are made available for use in the generate() method which renders all the needed markup.

And now lets see how this class is used:

subscriber_count.php

require "includes/subscriber_stats.class.php";

$cacheFileName = "cache.txt";

// IMPORTANT: after making changes to this file (or the SubscriberStats class)
// remeber to delete cache.txt from your server, otherwise you wont see your changes.

// If a cache file exists and it is less than 6*60*60 seconds (6 hours) old, use it:

if(file_exists($cacheFileName) && time() - filemtime($cacheFileName) > 6*60*60)
{
	$stats = unserialize(file_get_contents($cacheFileName));
}

if(!$stats)
{
	// If no cache was found, fetch the subscriber stats and create a new cache:

	$stats = new SubscriberStats(array(
		'facebookFanPageURL'	=> 'http://www.facebook.com/smashmag',
		'feedBurnerURL'			=> 'http://feeds.feedburner.com/Tutorialzine',
		'twitterName'			=> 'Tutorialzine'
	));

	// Serialize turns the object into a string,
	// which can later be restored with unserialize():

	file_put_contents($cacheFileName,serialize($stats));
}

//	You can access the individual stats like this:
//	$stats->twitter;
//	$stats->facebook;
//	$stats->rss;

//	Output the markup for the stats:

$stats->generate();

Sending a query to YQL’s servers and receiving a response is a relatively slow process and would be unwise to request the same information on every page load (not to mention that we could get banned from the API for abuse).

This is why we implement a simple caching system. The idea is simple: if a cache file does not exist (or is older than 6 hours), connect to YQL, create a new cache file and output the XHTML markup. Otherwise, just read the cache and output directly. This way we send a request to the API only once every six hours which is perfect for any practical purposes.

Combined Social Media Followers Count

Step 2 – XHTML

As mentioned in the PHP section above, the generate() method renders all the XHTML markup used to display the stats. Here is what the generated code looks like:

sample code

This code is fetched via AJAX and displayed on the page. Notice the title attributes. They are used as the contents of the fancy tooltips which are created by jQuery and the tipTip plugin, which we will discuss in a moment.

Step 3 – CSS

The CSS code is also quite simple and straightforward. The subscriberStats is the main outer div, inside it we have a number of .socialIcon divs and the subscrberCount.

css/styles.css

.subscriberStats{
	height:35px;
	padding:5px;
	width:220px;
}

.socialIcon{
	float:left;
	height:32px;
	width:32px;
}

a img{
	border:none;
}

.subscriberCount{
	border-bottom:1px dotted #CCCCCC;
	color:#999999;
	float:left;
	font-size:28px;
	line-height:32px;
	margin-right:10px;
}

#main{
	height:100px;
	margin:140px auto 50px;
	position:relative;
	width:200px;
}

All of these are floated to the left. Also notice that we disable the borders on the icon images on line 14, which are displayed by default and ruin your design.

Step 4 – jQuery

After including the jQuery library to the page, we just need to listen to the $(document).ready event, which is executed when all the markup of the page is accessible (this happens before things like images are loaded and comes earlier than the onload event).

js/script.js

$(document).ready(function(){

	// Using the load AJAX method to fetch the subscriber markup
	// from subscriber_count.php:

	$('#main').load('subscriber_count.php',function(){

		// Once loaded, convert the title attributes to tooltips
		// with the tipTip jQuery plugin:

		$('.subscriberStats div').tipTip({defaultPosition:'top'});
	})

});

#main is the div where we want to insert the stats. This could be your sidebar or website header. The load method fetches the markup from suscriber_count.php and displays it on the page. The callback function is called after this and all the div titles are replaced with fancy tooltips by the tipTip plugin.

With this our combined social stats widget is complete!

Conclusion

With services like YQL working with third party APIs is a charm. Not only it provides a common interface to a sea of technologies, but it also guarantees that you will be able to access to the services you want even as the underlying APIs change overtime.

What do you think? How would you improve this code?

Making a Donation Center With PHP, MySQL and PayPal’s APIs

Martin Angelov — Thu, 13 May 2010 13:27:21 +0000

It all started last month when I received the following email:

Hey there Tutorialzine!

Thanks for publishing such great tutorials, you have truly helped me increase my (growing) development skills. I know you enjoy getting ideas for tutorials, so I thought I’d toss one your way.

Donation buttons are a very common among blogs and websites in general, but they often don’t provide much else than a button for someone to click and pay. Why not kick it up a notch and create a sweet “donation center”, which doesn’t just take donations, but perhaps includes a “meter”, a top-donator list, and various other bells and whistles that may encourage the visitor to donate?

Devon

You are right, Devon, it is always nice to hear fresh ideas for tutorials. And a donation center is a great chance to experiment with PayPal’s APIs and build something that many people can benefit from.

The Idea

PayPal provides numerous APIs and integration options for third-party developers. One of these is the Donation button, which you can generate straight from PayPal’s site and include directly into your pages. Conversion rate for these buttons is typically minimal, but the right incentive can make a big difference.

The idea is to have a dedicated Donation Center. This is a place, where you get to see what a difference your donation would make, and a list of people who have already donated.

After choosing the amount you wish to donate and clicking the button, you are redirected to paypal.com to complete the transaction. After this is done, you are redirected back to the donation center where you can fill a form and get included in the official Donor List.

A Complete PHP & MySQL Donation Center

Step 1 – Database

The script uses two tables – dc_donations and dc_comments. The first stores the donation data which is passed in a request from PayPal (we will come back to this in the PHP step of the tutorial).

Table Schema for dc_donations

The second table holds the information about the donors, which they fill for themselves on the thank you page.

Table Schema for dc_comments

You can create these tables in your database by running the SQL code from tables.sql (found in the download archive) from the SQL tab of phpMyAdmin. You can also just upload the file via the “Import” feature.

After this remember to add your MySQL login details to connect.php.

Step 2 – XHTML

Moving to the markup of the donation center iself. Donate PHP is the only page which your visitors see. The other page is thankyou.php, which is displayed only to the donors, once they’ve completed the donation process.

donate.php


	Donation Center
	Show Your Support for our Cause

	
		Hello, dear visitor!
		This is Tutorialzine's Donation Center...	

		

	

	
		Our Goal
	

	
		% done
	

	

	
		The Donor List
		Folks Who Showed Their Support

The .lightSection div holds the message that we show to the visitor of the page and the markup of the PayPal donation button, which you can see below. After this is the Pie chart which shows how much of our initial goal is met. The chart is generated with Google’s Charting API. Lastly is the .donors div, which holds a list of donors that have already donated.

donate.php

The PayPal Donation button is structured as a regular html form. When you click the Donate graphic, the form is submitted to PayPal. A number of customizations are available, such as the the amount of the donation, the email of the recipient of the donation and many more (the full list of options is located here). Each of this options is added as a hidden field to the form.

Note the return and the notify_url variables. The first takes the URL of the page to which the user is redirected after the completion of the payment (in our case thankyou.php), and the other is a special page, which listens for PayPal’s Instant Payment Notifications (IPN).

When a payment occurs, PayPal sends a special IPN notification to a page on your server. Data about the transaction is passed along the way, including the amount received, the email of the payee, currency and more. For example our IPN listener page, ipn.php, inserts the amount received to the donations table, which is later used by the Donation Center to calculate how much money has been gathered and what percentage of the goal has been met.

Now lets move to the PHP part of the tutorial.

Setting a Goal with Google's Charting API

Step 3 – PHP

As mentioned in the previous step, when a payment occurs, PayPal sends an IPN notification to your script, which contains all kinds of data for the transaction. Implementing this IPN listener page involves a lot of coding, as the script must validate that the notification was issued by PayPal.

Lucky for us, there are nice people out there who have already implemented these validations and packed them into an easy to use PHP5 PayPal class. Now lets take a look at how this is used:

ipn.php

require "paypal_integration_class/paypal.class.php";
require "config.php";
require "connect.php";

$p = new paypal_class;
$p->paypal_url = $payPalURL; // $payPalURL is defined in config.php

if ($p->validate_ipn()) {
	if($p->ipn_data['payment_status']=='Completed')
	{
		$amount = $p->ipn_data['mc_gross'] - $p->ipn_data['mc_fee'];

		mysql_query("	INSERT INTO dc_donations (transaction_id,donor_email,amount,original_request)
						VALUES (
							'".esc($p->ipn_data['txn_id'])."',
							'".esc($p->ipn_data['payer_email'])."',
							".(float)$amount.",
							'".esc(http_build_query($_POST))."'
						)");
	}
}

function esc($str)
{
	global $link;
	return mysql_real_escape_string($str,$link);
}

First we create a new paypal_class and assign it PayPal’s URL. The rest is just a matter of calling the $p->validate_ipn() method and it will do all the hard work for us. If everything went OK, we insert the amount of the transaction, the email of the payee and the transaction id to the dc_donations table. It is probably a good place to note, that this page is not visible to the end user, it only exists to listen for IPN notifications from paypal which happen on the backend.

thankyou.php

require "config.php";
require "connect.php";

if(isset($_POST['submitform']) && isset($_POST['txn_id']))
{
	$_POST['nameField'] = esc($_POST['nameField']);
	$_POST['websiteField'] =  esc($_POST['websiteField']);
	$_POST['messageField'] = esc($_POST['messageField']);

	$error = array();

	if(mb_strlen($_POST['nameField'],"utf-8")<2)
	{
		$error[] = 'Please fill in a valid name.';
	}

	if(mb_strlen($_POST['messageField'],"utf-8")<2)
	{
		$error[] = 'Please fill in a longer message.';
	}

	if(!validateURL($_POST['websiteField']))
	{
		$error[] = 'The URL you entered is invalid.';
	}

	$errorString = '';
	if(count($error))
	{
		$errorString = join('
',$error);
	}
	else
	{
		mysql_query("	INSERT INTO dc_comments (transaction_id, name, url, message)
						VALUES (
							'".esc($_POST['txn_id'])."',
							'".$_POST['nameField']."',
							'".$_POST['websiteField']."',
							'".$_POST['messageField']."'
						)");

		if(mysql_affected_rows($link)==1)
		{
			$messageString = 'You were added to our donor section!';
		}
	}
}

After the use has donated, he is redirected by PayPal to our thank you page. Here he can add himself to the donor list by filling in a form. Wen redirecting, PayPal places transaction data in the $_POST array, which is available to thankyou.php. We can use this data to confirm that the user has in fact donated, and not just navigated manually to thankyou.php, bypassing PayPal. After the form is submitted, the user is added to the dc_comments table.

donate.php

require "config.php";
require "connect.php";

// Determining the URL of the page:
$url = 'http://'.$_SERVER['SERVER_NAME'].dirname($_SERVER["REQUEST_URI"]);

// Fetching the number and the sum of the donations:
list($number,$sum) = mysql_fetch_array(mysql_query("SELECT COUNT(*),SUM(amount) FROM dc_donations"));

// Calculating how many percent of the goal are met:
$percent = round(min(100*($sum/$goal),100));

// Building a URL with Google's Chart API:
$chartURL = 'http://chart.apis.google.com/chart?chf=bg,s,f9faf7&cht=p&chd=t:'.$percent.',-'.(100-$percent).'&chs=200x200&chco=639600&chp=1.57';

Google’s Chart Api is an easy way to generate any kind of chart. To use it you just have to create a URL to http://chart.apis.google.com/ which contains settings such as background color, type of chart (in our case a Pie), and a comma-separated list of values which serve as the data. You can include this URL as you would do a regular image, and a chart will be dynamically generated for you.

donate.php

Later in donate.php, we are building the donor list after running a query against the dc_comments table.

The Donor List

Step 4 – CSS

Having all the markup generated and included in the page, it is time to style it. You may find it surprising but the entire design is entirely CSS based and does not use a single image (apart from PayPal’s Donate button image that is).

styles.css – Part 1

*{
	/* Universal page reset */
	margin:0;
	padding:0;
}

body{
	/* Setting default text color, background and a font stack */
	font-size:13px;
	color:#9bb370;
	background-color:#f9faf7;
	font-family:Rockwell, 'Courier New', Courier, Georgia, serif;
}

p{
	font-family:Arial, Helvetica, sans-serif;
	font-size:20px;
}

h1{
	/* The Donation Center text */
	border-bottom:1px solid #E3EBD2;
	color:#639600;
	font-size:70px;
	line-height:1;
	margin-left:-20px;
	padding:0 0 0 30px;
}

h2{
	/* The subtitle, notice the line-height property */
	border-left:1px solid #E3EBD2;
	color:#ABC084;
	font-size:35px;
	height:35px;
	line-height:75px;
	margin:-70px 0 0;
	padding:55px 0 0 10px;
}

h3{
	color:#639600;
	font-size:38px;
}

#main{
	/* The main container div */
	margin:40px auto;
	padding:0 0 0 20px;
	position:relative;
	width:860px;
}

You may notice in the demo page, how the Donation Center heading and subheading form an interesting set of lines. These are in fact the bottom and left borders of the h1 and h2 respectively.

styles.css – Part 2

.chart{
	/* The Google Chart is set as this div's background via the style attribute.
	The negative text-indent moves the text outside the box */

	margin:0 0 0 300px;
	text-indent:-300px;
	width:200px;
}

.donations,.chart{
	color:#ABC084;
	font-size:50px;
	font-weight:bold;
	float:left;
	height:200px;
	line-height:200px;
}

.donations{ text-align:right; width:340px;}
.comments{ margin-top:60px;}
.entry{ margin-bottom:50px;}

.comment{
	background-color:#edf2e4;
	padding:20px;
	position:relative;
	margin-bottom:20px;
}

.name{
	color:#639600;
	font-size:24px;
	font-style:italic;
	font-weight:bold;
	position:relative;
}

.name a.url{
	color:#C0D39C;
	font-weight:normal;
	padding-left:10px;
}

.tip{
	width:0;
	height:0;
	bottom:-40px;
	left:20px;

	/* A neat CSS trick which creates a triangle shape*/
	/* from the div's top border */

	border:20px solid #f9faf7;
	border-width:20px 15px;
	border-top-color:#edf2e4;
	position:absolute;
}

Creating a triangle shape with CSS is also possible by setting the width and the height of the div to zero and specifying a big value for the widths of the borders.

With this our PHP & MySQL Donation Center is complete!

Conclusion

You can use this donation center to turn the usually anonymous act of donating funds into a more social and open process. You can possibly modify the code to include Twitter & Facebook integration or improve it in any other way you see fit.

What do you think? How would you improve this code?

Simple Banner Rotator With PHP, jQuery & MySQL

Martin Angelov — Tue, 27 Apr 2010 20:59:49 +0000

In this tutorial we are making a simple PHP, jQuery & MySQL banner rotator, with which you can create and randomly display banners on your site. Each of the banners features a neat jQuery animation effect, which you can customize to fit your own needs.

The database schema

Before we start coding, lets take a look at the database. All the banners are inserted into the banners MySQL table. It has the following structure:

The Database Schema

ID is a primary key, which is auto-incremented, which means that you don’t need to add a number in that field if you are manually inserting new banners. Next is the image field, which holds the filename of the banner, after it is the company name and lastly the URL of the company’s site, all of which are varchar fields (regular strings).

If you want to run the demo on your own host, you will need to recreate this table from the definitions inside table.sql in the download archive. Just paste the SQL colde in your MySQL manager. Also don’t forget to fill in your MySQL login details in connect.php, before uploading the files to your server.

Step 1 – XHTML

The XHTML code of the banners is generated on the fly by PHP after a database query, and outputted to the page. Here is how the markup for a sample banner looks like:

demo.php


	
		
	
	Visit Rapid HTML

Inside each banner div, we have a hyperlink to the company’s site, a standard 125 by 125 px banner, a paragraph with the company name, and four corner divs.

The paragraph and the corner divs are hidden by default and are shown when the user moves their mouse over the main .banner div. This ensures that the banners are perfectly functional even with JavaScript disabled, albeit without the fancy transition.

The jQuery Animation

Step 2 – CSS

Lets move to styling the page. To ensure cross-browser compatibility, we first have to reset the default styles that browsers apply to page elements. This is simple to do with a universal page reset:

styles.css – Part 1

*{
	/* A universal page reset */
	margin:0;
	padding:0;
}

body{
	/* Setting default text color, background and a font stack */
	font-size:0.825em;
	color:#666;
	background-color:#fff;
	font-family:Arial, Helvetica, sans-serif;
}

.bannerHolder{
	/* The main banner unordered list */

	height:270px;
	width:270px;

	float:left;
	margin:20px 15px;
	padding:10px;
	background:#f7f7f7;
	border:1px solid #eee;

	/* CSS3 rounded corners */

	-moz-border-radius:12px;
	-webkit-border-radius:12px;
	border-radius:12px;
}

.bannerHolder li{
	/* Hiding the bullets of the li elements: */
	list-style:none;
	display:inline;
}

.banner{
	/* The banner divs */
	position:relative;
	width:125px;
	height:125px;
	overflow:hidden;
	float:left;
	margin:5px;
}

.banner img{
	/* The banner divs */
	display:block;
	border:none;
}

As the banners are organized in an unordered list, we first style the list itself (which is assigned the bannerHolder class), then the li elements inside it and lastly the banner divs.

As we have two groups of banners on the page, we have to stick to class names to target the elements in the CSS, as IDs must be unique and don’t allow for more than one element with the same ID.

styles.css – Part 2

.banner div{
	/* The dark animated divs */

	position:absolute;
	z-index:100;
	background-color:#222;
	width:60px;
	height:60px;
	cursor:pointer;

	/*	Setting a really big value for border-radius
		will make the divs perfect circles */

	-moz-border-radius:100px;
	-webkit-border-radius:100px;
	border-radius:100px;
}

/*	Positioning the animated divs outside the
	corners of the visible banner area: */

.banner .cornerTL{ left:-63px;top:-63px; }
.banner .cornerTR{ right:-63px;top:-63px; }
.banner .cornerBL{ left:-63px;bottom:-63px; }
.banner .cornerBR{ right:-63px;bottom:-63px; }

.banner p{
	/* The "Visit Company" text */

	display:none;	/* hidden by default */

	left:0;
	top:57px;
	width:100%;
	z-index:200;
	position:absolute;

	font-family:Tahoma, Arial, Helvetica, sans-serif;
	color:white;
	font-size:11px;
	text-align:center;

	cursor:pointer;
}

In the second part of the code we style the animated rounded divs that slide into view on mouseenter. We are using the border-radius CSS3 property and by giving it a 100px value, we turn the divs into perfect circles. We also position each of the four divs just outside its parent div.

A PHP, MySQL & jQuery Banner Rotator

Step 3 – PHP

Moving to the PHP part, we will first take a look at the banner class.

banner.class.php

class Banner{

	private $data = array();

	public function __construct($row){
		$this->data = $row;
	}

	public function html(){

		/* This method returns the banner's HTML code */

		$d = &$this->data;
		$d['company'] = htmlspecialchars($d['company']);

		return '
			
				
					
				
				Visit '.$d['company'].'
				
				
				
				
			';
	}

}

The constructor method of the class is executed when we create a banner object. It copies the $row variable we pass as a parameter to its internal private $data array.

The other method – html() – returns the HTML code of the banner.

You can see below how this class and its methods are used:

demo.php

$bannerResult = mysql_query("SELECT * FROM banners");

$banners = array();
while($row=mysql_fetch_assoc($bannerResult))
{
	$banners[] = new Banner($row);
}

// Randomizing the $banners array:
shuffle($banners);

// Splitting the banners array into smaller arrays with 4 banners each:
$bannerGroups = array_chunk($banners,4);

After selecting all the banners from the database, PHP fetches each row of the result as an associative array, and creates banner objects. After this the resulting $banners array is shuffled and split with the help of the in-build array_chunk() function.

The array_chunk() PHP function splits an array into smaller chunks. It takes an array as its first parameter and a number as its second. The number specifies how many elements you want in the resulting chunks. The function splits the original array into smaller ones and returns them as an array of arrays.
Read more on array_chunk() at the PHP docs.

As we have 8 banners, we end up with two elements in $bannerGroups, which we can print to the page:

demo.php


	'.$ban->html().'';
		}

	?>

With all the markup generated and styled, we can move on with the jQuery part of the tutorial.

The Hover State

Step 4 – jQuery

After including the jQuery library to the page, we can start writing our own JavaScript code in script.js.

script.js

$(document).ready(function(){

	// Lowering the opacity of all slide in divs
	$('.banner div').css('opacity',0.4);

	// Using the hover method
	$('.banner').hover(function(){

		// Executed on mouseenter

		var el = $(this);

		// Find all the divs inside the banner div,
		// and animate them with the new size

		el.find('div').stop().animate({width:200,height:200},'slow',function(){
			// Show the "Visit Company" text:
			el.find('p').fadeIn('fast');
		});

	},function(){

		// Executed on moseleave

		var el = $(this);

		// Hiding the text
		el.find('p').stop(true,true).hide();

		// Animating the divs
		el.find('div').stop().animate({width:60,height:60},'fast');

	}).click(function(){

		// When clicked, open a tab with the address of the hyperlink

		window.open($(this).find('a').attr('href'));

	});
});

Using the hover method, we bind two functions to the mouseenter and the mouseleave events. These respectively show and hide the four rounded divs and the paragraph tag.

Notice the use of the stop() function, which, as it name suggests, stops a running animation. Remember that if you need to stop a build-in effect like fadeOut(), you should pass two additional true parameters to the function.

Stopping animations is important, as firing a new animation before the old one has completed, will make them pile up, which is definitely not desired.

Finally, because the hyperlink is hidden below the divs and is thus unclickable, we listen to the click event on the main banner div, and open a new tab to the appropriate URL when the event occurs.

With this our simple banner rotating script is complete!

Conclusion

In this tutorial we demonstrated some of PHP’s OOP features, jQuery animations and some interesting CSS effects. You are free to modify this code and use it any way you like.

What do you think? How would you modify this script?

Simple Bookmarking App With PHP, JS & MySQL

Martin Angelov — Wed, 14 Apr 2010 17:37:13 +0000

Part of the developer’s life, is to strive for simplicity in every aspect of their work. When searching for solutions to common problems, you have the choice to lock yourself into all kinds of third party services and API’s, or take the opportunity and develop the functionality yourself.

In this week’s tutorial, we are making a simple link sharing app. This app will give you the ability to instantly share any web page, with a single click of a bookmarklet in your bookmarks bar, and display it in a widget on your site.

The idea

Clicking the bookmarklet includes a PHP script (evaluated as a JavaScript file) to the page you are viewing, with the title and the URL passed as GET parameters. The PHP script writes the page data to the MySQL database, and outputs a success message that is treated as JavaScript code and executed by the browser.

The Idea

The database schema

Before moving to any development work, we need to create the database table that will hold all the bookmarks. The table definition is stored in table.sql in the download zip. You can run it in the SQL section of phpMyAdmin to recreate the table on your server. After this remember to change the MySQL login details in connect.php.

Database Schema

Notice the HASH column. This is a unique field that stores the md5() sum of the URL field. We are using this to ensure that there are no duplicate links in the database. Inserting a link that already exists, will cause the query to fail and the mysql_affected_rows() function will return 0. We are using this in the PHP section of the tut to determine what message is going to be displayed to the user, as you will see in a few moments.

Step 1 – XHTML

XHTML markup is generated on the fly by PHP. It is only needed when presenting the shared links on your website. It is basically a simple unordered list with each shared page being a li element inside it.

demo.php



      

      
          Perfection kills
          36 seconds ago
      
      
          The HTML5 test - How well does your browser support HTML5?
          2 minutes ago

The li elements are generated after PHP runs a query against the database for the latest bookmarks, as you will see in step 3. Each li contains the title of the page and the relative time since the bookmark was added. We will get back go this in the PHP part of the tutorial.

Step 2 – CSS

Again, the CSS code is only needed in the presentation part. You can modify the styling to match the rest of your site or ignore this code completely. Also, not all the styles are given here. You can see the rest in styles.css in the download archive.

styles.css

ul.latestSharesUL{
	/* The bookmark widet */
	background-color:#f5f5f5;
	margin:0 auto;
	padding:10px;
	width:280px;
	border:1px solid #e0e0e0;
	text-shadow:1px 1px 0 white;

	font-size:13px;
	color:#666;
	font-family:Arial, Helvetica, sans-serif;
}

ul.latestSharesUL li{
	/* Each bookmark entry */
	background-color:#FAFAFA;
	border:1px solid #EAEAEA;
	border-bottom:none;
	list-style:none;
	padding:12px;
}

ul.latestSharesUL li:last-child{
	/* Targeting the last element of the set */
	border-bottom:1px solid #EAEAEA;
}

ul.latestSharesUL,
ul.latestSharesUL li{
	/* Adding regular and inset shadows */
	-moz-box-shadow:1px 1px 0 white inset, 0 0 2px white;
	-webkit-box-shadow:1px 1px 0 white inset, 0 0 2px white;
	box-shadow:1px 1px 0 white inset, 0 0 2px white;
}

.dt{
	/* The date time field */
	font-size:10px;
	padding-top:10px;
	color:#888;
}

a.bookmrk,
a.bookmrk:visited{
	/* The bookmark title in the widget */
	color:#666;
}

By using the box-shadow and border-radius CSS3 properties, we are cutting down on the number of divs that would otherwise be needed to achieve the same design. Also notice the use of the :last-child selector, which targets the last li in the unordered list, and adds a bottom border.

The Bookmark Widget

Step 3 – PHP

First lets take a look at how the links are saved. As mentioned earlier, clicking the bookmarklet includes bookmark.php as a script in the head section of the current page. As it is served with a JavaScript content type, the browser will evaluate it as a regular JS file.

bookmark.php

// Setting the content-type header to javascript:
header('Content-type: application/javascript');

// Validating the input data
if(empty($_GET['url']) || empty($_GET['title']) || !validateURL($_GET['url'])) die();

// Sanitizing the variables
$_GET['url'] = sanitize($_GET['url']);
$_GET['title'] = sanitize($_GET['title']);

// Inserting, notice the use of the hash field and the md5 function:
mysql_query("	INSERT INTO bookmark_app (hash,url,title)
				VALUES (
					'".md5($_GET['url'])."',
					'".$_GET['url']."',
					'".$_GET['title']."'
				)");

$message = '';
if(mysql_affected_rows($link)!=1)
{
	$message = 'This URL already exists in the database!';
}
else
$message = 'The URL was shared!';

The document title and URL are passed to this script by the bookmarklet and are available in the $_GET array. The data is sanitized and validated with our custom made sanitize() function, after which it is inserted in the database. Then, after checking the status of the mysql_affected_rows() function, we assign to the $message variable the appropriate status message that is going to be displayed to the user.

I would suggest to take a quick look at bookmark.php in the download zip, to see how PHP and JavaScript work together to successfully insert the bookmark and output the result.

Now lets move on to see how the bookmarks are displayed in a simple widget.

demo.php

$shares = mysql_query("SELECT * FROM bookmark_app ORDER BY id DESC LIMIT 6");

while($row=mysql_fetch_assoc($shares))
{
	// Shortening the title if it is too long:
	if(mb_strlen($row['title'],'utf-8')>80)
		$row['title'] = mb_substr($row['title'],0,80,'utf-8').'..';

	// Outputting the list elements:
	echo '
	
		'.$row['title'].'
		'.relativeTime($row['dt']).'
	';
}

This code selects the last 6 shared links from the database, generates the appropriate LI elements containing the title as a hyperlink to the bookmarked page, and calculate the relative time since the entry was published with our custom made relativeTime() function.

The custom functions we are using are defined in functions.php.

functions.php

/* Helper functions */

function validateURL($str)
{
	return preg_match('/(http|ftp|https):\/\/[\w\-_]+(\.[\w\-_]+)+([\w\-\.,@?^=%&:\/~\+#]*[\w\-\@?^=%&\/~\+#])?/i',$str);
}

function sanitize($str)
{
	if(ini_get('magic_quotes_gpc'))
		$str = stripslashes($str);

	$str = strip_tags($str);
	$str = trim($str);
	$str = htmlspecialchars($str);
	$str = mysql_real_escape_string($str);

	return $str;
}

function relativeTime($dt,$precision=2)
{
	if(is_string($dt)) $dt = strtotime($dt);

	$times=array(	365*24*60*60	=> "year",
					30*24*60*60		=> "month",
					7*24*60*60		=> "week",
					24*60*60		=> "day",
					60*60			=> "hour",
					60				=> "minute",
					1				=> "second");

	$passed=time()-$dt;

	if($passed<5)
	{
		$output='less than 5 seconds ago';
	}
	else
	{
		$output=array();
		$exit=0;

		foreach($times as $period=>$name)
		{
			if($exit>=$precision || ($exit>0 && $period<60)) break;

			$result = floor($passed/$period);
			if($result>0)
			{
				$output[]=$result.' '.$name.($result==1?'':'s');
				$passed-=$result*$period;
				$exit++;
			}
			else if($exit>0) $exit++;
		}

		$output=implode(' and ',$output).' ago';
	}

	return $output;
}

One of the guiding principles when building web applications is “Do not trust your users”. This implies that all input data has to be properly escaped. This is exactly what the sanitize() function is doing – it prevents possible XSS attacks, strips any HTML tags and escapes all the HTML characters that could potentially break your markup when displayed.

The other interesting function is relativeTime(), which takes the timestamp field, assigned to each bookmark, and turns it into a user-friendly relative time string. It also takes an optional second argument, which limits the number of time units that are returned (setting precision to 1 will return 1 hour ago, instead of 1 hour and 10 minutes ago).

Step 4 – JavaScript

As the script is dynamically included in third party pages, it is not a good idea to rely on third party libraries like jQuery. This is why, for a change, we are going to work with pure JavaScript.

First, lets take a look at the bookmarklet code.

bookmarklet code

(function () {
	var jsScript = document.createElement('script');

	jsScript.setAttribute('type', 'text/javascript');
	jsScript.setAttribute('src', '/bookmark.php?url=' + encodeURIComponent(location.href) + '&title=' + encodeURIComponent(document.title));

	document.getElementsByTagName('head')[0].appendChild(jsScript);
})();

The bookmarklet is just a regular hyperlink, which has the code above preceded with the javascript: protocol as its href attribute. When clicked, the snippet creates a new script element, sets bookmark.php as its URL (along with the encoded title and URL of the currently active page), and appends it to the head section of the document. It is not as pretty as it would have been if we used the jQuery library, but it gets the job done.

Now lets return to bookmark.php.

bookmark.php

function displayMessage(str)
{
	// Using pure JavaScript to create and style a div element

	var d = document.createElement('div');

	with(d.style)
	{
		// Applying styles:

		position='fixed';
		width = '350px';
		height = '20px';
		top = '50%';
		left = '50%';
		margin = '-30px 0 0 -195px';
		backgroundColor = '#f7f7f7';
		border = '1px solid #ccc';
		color = '#777';
		padding = '20px';
		fontSize = '18px';
		fontFamily = '"Myriad Pro",Arial,Helvetica,sans-serif';
		textAlign = 'center';
		zIndex = 100000;

		textShadow = '1px 1px 0 white';

		MozBorderRadius = "12px";
		webkitBorderRadius = "12px";
		borderRadius = "12px";

		MozBoxShadow = '0 0 6px #ccc';
		webkitBoxShadow = '0 0 6px #ccc';
		boxShadow = '0 0 6px #ccc';
	}

	d.setAttribute('onclick','document.body.removeChild(this)');

    // Adding the message passed to the function as text:
	d.appendChild(document.createTextNode(str));

    // Appending the div to document
	document.body.appendChild(d);

    // The message will auto-hide in 3 seconds:

	setTimeout(function(){
		try{
			document.body.removeChild(d);
		}	catch(error){}
	},3000);
}

The JavaScript code above is right below the PHP logic that inserts the bookmark to the database in bookmark.php. The displayMessage() JavaScript function creates a div element, styles it and displays it in the center of the page.

As bookmark.php is evaluated as a JS file, every text that it outputs is treated as regular JavaScirpt code. As we mentioned in the PHP step, bookmark.php receives the document title and URL, inserts them in the database, and creates the $message variable. This is later outputted as a call to the displayMessage() function, which executes the above code and shows the message:

// Adding a line that will call the JavaScript function:
echo 'displayMessage("'.$message.'");';

With this our simple bookmarking app is complete!

Conclusion

If you plan to use this widget to share links with your visitors (or to save them for yourself) be sure to upload the script to a directory with a random name, as this script does not offer authentication. This is also the reason why it is so simple to set up and use.

What do you think? What do you plan to use it for?

Carbon Fiber Signup Form With PHP, jQuery and CSS3

Martin Angelov — Wed, 07 Apr 2010 14:28:51 +0000

Today we are making a carbon fiber – style form, build using progressive enhancement. This means that we first ensure that the form works well without JavaScript and fancy CSS support (think of IE6 here) and later move on by layering over cool styling, AJAX and jQuery magic.

The form features its own custom tooltip validation, and is even perfectly usable with JavaScript disabled.

Step 1 – XHTML

The first step includes creating the XHTML backbone of the form. It has to be simple, and, according to the principles defined by progressive enhancement, must be perfectly usable by itself.

demo.html


	Signup

The carbonForm div is the main container for the form. It is centered in the middle of the page with the CSS margin property, and then centered vertically with jQuery (take a look at our MicroTut for more info about centering).

Inside it we have the heading and the form with the fieldContainer div. Inside it there are three formRow divs, which share the markup given below:

demo.html


	
		Name:

Each pair of label and input elements is positioned inside its own wrapping divs, which are floated to the left. This allows for the layout of the form you can see in the demonstration page. It is important to have the text box names the same as their ids, because this is used to display the error tooltips as you will see in the next steps.

Carbon Fiber Signup Form

Step 2 – CSS

The form relies heavily on CSS to achieve the carbon fiber effect. A number of CSS3 rules are used as well, which successfully mimic the effects previously possible only in graphic suites as Photoshop. Only the most interesting styles are given here, you can see the rest in styles.css in the download archive.

styles.css

#carbonForm{
	/* The main form container */
	background-color:#1C1C1C;
	border:1px solid #080808;
	margin:20px auto;
	padding:20px;
	width:500px;

	-moz-box-shadow:0 0 1px #444 inset;
	-webkit-box-shadow:0 0 1px #444 inset;
	box-shadow:0 0 1px #444 inset;
}

.fieldContainer{
	/* The light rounded section, which contans the fields */
	background-color:#1E1E1E;
	border:1px solid #0E0E0E;
	padding:30px 10px;

	/* CSS3 box shadow, used as an inner glow */
	-moz-box-shadow:0 0 20px #292929 inset;
	-webkit-box-shadow:0 0 20px #292929 inset;
	box-shadow:0 0 20px #292929 inset;
}

#carbonForm,.fieldContainer,.errorTip{
	/* Rounding the divs at once */
	-moz-border-radius:12px;
	-webkit-border-radius:12px;
	border-radius:12px;
}

.formRow{
	height:35px;
	padding:10px;
	position:relative;
}

.label{
	float:left;
	padding:0 20px 0 0;
	text-align:right;
	width:70px;
}

label{
	font-family:Century Gothic,Myriad Pro,Arial,Helvetica,sans-serif;
	font-size:11px;
	letter-spacing:1px;
	line-height:35px; /* Neat line height trick */
}

.field{
	float:left;
}

.field input{
	/* The text boxes */
	border:1px solid white;
	color:#666666;
	font-family:Arial,Helvetica,sans-serif;
	font-size:22px;
	padding:4px 5px;
	background:url("img/box_bg.png") repeat-x scroll left top #FFFFFF;
	outline:none;
}

#submit{
	/* The submit button */
	border:1px solid #f4f4f4;
	cursor:pointer;
	height:40px;
	text-indent:-9999px;
	text-transform:uppercase;
	width:110px;

	background:url("img/submit.png") no-repeat center center #d0ecfd;

	-moz-border-radius:6px;
	-webkit-border-radius:6px;
	border-radius:6px;
}

#submit.active{
	/* Marking the submit button as active adds the preloader gif as background */
	background-image:url("img/preloader.gif");
}

input:hover,
input:focus{
	/* CSS3 glow effect */
	-moz-box-shadow:0 0 8px lightblue;
	-webkit-box-shadow:0 0 8px lightblue;
	box-shadow:0 0 8px lightblue;
}

Most of these rules are pretty straightforward. You may find interesting how we handle the submit button, as this element is quite tricky to style consistently cross-browser.

To hide the text of the button (in our case “Signup“), we can use the negative text-indent trick, but in IE it only works if we also specify the text-transform:uppercase rule. We also add a transparent background image consisting of the text “Submit” in Century Gothic, which is replaced with a rotating gif preloader if the button is assigned an “active” class.

We also use a number of CSS3 effects along with their vendor-specific versions for better compatibility. border-radius is for rounded corners, and with box-shadow we can mimic different glow and shadow effects.

CSS3 Rounded Corners & Glow

Step 3 – jQuery

After including the jQuery library and our own script.js file in the page, we can move on to writing the JavaScript code that will breathe some life into the form.

script.js

$(document).ready(function(){
	// $(document).ready() is executed after the page DOM id loaded

	// Binding an listener to the submit event on the form:
	$('#signupForm').submit(function(e){

		// If a previous submit is in progress:
		if($('#submit').hasClass('active')) return false;

		// Adding the active class to the button. Will show the preloader gif:
		$('#submit').addClass('active');

		// Removing the current error tooltips
		$('.errorTip').remove();

		// Issuing a POST ajax request to submit.php (the action attribute of the form):
		$.post($('#signupForm').attr('action'),
			$('#signupForm').serialize()+'&fromAjax=1',function(response){

			if(!response.status)
			{
				// Some kind of input error occured

				// Looping through all the input text boxes,
				// and checking whether they produced an error
				$('input[type!=submit]').each(function(){
					var elem = $(this);
					var id = elem.attr('id');

					if(response[id])
						showTooltip(elem,response[id]);
				});
			}
			else location.replace(response.redirectURL);

			$('#submit').removeClass('active');
		},'json');

		e.preventDefault();
	});

	$(window).resize();
});

// Centering the form vertically on every window resize:
$(window).resize(function(){
	var cf = $('#carbonForm');

	$('#carbonForm').css('margin-top',($(window).height()-cf.outerHeight())/2)
});

// Helper function that creates an error tooltip:
function showTooltip(elem,txt)
{
	// elem is the text box, txt is the error text
	$('').html(txt).appendTo(elem.closest('.formRow'));
}

Clicking the submit button (or pressing the enter key while entering text in one of the fields) submits the form. The function that is bound to the submit event prevents this from happening with e.preventDefault() and issues an AJAX request to submit.php instead.

The response that is returned is evaluated as JSON code (a JavaScript object), which contains a special status property. Depending on its value, the script either shows error tooltips on the fields, or redirects the browser to the specified URL in the response.

sample error response

{
	"status"	: 0,	// Indicates that the response is an error
	"email"		: "Please fill in a valid email!",		// Error message
	"pass"		: "Please fill in a valid password!"	// Error message
}

The error tooltips are generated by the script while looping though all the fields in the form and checking whether their ids exist as properties in the response object. If they do, a tooltip is created with the showTooltip() function.

Also notice how we use the serialize() method on line 18 to send all the form fields at once. Also, on this same line, we set fromAjax=1, which is going to tell PHP to return the response as JSON.

Now lets see how this response is generated and how the form is validated.

Dynamically Inserted Error Tooltips

Step 4 – PHP

The good thing about this form is that it is usable even if JavaScript is disabled. This works, because the action attribute of the form element is also set to submit.php. This means that we only have to implement the validation once no matter how the form is sent.

submit.php

// Error reporting:
error_reporting(E_ALL^E_NOTICE);

// This is the URL your users are redirected,
// when registered succesfully:

$redirectURL = 'http://demo.tutorialzine.com/2010/04/carbon-signup-form/demo.html';

$errors = array();

// Checking the input data and adding potential errors to the $errors array:

if(!$_POST['name'] || strlen($_POST['name'])<3 || strlen($_POST['name'])>50)
{
	$errors['name']='Please fill in a valid name!
Must be between 3 and 50 characters.';
}

if(!$_POST['email'] || !preg_match("/^[\.A-z0-9_\-\+]+[@][A-z0-9_\-]+([.][A-z0-9_\-]+)+[A-z]{1,4}$/", $_POST['email']))
{
	$errors['email']='Please fill in a valid email!';
}

if(!$_POST['pass'] || strlen($_POST['pass'])<5)
{
	$errors['pass']='Please fill in a valid password!
Must be at least 5 characters long.';
}

// Checking whether the request was sent via AJAX
// (we manually send the fromAjax var with the AJAX request):

if($_POST['fromAjax'])
{
	if(count($errors))
	{
		$errString = array();
		foreach($errors as $k=>$v)
		{
			// The name of the field that caused the error, and the
			// error text are grouped as key/value pair for the JSON response:
			$errString[]='"'.$k.'":"'.$v.'"';
		}

		// JSON error response:
		die	('{"status":0,'.join(',',$errString).'}');
	}

	// JSON success response. Returns the redirect URL:
	echo '{"status":1,"redirectURL":"'.$redirectURL.'"}';

	exit;
}

// If the request was not sent via AJAX (probably JavaScript
// has been disabled in the visitors' browser):

if(count($errors))
{
	echo ''.join('

',$errors).'';
	exit;
}

// Directly redirecting the visitor if JS is disabled:

header("Location: ".$redirectURL);

All the encountered errors are added to the $errors array. This, depending on whether fromAjax was set or not, is later returned either as a JSON object, or directly printed to the screen.

With this our carbon fiber signup form is complete!

Conclusion

You can modify and build upon this form any way you like. At present, the form does not actually register users, but you can add the code necessary to do so. It will also do a great job as a contact form for your site.

AJAX-ed Todo List With PHP, MySQL & jQuery

Martin Angelov — Wed, 31 Mar 2010 21:21:00 +0000

In this tutorial we are making a simple AJAX-ed Todo List App, with PHP, MySQL and jQuery. In the process we are going to demonstrate PHP’s OOP capabilities, play with jQuery UI and implement some nice AJAX functionality.

For a better understanding of the steps of this tutorial, you an go ahead and download the demo archive available from the button above.

Step 1 – PHP

As this is more of a developer-oriented tutorial, we are going to start with the PHP part. Unlike previous tutorials, this time we are leveraging the OOP features of PHP 5.

The author presumes you have a basic understanding of the core concepts behind object oriented programming, and PHP 5′s OOP implementation. For a quick reference, check out these pages of PHP’s documentation: OOP Basics, Static Methods, Exceptions, Magic Methods.

All of the functionality available to the end user – creating, editing, deleting and reordering the todo items – is implemented as different methods of a class, explained in detail below.

todo.class.php – Part 1

/* Defining the ToDo class */

class ToDo{

	/* An array that stores the todo item data: */

	private $data;

	/* The constructor */
	public function __construct($par){
		if(is_array($par))
			$this->data = $par;
	}

	/*
		This is an in-build "magic" method that is automatically called
		by PHP when we output the ToDo objects with echo.
	*/

	public function __toString(){

		// The string we return is outputted by the echo statement

		return '
			

				'.$this->data['text'].'

				
					Edit
					Delete
				

			';
	}

The constructor takes the array passed as a parameter and stores it in the $data property of the class. This array is a row fetched from the database with mysql_fetch_assoc() and contains the id and the text of the todo item.

After this is the magic __toString() method, which is called internally when we attempt to echo out an object of this class. The string it returns contains the markup used by each todo item – a

element with a unique id and a classname “todo”, inside of which we have the text of the todo and the two action hyperlinks.

AJAX, jQuery & CSS3 To Do List

todo.class.php – Part 2

	/*
		The edit method takes the ToDo item id and the new text
		of the ToDo. Updates the database.
	*/

	public static function edit($id, $text){

		$text = self::esc($text);
		if(!$text) throw new Exception("Wrong update text!");

		mysql_query("	UPDATE tz_todo
						SET text='".$text."'
						WHERE id=".$id
					);

		if(mysql_affected_rows($GLOBALS['link'])!=1)
			throw new Exception("Couldn't update item!");
	}

	/*
		The delete method. Takes the id of the ToDo item
		and deletes it from the database.
	*/

	public static function delete($id){

		mysql_query("DELETE FROM tz_todo WHERE id=".$id);

		if(mysql_affected_rows($GLOBALS['link'])!=1)
			throw new Exception("Couldn't delete item!");
	}

	/*
		The rearrange method is called when the ordering of
		the todos is changed. Takes an array parameter, which
		contains the ids of the todos in the new order.
	*/

	public static function rearrange($key_value){

		$updateVals = array();
		foreach($key_value as $k=>$v)
		{
			$strVals[] = 'WHEN '.(int)$v.' THEN '.((int)$k+1).PHP_EOL;
		}

		if(!$strVals) throw new Exception("No data!");

		// We are using the CASE SQL operator to update the ToDo positions en masse:

		mysql_query("	UPDATE tz_todo SET position = CASE id
						".join($strVals)."
						ELSE position
						END");

		if(mysql_error($GLOBALS['link']))
			throw new Exception("Error updating positions!");
	}

The definition of the class continues with a number of static methods. Those are special methods, which can be accessed without the need of an object of the class to be created. For example, you can call the edit method by writing: ToDo::edit($par1,$par2).

Notice how we are using exceptions to handle errors. When an exception occurs the script execution halts and it is up to the rest of the script to catch it and output the appropriate status.

Also you may find interesting the way we are updating the database with the new positions of the todo items. We are using the CASE operator, available in MySQL. This way, no matter how many todos are in the database, we execute only one query.

Saving queries and optimizing your scripts, although tedious, is hugely beneficial in the long run. You can read more about the CASE operator (among other interesting features) in MySQL’s official documentation.

todo.class.php – Part 3

	/*
		The createNew method takes only the text of the todo as a parameter,
		writes to the database and outputs the new todo back to
		the AJAX front-end.
	*/

	public static function createNew($text){

		$text = self::esc($text);
		if(!$text) throw new Exception("Wrong input data!");

		$posResult = mysql_query("SELECT MAX(position)+1 FROM tz_todo");

		if(mysql_num_rows($posResult))
			list($position) = mysql_fetch_array($posResult);

		if(!$position) $position = 1;

		mysql_query("INSERT INTO tz_todo SET text='".$text."', position = ".$position);

		if(mysql_affected_rows($GLOBALS['link'])!=1)
			throw new Exception("Error inserting TODO!");

		// Creating a new ToDo and outputting it directly:

		echo (new ToDo(array(
			'id'	=> mysql_insert_id($GLOBALS['link']),
			'text'	=> $text
		)));

		exit;
	}

	/*
		A helper method to sanitize a string:
	*/

	public static function esc($str){

		if(ini_get('magic_quotes_gpc'))
			$str = stripslashes($str);

		return mysql_real_escape_string(strip_tags($str));
	}

} // closing the class definition

Accessing static methods from the same class can easily be done with the self:: keyword. This way we are using the esc() method to sanitize the incoming user data.

Also notice the createNew() method. In it, after running the INSERT query on the database, we use the returned auto-assigned unique id with mysql_insert_id() and create a new todo object, which is then echoed out to the front end.

Now lets take a look at how this class is used.

demo.php – Part 1

// Select all the todos, ordered by position:
$query = mysql_query("SELECT * FROM `tz_todo` ORDER BY `position` ASC");

$todos = array();

// Filling the $todos array with new ToDo objects:

while($row = mysql_fetch_assoc($query)){
	$todos[] = new ToDo($row);
}

After including todo.class.php in demo.php, we select the todo items and loop through the MySQL result set, filling in the $todos array with objects.

demo.php – Part 2

// Looping and outputting the $todos array. The __toString() method
// is used internally to convert the objects to strings:

foreach($todos as $item){
	echo $item;
}

Later in the page, these objects are echoed out. Thanks to the __toString() method discussed above, all the markup is automatically generated, so we do not have to deal with any of that.

The front end issues a number of different AJAX calls. Making a separate file to handle each of them would be a bit of overkill, so the best solution is to group them in a single AJAX handling file. This is done in ajax.php, which you can see below.

ajax.php

$id = (int)$_GET['id'];

try{

	switch($_GET['action'])
	{
		case 'delete':
			ToDo::delete($id);
			break;

		case 'rearrange':
			ToDo::rearrange($_GET['positions']);
			break;

		case 'edit':
			ToDo::edit($id,$_GET['text']);
			break;

		case 'new':
			ToDo::createNew($_GET['text']);
			break;
	}

}
catch(Exception $e){
//	echo $e->getMessage();
	die("0");
}

echo "1";

With the help of a switch statement, we decide which of the static methods of the ToDo class to execute. If an error occurs in one of these methods, an exception is dispatched. Because the whole switch is enclosed in a try statement, execution of the script halts and control is passed to the catch statement, which outputs a zero and exits the script.

You could potentially echo (or write to a log) exactly what kind of error occurred by uncommenting line 26.

Step 2 – MySQL

The tz_todo table holds and assigns the unique ids of the todo items (via the auto_increment setting of the field), the position, the text and the dt_added timestamp.

Database Schema

You can find the SQL that will recreate the table in table.sql in the download archive. Also, if you plan to run the demo on your own server, don’t forget to fill in your login details in connect.php.

Step 3 – XHTML

As most of the markup is generated by PHP, we are left with taking care of the rest of the page’s XHTML. First we need to include jQuery, jQuery UI, and the stylesheets in the document. It is considered a good practice to include the stylesheets to the head section, and the JavaScript files right before the closing tag.

After this we can move on to coding the rest of the page.

demo.php



	

	

	

	Add a ToDo




Are you sure you want to delete this TODO item?

Each todo is a li item inside of the todoList unordered list. This way, we can later use the sortable method of jQuery UI to easily convert it into an interactive sortable element. Also, in the process, we enhance the semantic value of the code.

Step 4 – CSS

Now lets move on to the styling of the todos. Only parts of the original stylesheet are given here for better readability. You can find the rest in styles.css in the download archive.

styles.css – Part 1

/* The todo items are grouped into an UL unordered list */

ul.todoList{
	margin:0 auto;
	width:500px;
	position:relative;
}

ul.todoList li{
	background-color:#F9F9F9;
	border:1px solid #EEEEEE;
	list-style:none;
	margin:6px;
	padding:6px 9px;
	position:relative;
	cursor:n-resize;

	/* CSS3 text shadow and rounded corners: */

	text-shadow:1px 1px 0 white;

	-moz-border-radius:6px;
	-webkit-border-radius:6px;
	border-radius:6px;
}

ul.todoList li:hover{
	border-color:#9be0f9;

	/* CSS3 glow effect: */
	-moz-box-shadow:0 0 5px #A6E5FD;
	-webkit-box-shadow:0 0 5px #A6E5FD;
	box-shadow:0 0 5px #A6E5FD;
}

The todoList ul is horizontally centered on the page and is assigned a relative positioning. The li elements inside it (the todo items) share a number of CSS3 rules. These, unfortunately, do not work in older browsers, but as they are solely for presentation purposes even browsers as old as IE6 can enjoy a fully working script, albeit not as pretty as intentioned.

styles.css – Part 2

/* The edit textbox */

.todo input{
	border:1px solid #CCCCCC;
	color:#666666;
	font-family:Arial,Helvetica,sans-serif;
	font-size:0.725em;
	padding:3px 4px;
	width:300px;
}

/* The Save and Cancel edit links: */

.editTodo{
	display:inline;
	font-size:0.6em;
	padding-left:9px;
}

.editTodo a{
	font-weight:bold;
}

a.discardChanges{
	color:#C00 !important;
}

a.saveChanges{
	color:#4DB209 !important;
}

In the second part of the code we style the input text box, shown when the todo item is edited, and the save and cancel links.

jQuery UI Dialog Box

Step 5 – jQuery

Moving to the JavaScript code. Here we are using two of jQuery UI’s user interface components – sortable, and dialog. These alone save us at least a couple of hours of development time, which is one of the benefits of using a nicely thought out library like jQuery.

script.js – Part 1

$(document).ready(function(){
	/* The following code is executed once the DOM is loaded */

	$(".todoList").sortable({
		axis		: 'y',				// Only vertical movements allowed
		containment	: 'window',			// Constrained by the window
		update		: function(){		// The function is called after the todos are rearranged

			// The toArray method returns an array with the ids of the todos
			var arr = $(".todoList").sortable('toArray');

			// Striping the todo- prefix of the ids:

			arr = $.map(arr,function(val,key){
				return val.replace('todo-','');
			});

			// Saving with AJAX
			$.get('ajax.php',{action:'rearrange',positions:arr});
		}
	});

	// A global variable, holding a jQuery object
	// containing the current todo item:

	var currentTODO;

	// Configuring the delete confirmation dialog
	$("#dialog-confirm").dialog({
		resizable: false,
		height:130,
		modal: true,
		autoOpen:false,
		buttons: {
			'Delete item': function() {

				$.get("ajax.php",{"action":"delete","id":currentTODO.data('id')},function(msg){
					currentTODO.fadeOut('fast');
				})

				$(this).dialog('close');
			},
			Cancel: function() {
				$(this).dialog('close');
			}
		}
	});

To display the dialog, we need to have a base div, which is going to be converted to a dialog. The contents of the div is going to be displayed as the text of the dialog, and the contents of the title attribute of the div will become the title of the dialog window. You can find this div (id=dialog-confirm) in demo.php.

script.js – Part 2

	// When a double click occurs, just simulate a click on the edit button:
	$('.todo').live('dblclick',function(){
		$(this).find('a.edit').click();
	});

	// If any link in the todo is clicked, assign
	// the todo item to the currentTODO variable for later use.

	$('.todo a').live('click',function(e){

		currentTODO = $(this).closest('.todo');
		currentTODO.data('id',currentTODO.attr('id').replace('todo-',''));

		e.preventDefault();
	});

	// Listening for a click on a delete button:

	$('.todo a.delete').live('click',function(){
		$("#dialog-confirm").dialog('open');
	});

	// Listening for a click on a edit button

	$('.todo a.edit').live('click',function(){

		var container = currentTODO.find('.text');

		if(!currentTODO.data('origText'))
		{
			// Saving the current value of the ToDo so we can
			// restore it later if the user discards the changes:

			currentTODO.data('origText',container.text());
		}
		else
		{
			// This will block the edit button if the edit box is already open:
			return false;
		}

		$('').val(container.text()).appendTo(container.empty());

		// Appending the save and cancel links:
		container.append(
			''+
				'Save or Cancel'+
			''
		);

	});

Notice the use of the jQuery live() method to bind events. We are using live(), instead of bind(), because live() can listen for events on any elements, even those who do not yet exist. This way we make sure that all the todo items added in the future to the page by the user, will also trigger the same event handlers, as the currently existing ones.

script.js – Part 3

	// The cancel edit link:

	$('.todo a.discardChanges').live('click',function(){
		currentTODO.find('.text')
					.text(currentTODO.data('origText'))
					.end()
					.removeData('origText');
	});

	// The save changes link:

	$('.todo a.saveChanges').live('click',function(){
		var text = currentTODO.find("input[type=text]").val();

		$.get("ajax.php",{'action':'edit','id':currentTODO.data('id'),'text':text});

		currentTODO.removeData('origText')
					.find(".text")
					.text(text);
	});

	// The Add New ToDo button:

	var timestamp;
	$('#addButton').click(function(e){

		// Only one todo per 5 seconds is allowed:
		if(Date.now() - timestamp<5000) return false;

		$.get("ajax.php",{'action':'new','text':'New Todo Item. Doubleclick to Edit.'},function(msg){

			// Appending the new todo and fading it into view:
			$(msg).hide().appendTo('.todoList').fadeIn();
		});

		// Updating the timestamp:
		timestamp = Date.now();

		e.preventDefault();
	});

}); // Closing $(document).ready()

In the last part of the code we are binding events to the Save and Cancel links, which are added to the todo when editing it. We also set up an event listener for the “Add” button. Notice how we prevent flooding by limiting the submit rate of new todos to one every 5 seconds.

With this our AJAX-ed To Do List is complete!

Conclusion

Today we created a simple AJAX enabled ToDo web script with PHP, MySQL and jQuery. You can use it to create your own task management application or turn it into a fully fledged web app.

What do you think? How would you modify this code?

Sponsor Flip Wall With jQuery & CSS

Martin Angelov — Wed, 24 Mar 2010 19:40:29 +0000

Designing and coding a sponsors page is part of the developer’s life (at least the lucky developer’s life, if it is about a personal site of theirs). It, however, follows different rules than those for the other pages of the site. You have to find a way to fit a lot of information and organize it clearly, so that the emphasis is put on your sponsors, and not on other elements of your design.

We are using PHP, CSS and jQuery with the jQuery Flip plug-in, to do just that. The resulting code can be used to showcase your sponsors, clients or portfolio projects as well.

Step 1 – XHTML

Most of the markup is generated by PHP for each of the sponsors after looping the main $sponsor array. Below you can see the code that would be generated and outputted for Google:

demo.php


	
		
	

	
		
			The company that redefined web search.
		
		
			http://www.google.com/

The outermost .sponsor div contains two additional div elements. The first – sponsorFlip – contains the company logo. Every click on this element causes the Flip effect to be initiated, as you will see in the jQuery part of the tutorial.

Maybe more interesting is the sponsorData div. It is hidden from view with a display:none CSS rule, but is accessible to jQuery. This way we can pass the description and the URL of the sponsoring company to the front end. After the flipping animation is complete, the contents of this div is dynamically inserted into sponsorFlip.

Sponsor Flip Wall

Step 2 – CSS

We can start laying down the styling of the wall, as without it there is no much use of the page. The code is divided in two parts. Some classes are omitted for clarity. You can see all the styles used by the demo in styles.css in the download archive.

styles.css – Part 1

body{
	/* Setting default text color, background and a font stack */
	font-size:0.825em;
	color:#666;
	background-color:#fff;
	font-family:Arial, Helvetica, sans-serif;
}

.sponsorListHolder{
	margin-bottom:30px;
}

.sponsor{
	width:180px;
	height:180px;
	float:left;
	margin:4px;

	/* Giving the sponsor div a relative positioning: */
	position:relative;
	cursor:pointer;
}

.sponsorFlip{
	/*  The sponsor div will be positioned absolutely with respect
		to its parent .sponsor div and fill it in entirely */

	position:absolute;
	left:0;
	top:0;
	width:100%;
	height:100%;
	border:1px solid #ddd;
	background:url("img/background.jpg") no-repeat center center #f9f9f9;
}

.sponsorFlip:hover{
	border:1px solid #999;

	/* CSS3 inset shadow: */
	-moz-box-shadow:0 0 30px #999 inset;
	-webkit-box-shadow:0 0 30px #999 inset;
	box-shadow:0 0 30px #999 inset;
}

After styling the sponsor and sponsorFlip divs, we add a :hover state for the latter. We are using CSS3 inset box-shadow to mimic the inner shadow effect you may be familiar with from Photoshop. At the moment of writing inset shadows only work in the latest versions of Firefox, Opera and Chrome, but being primarily a visual enhancement, without it the page is still perfectly usable in all browsers.

styles.css – Part 2

.sponsorFlip img{
	/* Centering the logo image in the middle of the .sponsorFlip div */

	position:absolute;
	top:50%;
	left:50%;
	margin:-70px 0 0 -70px;
}

.sponsorData{
	/* Hiding the .sponsorData div */
	display:none;
}

.sponsorDescription{
	font-size:11px;
	padding:50px 10px 20px 20px;
	font-style:italic;
}

.sponsorURL{
	font-size:10px;
	font-weight:bold;
	padding-left:20px;
}

.clear{
	/* This class clears the floats */
	clear:both;
}

As mentioned earlier, the sponsorData div is not meant for viewing, so it is hidden with display:none. Its purpose is to only store the data which is later extracted by jQuery and displayed at the end of the flipping animation.

Flipping Animation

Step 3 – PHP

You have many options in storing your sponsors data – in a MySQL database, XML document or even a plain text file. These all have their benefits and we’ve used all of them in the previous tutorials (except XML storage, note to self).

However, the sponsor data is not something that changes often. This is why a different approach is needed. For the purposes of the task at hand, we are using a multidimensional array with all the sponsor information inside it. It is easy to update and even easier to implement:

demo.php – Part 1

// Each sponsor is an element of the $sponsors array:

$sponsors = array(
	array('facebook','The biggest social..','http://www.facebook.com/'),
	array('adobe','The leading software de..','http://www.adobe.com/'),
	array('microsoft','One of the top software c..','http://www.microsoft.com/'),
	array('sony','A global multibillion electronics..','http://www.sony.com/'),
	array('dell','One of the biggest computer develo..','http://www.dell.com/'),
	array('ebay','The biggest online auction and..','http://www.ebay.com/'),
	array('digg','One of the most popular web 2.0..','http://www.digg.com/'),
	array('google','The company that redefined w..','http://www.google.com/'),
	array('ea','The biggest computer game manufacturer.','http://www.ea.com/'),
	array('mysql','The most popular open source dat..','http://www.mysql.com/'),
	array('hp','One of the biggest computer manufacturers.','http://www.hp.com/'),
	array('yahoo','The most popular network of so..','http://www.yahoo.com/'),
	array('cisco','The biggest networking and co..','http://www.cisco.com/'),
	array('vimeo','A popular video-centric social n..','http://www.vimeo.com/'),
	array('canon','Imaging and optical technology ma..','http://www.canon.com/')
);

// Randomizing the order of sponsors:

shuffle($sponsors);

The sponsors are grouped into the main $sponsors array. Each sponsor entry is organized as a separate regular array. The first element of that array is the unique key of the sponsor, which corresponds to the file name of the logo. The second element is a description of the sponsor and the last is a link to the sponsor’s website.

After defining the array, we use the in-build shuffle() PHP function to randomize the order in which the sponsors are displayed.

demo.php – Part 2

// Looping through the array:

foreach($sponsors as $company)
{
	echo'
		
			
				
			

			
				
					'.$company[1].'
				
				
					'.$company[2].'
				
			
		

	';
}

The code above can be found halfway down demo.php. It basically loops through the shuffled $sponsors array and outputs the markup we discussed in step one. Notice how the different elements of the array are inserted into the template.

Step 4 – jQuery

The jQuery Flip plugin requires both the jQuery library and jQuery UI. So, after including those in the page, we can move on with writing the code that will bring our sponsor wall to life.

script.js

$(document).ready(function(){
	/* The following code is executed once the DOM is loaded */

	$('.sponsorFlip').bind("click",function(){

		// $(this) point to the clicked .sponsorFlip element (caching it in elem for speed):

		var elem = $(this);

		// data('flipped') is a flag we set when we flip the element:

		if(elem.data('flipped'))
		{
			// If the element has already been flipped, use the revertFlip method
			// defined by the plug-in to revert to the default state automatically:

			elem.revertFlip();

			// Unsetting the flag:
			elem.data('flipped',false)
		}
		else
		{
			// Using the flip method defined by the plugin:

			elem.flip({
				direction:'lr',
				speed: 350,
				onBefore: function(){
					// Insert the contents of the .sponsorData div (hidden
					// from view with display:none) into the clicked
					// .sponsorFlip div before the flipping animation starts:

					elem.html(elem.siblings('.sponsorData').html());
				}
			});

			// Setting the flag:
			elem.data('flipped',true);
		}
	});

});

First we bind a function as a listener for the click event on the .sponsorFlip divs. After a click event occurs, we check whether the flipped flag is set via the jquery data() method. This flag is set individually for each sponsorFlip div and helps us determine whether the div has already been flipped. If this is so, we use the revertFlip() method which is defined by the Flip plugin. It returns the div to its previous state.

If the flag is not present, however, we initiate a flip on the element. As mentioned earlier, the .sponsorData div, which is contained in every sponsor div, contains the description and the URL of the sponsor, and is hidden from view with CSS. Before the flipping starts, the plug-in executes the onBefore function we define in the configuration object that is passed as a parameter (line 29). In it we change the content of the sponsorFlip div to the one of sponsorData div, which replaces the logo image with information about the sponsor.

With this our sponsor flip wall is complete!

Conclusion

Today we used the jQuery Flip plug-in to build a sponsor wall for your site. You can use this example to bring interactivity to your site’s pages. And as the data for the wall is read from an array, you can easily modify it to work with any kind of database or storage.

What do you think? How would you modify this code?

“Who Is Online” Widget With PHP, MySQL & jQuery

Martin Angelov — Tue, 02 Mar 2010 22:37:22 +0000

For this week’s tutorial, we are taking a look at our ever-so-interesting inbox. It all started with a letter from one of our readers a couple of weeks ago:

My boss is always coming into my office asking me to install things on our client’s sites. One of the items that’s been coming up more and more is “How can we tell who’s currently online?” So, the next time you need a tutorial idea, there you go – a php/mysql/jquery ‘online users’ widget. Oh, and a geomap of each visitor would be super rad too.

Thanks for everything you guys do,
Taylor

Taylor, we are always happy when we receive good tutorial ideas, so today we are doing just that – a “Who is online” widget with PHP, MySQL & jQuery. It will display the number of visitors, currently viewing your site, and thanks to Hostip’s free IP to location API, it will even be able to detect the country your visitors are from and display it in a slide out panel.

Step 1 – XHTML

As usual, we start off with the XHTML part. The code presented here might not look like much, but it is all that we need to show off all the work that has been done by the backend. The widget features a slick slide-out panel with all the geolocation data, shown on mouse over.

demo.html





	

	
	
	UNITED STATES
	2
	

	
	
	UNITED KINGDOM
	1
	



8
online

As you may see from the markup above, the main container div – “onlineWidget” contains the slide-out panel (the div with class name “panel“), the total number of people online (the “count” div), the “online” label and the green arrow to the right.

Geolocation-enabled Who Is Online Widget

The panel div is dynamically filled by AJAX with the countries with the most visitors currently online. The default content of this div is a rotating gif preloader, which is replaced with the geo data once the AJAX request is complete (usually in less than a second). We will come back to this in a moment.

Step 2 – The Database

Unlike the usual routine, here we are going to take a look at how the database is structured, as it is fundamental to the rest of the script.

All of the widget data is stored into the tz_who_is_online table. It consists of six fields (or columns). The first one – ID, is a standard primary key / auto increment field. After this is the IP field which stores the visitor’s IP address (converted to a integer beforehand with the ip2long PHP function).

After this are three fields fetched by Hostip’s API - Country, CountryCode and City. The widget is not using the city field at this point, but it is good to have in case somebody wants to implement it. Last is the DT timestamp field, which is updated on every page load and enables us to track who is online (users without a page load in the last 10 minutes have probably left the site).

Table Structure Of tz_who_is_online

Step 3 – CSS

The widget is (almost) image free, and is only styled with CSS. Lets take a look at the styling, as defined in styles.css. The code is divided in two parts, so it is easier to follow.

who-is-online/styles.css – Part 1

.onlineWidget,.panel{

	/* Styling the widget and the sliding panel at once */

	background-color:#F9F9F9;
	border:2px solid #FFFFFF;
	height:25px;
	padding:4px 8px;
	position:relative;
	width:130px;

	cursor:pointer;

	/* CSS3 rules for rounded corners, box and text shadows: */

	-moz-border-radius:6px;
	-webkit-border-radius:6px;
	border-radius:6px;

	-moz-box-shadow:0 0 3px #CCCCCC;
	-webkit-box-shadow:0 0 3px #CCCCCC;
	box-shadow:0 0 3px #CCCCCC;

	text-shadow:0 2px 0 white;
}

.onlineWidget:hover{
	background-color:#fcfcfc;
}

.onlineWidget:hover .arrow{
	/* Changing the background image for the green arrow on hover: */
	background-position:bottom center;
}

.count{
	/* The total number of people online div */

	color:#777777;
	float:left;
	font-size:26px;
	font-weight:bold;
	margin-top:-3px;
	text-align:center;
	width:30px;
}

.label{
	/* The online label */

	float:left;
	font-size:10px;
	padding:7px 0 0 7px;
	text-transform:uppercase;
}

In the first step above, you can see that we style the widget and the slide-out panel at once. This is to ensure that they have consistent styling which is easy to change later on. Some rules are unique to the panel, however, so we include a individually targeted set of rules in the second part of the code.

We also define the hover state and style the label and count divs.

who-is-online/styles.css – Part 2

.arrow{
	/* The green arrow on the right */

	background:url(img/arrow.png) no-repeat top center;
	position:absolute;
	right:6px;

	width:25px;
	height:25px;
}

.panel{
	/* The slideout panel */

	position:absolute;
	cursor:default;

	bottom:50px;
	left:0;
	height:auto;
	display:none;
	margin:-2px;
	z-index:1000;
}

.preloader{
	/* The rotating gif preloader image */
	display:block;
	margin:10px auto;
}

.geoRow{
	/* The div that contains each country */

	height:16px;
	overflow:hidden;
	padding:2px 0;
}

.flag{
	float:left;
	margin:0 4px;
}

.country, .people{
	float:left;
	font-size:10px;
	padding:2px;
}

.country{
	width:85px;
	overflow:hidden;
}

.people{
	font-weight:bold;
}

In the second part of the file, we style the how the geolocation data that is presented in the slide-out panel, after jQuery fetches it from the back-end. With this we can continue with the next step.

CSS3 & jQuery Front End

Step 4 – PHP

This is where the magic happens. PHP has to keep the database of online users up to date and fetch IP-to-location data from Hostip’s API. This is later cached for future use in a cookie on the visitors PC.

who-is-online/online.php

require "connect.php";
require "functions.php";

// We don't want web bots altering our stats:
if(is_bot()) die();

$stringIp = $_SERVER['REMOTE_ADDR'];
$intIp = ip2long($stringIp);

// Checking wheter the visitor is already marked as being online:
$inDB = mysql_query("SELECT 1 FROM tz_who_is_online WHERE ip=".$intIp);

if(!mysql_num_rows($inDB))
{
	// This user is not in the database, so we must fetch
	// the geoip data and insert it into the online table:

	if($_COOKIE['geoData'])
	{
		// A "geoData" cookie has been previously set by the script, so we will use it

		// Always escape any user input, including cookies:
		list($city,$countryName,$countryAbbrev) = explode('|',mysql_real_escape_string(strip_tags($_COOKIE['geoData'])));
	}
	else
	{
		// Making an API call to Hostip:

		$xml = file_get_contents('http://api.hostip.info/?ip='.$stringIp);

		$city = get_tag('gml:name',$xml);
		$city = $city[1];

		$countryName = get_tag('countryName',$xml);
		$countryName = $countryName[0];

		$countryAbbrev = get_tag('countryAbbrev',$xml);
		$countryAbbrev = $countryAbbrev[0];

		// Setting a cookie with the data, which is set to expire in a month:
		setcookie('geoData',$city.'|'.$countryName.'|'.$countryAbbrev, time()+60*60*24*30,'/');
	}

	$countryName = str_replace('(Unknown Country?)','UNKNOWN',$countryName);

	mysql_query("	INSERT INTO tz_who_is_online (ip,city,country,countrycode)
					VALUES(".$intIp.",'".$city."','".$countryName."', '".$countryAbbrev."')");
}
else
{
	// If the visitor is already online, just update the dt value of the row:
	mysql_query("UPDATE tz_who_is_online SET dt=NOW() WHERE ip=".$intIp);
}

// Removing entries not updated in the last 10 minutes:
mysql_query("DELETE FROM tz_who_is_online WHERE dt
This PHP script is initially called by jQuery in order to populate the count div with the current number of people online. Behind the scenes, however, this script writes the visitor’s IP to the database and resolves their IP-to-location data.
This is the best strategy in organizing the back-end, as we keep the calls to the API (which are quite time expensive) distributed to each user as they visit the site for the first time.
The other alternative would be to store only the IPs of the visitors and queue the geolocation data once the panel is shown. This would mean to resolve a huge number of IPs simultaneously, which would make the script unresponsive and get us black-listed from the API. Totally not cool.
You can queue the Hostip’s API by opening a connection to a URL similar to this: http://api.hostip.info/?ip=128.128.128.128. It returns a valid XML response, which contains all sorts of data, including a country and city name associated with the IP, country abbreviation and even absolute coordinates. We are fetching this data with the PHP file_get_contents() function and extracting the bits of information we need.
who-is-online/geodata.php
require "connect.php";
require "functions.php";

// We don't want web bots accessing this page:
if(is_bot()) die();

// Selecting the top 15 countries with the most visitors:
$result = mysql_query("	SELECT countryCode,country, COUNT(*) AS total
						FROM tz_who_is_online
						GROUP BY countryCode
						ORDER BY total DESC
						LIMIT 15");

while($row=mysql_fetch_assoc($result))
{
	echo '
	
		
		'.$row['country'].'
		'.$row['total'].'
	
	';
}
Geodata.php is fetched by jQuery to populate the slide-out panel with location data. This file basically queues the database with a GROUP BY query, which groups the individual users by country and orders the resulting rows in a descending order, with the most popular countries at the top.
For the flag icons, we are using the famfamfam flag icon set, which is released as public domain. A great thing about the Hostip API, is that it returns the country code in a standard two letter format, which is also shared by the famfamfam icon set. This means that in the while loop, it is really easy to find the appropriate flag to show, by just lowering the case of the country abbreviation stored in the database and adding a gif extension.
Step 5 – jQuery
JavaScript manages the AJAX requests and slides the panel. This would be a daunting task with pure JS alone, which is why we are using the newest version of the jQuery library.
Now lets take a look at what the code looks like.
who-is-online/widget.js
$(document).ready(function(){
	// This function is executed once the document is loaded

	// Caching the jQuery selectors:
	var count = $('.onlineWidget .count');
	var panel = $('.onlineWidget .panel');
	var timeout;

	// Loading the number of users online into the count div with the load AJAX method:
	count.load('who-is-online/online.php');

	$('.onlineWidget').hover(
		function(){
			// Setting a custom 'open' event on the sliding panel:

			clearTimeout(timeout);
			timeout = setTimeout(function(){panel.trigger('open');},500);
		},
		function(){
			// Custom 'close' event:

			clearTimeout(timeout);
			timeout = setTimeout(function(){panel.trigger('close');},500);
		}
	);

	var loaded=false;	// A flag which prevents multiple AJAX calls to geodata.php;

	// Binding functions to custom events:

	panel.bind('open',function(){
		panel.slideDown(function(){
			if(!loaded)
			{
				// Loading the countries and the flags
				// once the sliding panel is shown:

				panel.load('who-is-online/geodata.php');
				loaded=true;
			}
		});
	}).bind('close',function(){
		panel.slideUp();
	});

});
You might be a bit perplexed with the use of setTimeout in the menu. This is done, so we have a bit of delay between the hovering of the mouse and the actual opening of the slide-out panel. This way, unintentional movements of the mouse cursor over the widget won’t fire the open event, and once opened, will not close it immediately once the mouse leaves it.
With this our widget is ready!
Setting up the demo
At this point you probably want to grab the widget and put it on your site. To make it work, you need to execute the SQL code found in table.sql in the download archive. It will create the tz_who_is_online table in your database, which is used by the widget. Later you need to upload the files to your server and include widget.js to the head section of your page (along with the jQuery  library). After this you have to fill your MySQL login details in connect.php and finally add the markup from demo.html to your web page.
Conclusion
Having access to real time data on your site userbase is a dream to any webmaster. Tools like Google Analytics give a great perspective on your site’s reach, but lack the real time feel a simple widget like this can provide.
What do you think? How would you modify this code?