blob: c4caf5e4a2670057437ed006f9e1cbbbd7429b6d [file] [log] [blame]
adminb0dd10f2006-08-25 17:25:49 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html>
3<head>
4
5<title>Code Igniter User Guide</title>
6
7<style type='text/css' media='all'>@import url('../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
9
admin17a890d2006-09-27 20:42:42 +000010<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +000011<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +000012<script type="text/javascript" src="../nav/moo.fx.js"></script>
adminb0dd10f2006-08-25 17:25:49 +000013<script type="text/javascript">
14window.onload = function() {
15 myHeight = new fx.Height('nav', {duration: 400});
16 myHeight.hide();
17}
18</script>
19
20<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
21<meta http-equiv='expires' content='-1' />
22<meta http-equiv= 'pragma' content='no-cache' />
23<meta name='robots' content='all' />
24<meta name='author' content='Rick Ellis' />
25<meta name='description' content='Code Igniter User Guide' />
26
27</head>
28<body>
29
30<!-- START NAVIGATION -->
31<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
32<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
33<div id="masthead">
34<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
35<tr>
admin10c3f412006-10-08 07:21:12 +000036<td><h1>Code Igniter User Guide Version 1.5.0b1</h1></td>
adminb0dd10f2006-08-25 17:25:49 +000037<td id="breadcrumb_right"><a href="../toc.html">Full Table of Contents</a></td>
38</tr>
39</table>
40</div>
41<!-- END NAVIGATION -->
42
43
44<!-- START BREADCRUMB -->
45<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
46<tr>
47<td id="breadcrumb">
48<a href="http://www.codeigniter.com/">Code Igniter Home</a> &nbsp;&#8250;&nbsp;
49<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
50Trackback Class
51</td>
52<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="www.codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
53</tr>
54</table>
55<!-- END BREADCRUMB -->
56
57<br clear="all" />
58
59
60<!-- START CONTENT -->
61<div id="content">
62
63
64<h1>Trackback Class</h1>
65
66<p>The Trackback Class provides functions that enable you to send and receive Trackback data.</p>
67
68
69<p>If you are not familiar with Trackbacks you'll find more information <a href="http://en.wikipedia.org/wiki/Trackback">here</a>.</p>
70
71<h2>Initializing the Class</h2>
72
73<p>Like most other classes in Code Igniter, the Trackback class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
74
75<code>$this->load->library('trackback');</code>
76<p>Once loaded, the Trackback library object will be available using: <dfn>$this->trackback</dfn></p>
77
78
79<h2>Sending Trackbacks</h2>
80
81<p>A Trackback can be sent from any of your controller functions using code similar to this example:
82
83<code>$this->load->library('trackback');<br />
84<br />
85$tb_data = array(<br />
86&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ping_url'&nbsp;&nbsp;=> 'http://some-site.com/trackback/456',<br />
87&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'url'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 'http://www.my-site.com/blog/entry/123',<br />
88&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'title'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 'The Title of My Entry',<br />
89&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'excerpt'&nbsp;&nbsp;&nbsp;=> 'The entry content.',<br />
90&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'blog_name' => 'My Blog Name',<br />
91&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'charset'&nbsp;&nbsp;&nbsp;=> 'utf-8'<br />
92&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
93<br />
94if ( ! $this->trackback->send($tb_data))<br />
95{<br />
96&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $this->trackback->display_errors();<br />
97}<br />
98else<br />
99{<br />
100&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo 'Trackback was sent!';<br />
101}</code>
102
103<p>Description of array data:</p>
104
105<ul>
106<li><strong>ping_url</strong> - 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.</li>
107<li><strong>url</strong> - The URL to YOUR site where the weblog entry can be seen.</li>
108<li><strong>title</strong> - The title of your weblog entry.</li>
109<li><strong>excerpt</strong> - 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.</li>
110<li><strong>blog_name</strong> - The name of your weblog.</li>
111<li><strong>charset</strong> - The character encoding your weblog is written in. If omitted, UTF-8 will be used.</li>
112</ul>
113
114<p>The Trackback sending function returns TRUE/FALSE (boolean) on success or failure. If it fails, you can retrieve the error message using:</p>
115
116<code>$this->trackback->display_errors();</code>
117
118
119<h2>Receiving Trackbacks</h2>
120
121<p>Before you can receive Trackbacks you must create a weblog. If you don't have a blog yet there's no point in continuing.</p>
122
123<p>Receiving Trackbacks is a little more complex than sending them, only because you will need a database table in which to store them,
124and you will need to validate the incoming trackback data. You are encouraged to implement a thorough validation process to
125guard against spam and duplicate data. You may also want to limit the number of Trackbacks you allow from a particular IP within
126a given span of time to further curtail spam. The process of receiving a Trackback is quite simple;
127the validation is what takes most of the effort.</p>
128
129<h2>Your Ping URL</h2>
130
131<p>In order to accept Trackbacks you must display a Trackback URL next to each one of your weblog entries. This will be the URL
132that people will use to send you Trackbacks (we will refer to this as your "Ping URL").</p>
133
134<p>Your Ping URL must point to a controller function where your Trackback receiving code is located, and the URL
135must contain the ID number for each particular entry, so that when the Trackback is received you'll be
136able to associate it with a particular entry.</p>
137
138<p>For example, if your controller class is called <dfn>Trackback</dfn>, and the receiving function is called <dfn>receive</dfn>, your
139Ping URLs will look something like this:</p>
140
141<code>http://www.your-site.com/index.php/trackback/receive/<samp>entry_id</samp></code>
142
143<p>Where <samp>entry_id</samp> represents the individual ID number for each of your entries.</p>
144
145
146<h2>Creating a Trackback Table</h2>
147
148<p>Before you can receive Trackbacks you must create a table in which to store them. Here is a basic prototype for such a table:</p>
149
150<textarea class="textarea" style="width:100%" cols="50" rows="13">
151CREATE TABLE trackbacks (
152 tb_id int(10) unsigned NOT NULL auto_increment,
153 entry_id int(10) unsigned NOT NULL default 0,
154 url varchar(200) NOT NULL,
155 title varchar(100) NOT NULL,
156 excerpt text NOT NULL,
157 blog_name varchar(100) NOT NULL,
158 tb_date int(10) NOT NULL,
159 ip_address varchar(16) NOT NULL,
160 PRIMARY KEY (tb_id),
161 KEY (entry_id)
162);</textarea>
163
164
165<p>The Trackback specification only requires four pieces of information to be sent in a Trackback (url, title, excerpt, blog_name),
166but to make the data more useful we've added a few more fields in the above table schema (date, IP address, etc.).</p>
167
168<h2>Processing a Trackback</h2>
169
170<p>Here is an example showing how you will receive and process a Trackback. The following
171code is intended for use within the controller function where you expect to receive Trackbacks.</p>
172
173<code>$this->load->library('trackback');<br />
174$this->load->database();<br />
175<br />
176if ($this->uri->segment(3) == FALSE)<br />
177{<br />
178&nbsp;&nbsp;&nbsp;&nbsp;$this->trackback->send_error("Unable to determine the entry ID");<br />
179}<br />
180<br />
181if ( ! $this->trackback->receive())<br />
182{<br />
183&nbsp;&nbsp;&nbsp;&nbsp;$this->trackback->send_error("The Trackback did not contain valid data");<br />
184}<br />
185<br />
186$data = array(<br />
187&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'tb_id'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> '',<br />
188&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'entry_id'&nbsp;&nbsp;&nbsp;=> $this->uri->segment(3),<br />
189&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'url'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> $this->trackback->data('url'),<br />
190&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'title'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> $this->trackback->data('title'),<br />
191&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'excerpt'&nbsp;&nbsp;&nbsp;&nbsp;=> $this->trackback->data('excerpt'),<br />
192&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'blog_name'&nbsp;&nbsp;=> $this->trackback->data('blog_name'),<br />
193&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'tb_date'&nbsp;&nbsp;&nbsp;&nbsp;=> time(),<br />
194&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ip_address' => $this->input->ip_address()<br />
195&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
196<br />
197$sql = $this->db->insert_string('trackbacks', $data);<br />
198$this->db->query($sql);<br />
199<br />
200$this->trackback->send_success();</code>
201
202<h4>Notes:</h4>
203
204<p>The entry ID number is expected in the third segment of your URL. This is based on the URI example we gave earlier:</p>
205
206<code>http://www.your-site.com/index.php/trackback/receive/<samp>entry_id</samp></code>
207
208<p>Notice the entry_id is in the third URI, which you can retrieve using:</p>
209
210<code>$this->uri->segment(3);</code>
211
212<p>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
213reason to continue.</p>
214
215<p>The <dfn>$this->trackback->receive()</dfn> function is simply a validation function that looks at the incoming data
216and makes sure it contains the four pieces of data that are required (url, title, excerpt, blog_name).
217It returns TRUE on success and FALSE on failure. If it fails you will issue an error message.</p>
218
219<p>The incoming Trackback data can be retrieved using this function:</p>
220
221<code>$this->trackback->data('<var>item</var>')</code>
222
223<p>Where <var>item</var> represents one of these four pieces of info: url, title, excerpt, or blog_name</p>
224
225<p>If the Trackback data is successfully received, you will issue a success message using:</p>
226
227<code>$this->trackback->send_success();</code>
228
229<p class="important"><strong>Note:</strong> The above code contains no data validation, which you are encouraged to add.</p>
230
231
232
233
234
235</div>
236<!-- END CONTENT -->
237
238
239<div id="footer">
240<p>
admin40037182006-10-11 19:16:58 +0000241Previous Topic:&nbsp;&nbsp;<a href="sessions.html">Session Class</a>
adminb0dd10f2006-08-25 17:25:49 +0000242&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
243<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
244<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
admin6c9f7362006-10-09 03:33:48 +0000245Next Topic:&nbsp;&nbsp;<a href="unit_testing.html">Unit Testing Class</a>
adminb0dd10f2006-08-25 17:25:49 +0000246<p>
247<p><a href="http://www.codeigniter.com">Code Igniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 &nbsp;&middot;&nbsp; <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
248</div>
249
250</body>
251</html>