summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/trackback.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2014-02-08 17:18:33 +0100
committerAndrey Andreev <narf@devilix.net>2014-02-08 17:18:33 +0100
commitf733d6db7345ccc5d7ed516fd22ea03cc245cbc4 (patch)
tree0f5eec61542d5c1142709610f5ccaf3908cf36f5 /user_guide_src/source/libraries/trackback.rst
parent93326a5b1bbaade4d416ad17a768cab27337ec5b (diff)
parent28c2c975b118016d07212ed8e7c22ff280309f82 (diff)
Merge branch 'feature/user-guide-cleanup' into develop
Diffstat (limited to 'user_guide_src/source/libraries/trackback.rst')
-rw-r--r--user_guide_src/source/libraries/trackback.rst226
1 files changed, 182 insertions, 44 deletions
diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst
index f9e0df882..22859a13d 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 <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 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,37 @@ 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.
- **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
+.. 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();
@@ -107,16 +118,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 +140,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 +208,132 @@ 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: TRUE on success, FALSE on failure
+ :rtype: bool
+
+ Send trackback.
+
+ .. 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.
+
+ .. 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.
+
+ .. method:: send_success()
+
+ :rtype: 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: 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: 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: 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
+ :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: 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: Converted string
+ :rtype: string
+
+ Converts reserved XML characters to entities.
+
+ .. method:: limit_characters($str[, $n = 500[, $end_char = '&#8230;']])
+
+ :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: 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
+ :rtype: void
+
+ Set an log an error message.
+
+ .. 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