diff options
Diffstat (limited to 'user_guide_src/source/libraries/trackback.rst')
| -rw-r--r-- | user_guide_src/source/libraries/trackback.rst | 339 |
1 files changed, 0 insertions, 339 deletions
diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst deleted file mode 100644 index dc4477e9f..000000000 --- a/user_guide_src/source/libraries/trackback.rst +++ /dev/null @@ -1,339 +0,0 @@ -############### -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>`_. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************* -Using the Trackback Class -************************* - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Trackback class is -initialized in your controller using the ``$this->load->library()`` method:: - - $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. -- **blog_name** - The name of your weblog. -- **charset** - The character encoding your weblog is written in. If omitted, UTF-8 will be used. - -.. note:: The Trackback class will automatically send only the first 500 characters of your - entry. It will also strip all HTML. - -The Trackback sending method 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(45) 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. - -*************** -Class Reference -*************** - -.. php:class:: CI_Trackback - - .. attribute:: $data = array('url' => '', 'title' => '', 'excerpt' => '', 'blog_name' => '', 'charset' => '') - - Trackback data array. - - .. attribute:: $convert_ascii = TRUE - - Whether to convert high ASCII and MS Word characters to HTML entities. - - .. php:method:: send($tb_data) - - :param array $tb_data: Trackback data - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Send trackback. - - .. php:method:: receive() - - :returns: TRUE on success, FALSE on failure - :rtype: bool - - This method simply validates the incoming TB data, returning TRUE on success and FALSE on failure. - If the data is valid it is set to the ``$this->data`` array so that it can be inserted into a database. - - .. php:method:: send_error([$message = 'Incomplete information']) - - :param string $message: Error message - :rtype: void - - Responses to a trackback request with an error message. - - .. note:: This method will terminate script execution. - - .. php:method:: send_success() - - :rtype: void - - Responses to a trackback request with a success message. - - .. note:: This method will terminate script execution. - - .. php:method:: data($item) - - :param string $item: Data key - :returns: Data value or empty string if not found - :rtype: string - - Returns a single item from the response data array. - - .. php:method:: process($url, $data) - - :param string $url: Target url - :param string $data: Raw POST data - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. - - .. php:method:: extract_urls($urls) - - :param string $urls: Comma-separated URL list - :returns: Array of URLs - :rtype: array - - This method lets multiple trackbacks to be sent. It takes a string of URLs (separated by comma or space) and puts each URL into an array. - - .. php:method:: validate_url(&$url) - - :param string $url: Trackback URL - :rtype: void - - Simply adds the *http://* prefix it it's not already present in the URL. - - .. php:method:: get_id($url) - - :param string $url: Trackback URL - :returns: URL ID or FALSE on failure - :rtype: string - - Find and return a trackback URL's ID or FALSE on failure. - - .. php:method:: convert_xml($str) - - :param string $str: Input string - :returns: Converted string - :rtype: string - - Converts reserved XML characters to entities. - - .. php:method:: limit_characters($str[, $n = 500[, $end_char = '…']]) - - :param string $str: Input string - :param int $n: Max characters number - :param string $end_char: Character to put at end of string - :returns: Shortened string - :rtype: string - - Limits the string based on the character count. Will preserve complete words. - - .. php:method:: convert_ascii($str) - - :param string $str: Input string - :returns: Converted string - :rtype: string - - Converts high ASCII text and MS Word special characterss to HTML entities. - - .. php:method:: set_error($msg) - - :param string $msg: Error message - :rtype: void - - Set an log an error message. - - .. php:method:: display_errors([$open = '<p>'[, $close = '</p>']]) - - :param string $open: Open tag - :param string $close: Close tag - :returns: HTML formatted error messages - :rtype: string - - Returns error messages formatted in HTML or an empty string if there are no errors.
\ No newline at end of file |