documentation/manual/en/module_specs/Zend_Service_Simpy.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.simpy">
   4     <title>Zend_Service_Simpy</title>
   5
   6     <sect2 id="zend.service.simpy.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Simpy</classname> is a lightweight wrapper for the free REST
  11             <acronym>API</acronym> available for the Simpy social bookmarking service.
  12         </para>
  13
  14         <para>
  15             In order to use <classname>Zend_Service_Simpy</classname>, you should already have a
  16             Simpy account. To get an account, visit the <ulink
  17                 url="http://simpy.com">Simpy web site</ulink>. For more information on the Simpy
  18             REST <acronym>API</acronym>, refer to the <ulink
  19                 url="http://www.simpy.com/doc/api/rest">Simpy REST <acronym>API</acronym>
  20                 documentation</ulink>.
  21         </para>
  22
  23         <para>
  24             The Simpy REST <acronym>API</acronym> allows developers to interact with specific
  25             aspects of the service that the Simpy web site offers. The sections following will
  26             outline the use of <classname>Zend_Service_Simpy</classname> for each of these areas.
  27
  28             <itemizedlist>
  29                 <listitem>
  30                     <para>
  31                         Links: Create, Retrieve, Update, Delete
  32                     </para>
  33                 </listitem>
  34
  35                 <listitem>
  36                     <para>
  37                         Tags: Retrieve, Delete, Rename, Merge, Split
  38                     </para>
  39                 </listitem>
  40
  41                 <listitem>
  42                     <para>
  43                         Notes: Create, Retrieve, Update, Delete
  44                     </para>
  45                 </listitem>
  46
  47                 <listitem>
  48                     <para>
  49                         Watchlists: Get, Get All
  50                     </para>
  51                 </listitem>
  52             </itemizedlist>
  53         </para>
  54     </sect2>
  55
  56     <sect2 id="zend.service.simpy.links">
  57         <title>Links</title>
  58
  59         <para>
  60             When querying links, results are returned in descending order by date added. Links can
  61             be searched by title, nickname, tags, note, or even the content of the web page
  62             associated with the link. Simpy offers searching by any or all of these fields with
  63             phrases, boolean operators, and wildcards. See the
  64             <ulink url="http://www.simpy.com/faq#searchSyntax">search syntax</ulink> and
  65             <ulink url="http://www.simpy.com/faq#searchFieldsLinks">search fields</ulink>
  66             sections of the Simpy FAQ for more information.
  67         </para>
  68
  69         <example id="zend.service.simpy.links.querying">
  70             <title>Querying Links</title>
  71
  72             <programlisting language="php"><![CDATA[
  73 $simpy = new Zend_Service_Simpy('yourusername', 'yourpassword');
  74
  75 /* Search for the 10 links added most recently */
  76 $linkQuery = new Zend_Service_Simpy_LinkQuery();
  77 $linkQuery->setLimit(10);
  78
  79 /* Get and display the links */
  80 $linkSet = $simpy->getLinks($linkQuery);
  81 foreach ($linkSet as $link) {
  82     echo '<a href="';
  83     echo $link->getUrl();
  84     echo '">';
  85     echo $link->getTitle();
  86     echo '</a><br />';
  87 }
  88
  89 /* Search for the 5 links added most recently with 'PHP' in
  90 the title */
  91 $linkQuery->setQueryString('title:PHP');
  92 $linkQuery->setLimit(5);
  93
  94 /* Search for all links with 'French' in the title and
  95 'language' in the tags */
  96 $linkQuery->setQueryString('+title:French +tags:language');
  97
  98 /* Search for all links with 'French' in the title and without
  99 'travel' in the tags */
 100 $linkQuery->setQueryString('+title:French -tags:travel');
 101
 102 /* Search for all links added on 12/9/06 */
 103 $linkQuery->setDate('2006-12-09');
 104
 105 /* Search for all links added after 12/9/06 (excluding that
 106 date) */
 107 $linkQuery->setAfterDate('2006-12-09');
 108
 109 /* Search for all links added before 12/9/06 (excluding that
 110 date) */
 111 $linkQuery->setBeforeDate('2006-12-09');
 112
 113 /* Search for all links added between 12/1/06 and 12/9/06
 114 (excluding those two dates) */
 115 $linkQuery->setBeforeDate('2006-12-01');
 116 $linkQuery->setAfterDate('2006-12-09');
 117 ]]></programlisting>
 118         </example>
 119
 120         <para>
 121             Links are represented uniquely by their <acronym>URL</acronym>s. In other words, if an
 122             attempt is made to save a link that has the same <acronym>URL</acronym> as an existing
 123             link, data for the existing link will be overwritten with the data specified in the save
 124             attempt.
 125         </para>
 126
 127         <example id="zend.service.simpy.links.modifying">
 128             <title>Modifying Links</title>
 129
 130             <programlisting language="php"><![CDATA[
 131 $simpy = new Zend_Service_Simpy('yourusername', 'yourpassword');
 132
 133 /* Save a link */
 134 $simpy->saveLink(
 135     'Zend Framework' // Title
 136     'http://framework.zend.com', // URL
 137     Zend_Service_Simpy_Link::ACCESSTYPE_PUBLIC, // Access Type
 138     'zend, framework, php' // Tags
 139     'Zend Framework home page' // Alternative title
 140     'This site rocks!' // Note
 141 );
 142
 143 /* Overwrite the existing link with new data */
 144 $simpy->saveLink(
 145     'Zend Framework'
 146     'http://framework.zend.com',
 147     Zend_Service_Simpy_Link::ACCESSTYPE_PRIVATE, // Access Type has changed
 148     'php, zend, framework' // Tags have changed order
 149     'Zend Framework' // Alternative title has changed
 150     'This site REALLY rocks!' // Note has changed
 151 );
 152
 153 /* Delete the link */
 154 $simpy->deleteLink('http://framework.zend.com');
 155
 156 /* A really easy way to do spring cleaning on your links ;) */
 157 $linkSet = $this->_simpy->getLinks();
 158 foreach ($linkSet as $link) {
 159     $this->_simpy->deleteLink($link->getUrl());
 160 }
 161 ]]></programlisting>
 162         </example>
 163     </sect2>
 164
 165     <sect2 id="zend.service.simpy.tags">
 166         <title>Tags</title>
 167
 168         <para>
 169             When retrieved, tags are sorted in decreasing order (i.e. highest
 170             first) by the number of links that use the tag.
 171         </para>
 172
 173         <example id="zend.service.simpy.tags.working">
 174             <title>Working With Tags</title>
 175
 176             <programlisting language="php"><![CDATA[
 177 $simpy = new Zend_Service_Simpy('yourusername', 'yourpassword');
 178
 179 /* Save a link with tags */
 180 $simpy->saveLink(
 181     'Zend Framework' // Title
 182     'http://framework.zend.com', // URL
 183     Zend_Service_Simpy_Link::ACCESSTYPE_PUBLIC, // Access Type
 184     'zend, framework, php' // Tags
 185 );
 186
 187 /* Get a list of all tags in use by links and notes */
 188 $tagSet = $simpy->getTags();
 189
 190 /* Display each tag with the number of links using it */
 191 foreach ($tagSet as $tag) {
 192     echo $tag->getTag();
 193     echo ' - ';
 194     echo $tag->getCount();
 195     echo '<br />';
 196 }
 197
 198 /* Remove the 'zend' tag from all links using it */
 199 $simpy->removeTag('zend');
 200
 201 /* Rename the 'framework' tag to 'frameworks' */
 202 $simpy->renameTag('framework', 'frameworks');
 203
 204 /* Split the 'frameworks' tag into 'framework' and
 205 'development', which will remove the 'frameworks' tag for
 206 all links that use it and add the tags 'framework' and
 207 'development' to all of those links */
 208 $simpy->splitTag('frameworks', 'framework', 'development');
 209
 210 /* Merge the 'framework' and 'development' tags back into
 211 'frameworks', basically doing the opposite of splitting them */
 212 $simpy->mergeTags('framework', 'development', 'frameworks');
 213 ]]></programlisting>
 214         </example>
 215     </sect2>
 216
 217     <sect2 id="zend.service.simpy.notes">
 218         <title>Notes</title>
 219
 220         <para>
 221             Notes can be saved, retrieved, and deleted. They are uniquely
 222             identified by a numeric ID value.
 223         </para>
 224
 225         <example id="zend.service.simpy.notes.working">
 226             <title>Working With Notes</title>
 227
 228             <programlisting language="php"><![CDATA[
 229 $simpy = new Zend_Service_Simpy('yourusername', 'yourpassword');
 230
 231 /* Save a note */
 232 $simpy->saveNote(
 233     'Test Note', // Title
 234     'test,note', // Tags
 235     'This is a test note.' // Description
 236 );
 237
 238 /* Overwrite an existing note */
 239 $simpy->saveNote(
 240     'Updated Test Note', // Title
 241     'test,note,updated', // Tags
 242     'This is an updated test note.', // Description
 243     $note->getId() // Unique identifier
 244 );
 245
 246 /* Search for the 10 most recently added notes */
 247 $noteSet = $simpy->getNotes(null, 10);
 248
 249 /* Display the notes */
 250 foreach ($noteSet as $note) {
 251     echo '<p>';
 252     echo $note->getTitle();
 253     echo '<br />';
 254     echo $note->getDescription();
 255     echo '<br >';
 256     echo $note->getTags();
 257     echo '</p>';
 258 }
 259
 260 /* Search for all notes with 'PHP' in the title */
 261 $noteSet = $simpy->getNotes('title:PHP');
 262
 263 /* Search for all notes with 'PHP' in the title and
 264 without 'framework' in the description */
 265 $noteSet = $simpy->getNotes('+title:PHP -description:framework');
 266
 267 /* Delete a note */
 268 $simpy->deleteNote($note->getId());
 269 ]]></programlisting>
 270         </example>
 271     </sect2>
 272
 273     <sect2 id="zend.service.simpy.watchlists">
 274         <title>Watchlists</title>
 275
 276         <para>
 277             Watchlists cannot be created or removed using the <acronym>API</acronym>, only
 278             retrieved. Thus, you must set up a watchlist via the Simpy web
 279             site prior to attempting to access it using the <acronym>API</acronym>.
 280         </para>
 281
 282         <example id="zend.service.simpy.watchlists.retrieving">
 283             <title>Retrieving Watchlists</title>
 284
 285             <programlisting language="php"><![CDATA[
 286 $simpy = new Zend_Service_Simpy('yourusername', 'yourpassword');
 287
 288 /* Get a list of all watchlists */
 289 $watchlistSet = $simpy->getWatchlists();
 290
 291 /* Display data for each watchlist */
 292 foreach ($watchlistSet as $watchlist) {
 293     echo $watchlist->getId();
 294     echo '<br />';
 295     echo $watchlist->getName();
 296     echo '<br />';
 297     echo $watchlist->getDescription();
 298     echo '<br />';
 299     echo $watchlist->getAddDate();
 300     echo '<br />';
 301     echo $watchlist->getNewLinks();
 302     echo '<br />';
 303
 304     foreach ($watchlist->getUsers() as $user) {
 305         echo $user;
 306         echo '<br />';
 307     }
 308
 309     foreach ($watchlist->getFilters() as $filter) {
 310         echo $filter->getName();
 311         echo '<br />';
 312         echo $filter->getQuery();
 313         echo '<br />';
 314     }
 315 }
 316
 317 /* Get an individual watchlist by its identifier */
 318 $watchlist = $simpy->getWatchlist($watchlist->getId());
 319 $watchlist = $simpy->getWatchlist(1);
 320 ]]></programlisting>
 321         </example>
 322     </sect2>
 323 </sect1>
 324 <!--
 325 vim:se ts=4 sw=4 et:
 326 -->