From 9ea31e823af8cfe73154d4e262331623a2f1ded5 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 17:20:56 +0300 Subject: [ci skip] Update the Trackback library docs --- user_guide_src/source/libraries/trackback.rst | 215 ++++++++++++++++++++------ 1 file changed, 171 insertions(+), 44 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 f9e0df882..72958934c 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -8,16 +8,28 @@ receive Trackback data. If you are not familiar with Trackbacks you'll find more information `here `_. +.. content:: + :local: + +.. raw:: html + +
+ +************************* +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 function:: +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 +Once loaded, the Trackback library object will be available using:: + + $this->trackback Sending Trackbacks ================== @@ -28,38 +40,36 @@ 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' - ); + '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(); + echo $this->trackback->display_errors(); } else { - echo 'Trackback was sent!'; + 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. + 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. +- **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. +- **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 +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(); @@ -107,16 +117,16 @@ 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`) + 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 @@ -129,33 +139,31 @@ 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. - -:: +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"); + $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"); + $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() - ); + '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); @@ -199,3 +207,122 @@ message using:: .. note:: The above code contains no data validation, which you are encouraged to add. + +*************** +Class Reference +*************** + +.. 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. + + .. method:: send($tb_data) + + :param array $tb_data: trackback data + :returns: bool + + Send trackback. + + .. method:: receive() + + :returns: 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. + + .. method:: send_error([$message = 'Incomplete information') + + :param string $message: error message + :returns: void + + Responses to a trackback request with an error message. + + .. note:: This method will terminate script execution. + + .. method:: send_success() + + :returns: void + + Responses to a trackback request with a success message. + + .. note:: This method will terminate script execution. + + .. method:: data($item) + + :param string $item: data key + :returns: string + + Returns a single item from the reponse data array. + + .. method:: process($url, $data) + + :param string $url: target url + :param string $data: raw post data + :returns: bool + + Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. + + .. method:: extract_urls($urls) + + :param string $urls: comma-separated url list + :returns: string + + 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. + + .. method:: validate_url(&$url) + + :param string $url: trackback url + :returns: void + + Simply adds the *http://* prefix it it's not already present in the URL. + + .. method:: get_id($url) + + :param string $url: trackback url + :returns: string + + Find and return a trackback URL's ID or FALSE on failure. + + .. method:: convert_xml($str) + + :param string $str: input string + :returns: string + + Converts reserved XML characters to entities. + + .. 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: string + + Limits the string based on the character count. Will preserve complete words. + + .. method:: convert_ascii($str) + + :param string $str: input string + :returns: string + + Converts high ASCII text and MS Word special characterss to HTML entities. + + .. method:: set_error($msg) + + :param string $msg: error message + :returns: void + + Set an log an error message. + + .. method:: display_errors([$open = '

'[, $close = '

']]) + + :param string $open: open tag + :param string $close: close tag + :returns: string + + Returns error messages formatted in HTML or an empty string if there are no errors. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc042095bcce9856402cc04997f44310074716e0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:08:27 +0200 Subject: [ci skip] Some more generic user guide cleanup --- user_guide_src/source/libraries/trackback.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 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 72958934c..a1667c79c 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -9,11 +9,11 @@ If you are not familiar with Trackbacks you'll find more information `here `_. .. content:: - :local: + :local: .. raw:: html -
+
************************* Using the Trackback Class -- cgit v1.2.3-24-g4f1b From 75b3fb26a324c71ff18fa19b2a3caa357f8133ec Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Sat, 11 Jan 2014 06:58:43 -0600 Subject: cleanup warnings Signed-off-by: Connor Tumbleson --- user_guide_src/source/libraries/trackback.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 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 a1667c79c..c5b01a2ee 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -8,7 +8,7 @@ receive Trackback data. If you are not familiar with Trackbacks you'll find more information `here `_. -.. content:: +.. contents:: :local: .. raw:: html @@ -64,11 +64,12 @@ Description of array data: - **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. +.. 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:: -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/trackback.rst | 70 +++++++++++++++------------ 1 file changed, 40 insertions(+), 30 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 c5b01a2ee..22859a13d 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -225,22 +225,24 @@ Class Reference .. method:: send($tb_data) - :param array $tb_data: trackback data - :returns: bool + :param array $tb_data: Trackback data + :returns: TRUE on success, FALSE on failure + :rtype: bool Send trackback. .. method:: receive() - :returns: bool + :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. .. method:: send_error([$message = 'Incomplete information') - :param string $message: error message - :returns: void + :param string $message: Error message + :rtype: void Responses to a trackback request with an error message. @@ -248,7 +250,7 @@ Class Reference .. method:: send_success() - :returns: void + :rtype: void Responses to a trackback request with a success message. @@ -256,74 +258,82 @@ Class Reference .. method:: data($item) - :param string $item: data key - :returns: string + :param string $item: Data key + :returns: Data value or empty string if not found + :rtype: string Returns a single item from the reponse data array. .. method:: process($url, $data) - :param string $url: target url - :param string $data: raw post data - :returns: bool + :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. .. method:: extract_urls($urls) - :param string $urls: comma-separated url list - :returns: string + :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. .. method:: validate_url(&$url) - :param string $url: trackback url - :returns: void + :param string $url: Trackback URL + :rtype: void Simply adds the *http://* prefix it it's not already present in the URL. .. method:: get_id($url) - :param string $url: trackback url - :returns: string + :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. .. method:: convert_xml($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts reserved XML characters to entities. .. 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: string + :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. .. method:: convert_ascii($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts high ASCII text and MS Word special characterss to HTML entities. .. method:: set_error($msg) - :param string $msg: error message - :returns: void + :param string $msg: Error message + :rtype: void Set an log an error message. .. method:: display_errors([$open = '

'[, $close = '

']]) - :param string $open: open tag - :param string $close: close tag - :returns: string + :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 -- cgit v1.2.3-24-g4f1b