From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/trackback.rst | 149 ++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 user_guide_src/source/libraries/trackback.rst (limited to 'user_guide_src/source/libraries/trackback.rst') diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst new file mode 100644 index 000000000..6b332783e --- /dev/null +++ b/user_guide_src/source/libraries/trackback.rst @@ -0,0 +1,149 @@ +############### +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 `_. + +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. -- cgit v1.2.3-24-g4f1b From e0da604e48f70ec1327e781b0446c885643d8a7c Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 15:37:39 -0500 Subject: fixed code block samples for Typography and Trackback libs --- user_guide_src/source/libraries/trackback.rst | 72 +++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 10 deletions(-) (limited to 'user_guide_src/source/libraries/trackback.rst') diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index 6b332783e..07b2b2177 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -25,7 +25,25 @@ 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!'; } + $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: @@ -86,14 +104,21 @@ 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\`) ); +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 @@ -108,7 +133,34 @@ 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(); + $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: ^^^^^^ -- cgit v1.2.3-24-g4f1b