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