summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/trackback.rst
diff options
context:
space:
mode:
Diffstat (limited to 'user_guide_src/source/libraries/trackback.rst')
-rw-r--r--user_guide_src/source/libraries/trackback.rst201
1 files changed, 201 insertions, 0 deletions
diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst
new file mode 100644
index 000000000..07b2b2177
--- /dev/null
+++ b/user_guide_src/source/libraries/trackback.rst
@@ -0,0 +1,201 @@
+###############
+Trackback Class
+###############
+
+The Trackback Class provides functions that enable you to send and
+receive Trackback data.
+
+If you are not familiar with Trackbacks you'll find more information
+`here <http://en.wikipedia.org/wiki/Trackback>`_.
+
+Initializing the Class
+======================
+
+Like most other classes in CodeIgniter, the Trackback class is
+initialized in your controller using the $this->load->library function::
+
+ $this->load->library('trackback');
+
+Once loaded, the Trackback library object will be available using:
+$this->trackback
+
+Sending Trackbacks
+==================
+
+A Trackback can be sent from any of your controller functions using code
+similar to this example::
+
+ $this->load->library('trackback');
+
+ $tb_data = array(
+ 'ping_url' => 'http://example.com/trackback/456',
+ 'url' => 'http://www.my-example.com/blog/entry/123',
+ 'title' => 'The Title of My Entry',
+ 'excerpt' => 'The entry content.',
+ 'blog_name' => 'My Blog Name',
+ 'charset' => 'utf-8'
+ );
+
+ if ( ! $this->trackback->send($tb_data))
+ {
+ echo $this->trackback->display_errors();
+ }
+ else
+ {
+ echo 'Trackback was sent!';
+ }
+
+Description of array data:
+
+- **ping_url** - The URL of the site you are sending the Trackback to.
+ You can send Trackbacks to multiple URLs by separating each URL with
+ a comma.
+- **url** - The URL to YOUR site where the weblog entry can be seen.
+- **title** - The title of your weblog entry.
+- **excerpt** - The content of your weblog entry. Note: the Trackback
+ class will automatically send only the first 500 characters of your
+ entry. It will also strip all HTML.
+- **blog_name** - The name of your weblog.
+- **charset** - The character encoding your weblog is written in. If
+ omitted, UTF-8 will be used.
+
+The Trackback sending function returns TRUE/FALSE (boolean) on success
+or failure. If it fails, you can retrieve the error message using::
+
+ $this->trackback->display_errors();
+
+Receiving Trackbacks
+====================
+
+Before you can receive Trackbacks you must create a weblog. If you don't
+have a blog yet there's no point in continuing.
+
+Receiving Trackbacks is a little more complex than sending them, only
+because you will need a database table in which to store them, and you
+will need to validate the incoming trackback data. You are encouraged to
+implement a thorough validation process to guard against spam and
+duplicate data. You may also want to limit the number of Trackbacks you
+allow from a particular IP within a given span of time to further
+curtail spam. The process of receiving a Trackback is quite simple; the
+validation is what takes most of the effort.
+
+Your Ping URL
+=============
+
+In order to accept Trackbacks you must display a Trackback URL next to
+each one of your weblog entries. This will be the URL that people will
+use to send you Trackbacks (we will refer to this as your "Ping URL").
+
+Your Ping URL must point to a controller function where your Trackback
+receiving code is located, and the URL must contain the ID number for
+each particular entry, so that when the Trackback is received you'll be
+able to associate it with a particular entry.
+
+For example, if your controller class is called Trackback, and the
+receiving function is called receive, your Ping URLs will look something
+like this::
+
+ http://example.com/index.php/trackback/receive/entry_id
+
+Where entry_id represents the individual ID number for each of your
+entries.
+
+Creating a Trackback Table
+==========================
+
+Before you can receive Trackbacks you must create a table in which to
+store them. Here is a basic prototype for such a table::
+
+ CREATE TABLE trackbacks (
+ tb_id int(10) unsigned NOT NULL auto_increment,
+ entry_id int(10) unsigned NOT NULL default 0,
+ url varchar(200) NOT NULL,
+ title varchar(100) NOT NULL,
+ excerpt text NOT NULL,
+ blog_name varchar(100) NOT NULL,
+ tb_date int(10) NOT NULL,
+ ip_address varchar(16) NOT NULL,
+ PRIMARY KEY `tb_id` (`tb_id`),
+ KEY `entry_id` (`entry_id`)
+ );
+
+The Trackback specification only requires four pieces of information to
+be sent in a Trackback (url, title, excerpt, blog_name), but to make
+the data more useful we've added a few more fields in the above table
+schema (date, IP address, etc.).
+
+Processing a Trackback
+======================
+
+Here is an example showing how you will receive and process a Trackback.
+The following code is intended for use within the controller function
+where you expect to receive Trackbacks.
+
+::
+
+ $this->load->library('trackback');
+ $this->load->database();
+
+ if ($this->uri->segment(3) == FALSE)
+ {
+ $this->trackback->send_error("Unable to determine the entry ID");
+ }
+
+ if ( ! $this->trackback->receive())
+ {
+ $this->trackback->send_error("The Trackback did not contain valid data");
+ }
+
+ $data = array(
+ 'tb_id' => '',
+ 'entry_id' => $this->uri->segment(3),
+ 'url' => $this->trackback->data('url'),
+ 'title' => $this->trackback->data('title'),
+ 'excerpt' => $this->trackback->data('excerpt'),
+ 'blog_name' => $this->trackback->data('blog_name'),
+ 'tb_date' => time(),
+ 'ip_address' => $this->input->ip_address()
+ );
+
+ $sql = $this->db->insert_string('trackbacks', $data);
+ $this->db->query($sql);
+
+ $this->trackback->send_success();
+
+Notes:
+^^^^^^
+
+The entry ID number is expected in the third segment of your URL. This
+is based on the URI example we gave earlier::
+
+ http://example.com/index.php/trackback/receive/entry_id
+
+Notice the entry_id is in the third URI segment, which you can retrieve
+using::
+
+ $this->uri->segment(3);
+
+In our Trackback receiving code above, if the third segment is missing,
+we will issue an error. Without a valid entry ID, there's no reason to
+continue.
+
+The $this->trackback->receive() function is simply a validation function
+that looks at the incoming data and makes sure it contains the four
+pieces of data that are required (url, title, excerpt, blog_name). It
+returns TRUE on success and FALSE on failure. If it fails you will issue
+an error message.
+
+The incoming Trackback data can be retrieved using this function::
+
+ $this->trackback->data('item')
+
+Where item represents one of these four pieces of info: url, title,
+excerpt, or blog_name
+
+If the Trackback data is successfully received, you will issue a success
+message using::
+
+ $this->trackback->send_success();
+
+.. note:: The above code contains no data validation, which you are
+ encouraged to add.