documentation/manual/en/module_specs/Zend_Service_SlideShare.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.slideshare">
   4     <title>Zend_Service_SlideShare</title>
   5
   6     <para>
   7         The <classname>Zend_Service_SlideShare</classname> component is used to interact with the
   8         <ulink url="http://www.slideshare.net/">slideshare.net</ulink> web services for hosting
   9         slide shows online. With this component, you can embed slide shows which are hosted on this
  10         web site within a web site and even upload new slide shows to your account.
  11     </para>
  12
  13     <sect2 id="zend.service.slideshare.basicusage">
  14         <title>Getting Started with Zend_Service_SlideShare</title>
  15
  16         <para>
  17             In order to use the <classname>Zend_Service_SlideShare</classname> component you must
  18             first create an account on the slideshare.net servers (more information can be found
  19             <ulink url="http://www.slideshare.net/developers/">here</ulink>) in order to receive an
  20             <acronym>API</acronym> key, username, password and shared secret value -- all of which
  21             are needed in order to use the <classname>Zend_Service_SlideShare</classname> component.
  22         </para>
  23
  24         <para>
  25             Once you have setup an account, you can begin using the
  26             <classname>Zend_Service_SlideShare</classname> component by creating a new instance of
  27             the <classname>Zend_Service_SlideShare</classname> object and providing these values as
  28             shown below:
  29         </para>
  30
  31         <programlisting language="php"><![CDATA[
  32 // Create a new instance of the component
  33 $ss = new Zend_Service_SlideShare('APIKEY',
  34                                   'SHAREDSECRET',
  35                                   'USERNAME',
  36                                   'PASSWORD');
  37 ]]></programlisting>
  38     </sect2>
  39
  40     <sect2 id="zend.service.slideshare.slideshowobj">
  41         <title>The SlideShow object</title>
  42
  43         <para>
  44             All slide shows in the <classname>Zend_Service_SlideShare</classname> component are
  45             represented using the <classname>Zend_Service_SlideShare_SlideShow</classname> object
  46             (both when retrieving and uploading new slide shows). For your reference a pseudo-code
  47             version of this class is provided below.
  48         </para>
  49
  50         <programlisting language="php"><![CDATA[
  51 class Zend_Service_SlideShare_SlideShow {
  52
  53     /**
  54      * Retrieves the location of the slide show
  55      */
  56     public function getLocation() {
  57         return $this->_location;
  58     }
  59
  60     /**
  61      * Gets the transcript for this slide show
  62      */
  63     public function getTranscript() {
  64         return $this->_transcript;
  65     }
  66
  67     /**
  68      * Adds a tag to the slide show
  69      */
  70     public function addTag($tag) {
  71         $this->_tags[] = (string)$tag;
  72         return $this;
  73     }
  74
  75     /**
  76      * Sets the tags for the slide show
  77      */
  78     public function setTags(Array $tags) {
  79         $this->_tags = $tags;
  80         return $this;
  81     }
  82
  83     /**
  84      * Gets all of the tags associated with the slide show
  85      */
  86     public function getTags() {
  87         return $this->_tags;
  88     }
  89
  90     /**
  91      * Sets the filename on the local filesystem of the slide show
  92      * (for uploading a new slide show)
  93      */
  94     public function setFilename($file) {
  95         $this->_slideShowFilename = (string)$file;
  96         return $this;
  97     }
  98
  99     /**
 100      * Retrieves the filename on the local filesystem of the slide show
 101      * which will be uploaded
 102      */
 103     public function getFilename() {
 104         return $this->_slideShowFilename;
 105     }
 106
 107     /**
 108      * Gets the ID for the slide show
 109      */
 110     public function getId() {
 111         return $this->_slideShowId;
 112     }
 113
 114     /**
 115      * Retrieves the HTML embed code for the slide show
 116      */
 117     public function getEmbedCode() {
 118         return $this->_embedCode;
 119     }
 120
 121     /**
 122      * Retrieves the Thumbnail URi for the slide show
 123      */
 124     public function getThumbnailUrl() {
 125         return $this->_thumbnailUrl;
 126     }
 127
 128     /**
 129      * Sets the title for the Slide show
 130      */
 131     public function setTitle($title) {
 132         $this->_title = (string)$title;
 133         return $this;
 134     }
 135
 136     /**
 137      * Retrieves the Slide show title
 138      */
 139     public function getTitle() {
 140         return $this->_title;
 141     }
 142
 143     /**
 144      * Sets the description for the Slide show
 145      */
 146     public function setDescription($desc) {
 147         $this->_description = (string)$desc;
 148         return $this;
 149     }
 150
 151     /**
 152      * Gets the description of the slide show
 153      */
 154     public function getDescription() {
 155         return $this->_description;
 156     }
 157
 158     /**
 159      * Gets the numeric status of the slide show on the server
 160      */
 161     public function getStatus() {
 162         return $this->_status;
 163     }
 164
 165     /**
 166      * Gets the textual description of the status of the slide show on
 167      * the server
 168      */
 169     public function getStatusDescription() {
 170         return $this->_statusDescription;
 171     }
 172
 173     /**
 174      * Gets the permanent link of the slide show
 175      */
 176     public function getPermaLink() {
 177         return $this->_permalink;
 178     }
 179
 180     /**
 181      * Gets the number of views the slide show has received
 182      */
 183     public function getNumViews() {
 184         return $this->_numViews;
 185     }
 186 }
 187 ]]></programlisting>
 188
 189         <note>
 190             <para>
 191                 The above pseudo-class only shows those methods which should be used by end-user
 192                 developers. Other available methods are internal to the component.
 193             </para>
 194         </note>
 195
 196         <para>
 197             When using the <classname>Zend_Service_SlideShare</classname> component, this data class
 198             will be used frequently to browse or add new slide shows to or from the web service.
 199         </para>
 200     </sect2>
 201
 202     <sect2 id="zend.service.slideshare.getslideshow">
 203         <title>Retrieving a single slide show</title>
 204
 205         <para>
 206             The simplest usage of the <classname>Zend_Service_SlideShare</classname> component is
 207             the retrieval of a single slide show by slide show ID provided by the slideshare.net
 208             application and is done by calling the <methodname>getSlideShow()</methodname> method of
 209             a <classname>Zend_Service_SlideShare</classname> object and using the resulting
 210             <classname>Zend_Service_SlideShare_SlideShow</classname> object as shown.
 211         </para>
 212
 213         <programlisting language="php"><![CDATA[
 214 // Create a new instance of the component
 215 $ss = new Zend_Service_SlideShare('APIKEY',
 216                                   'SHAREDSECRET',
 217                                   'USERNAME',
 218                                   'PASSWORD');
 219
 220 $slideshow = $ss->getSlideShow(123456);
 221
 222 print "Slide Show Title: {$slideshow->getTitle()}<br/>\n";
 223 print "Number of views: {$slideshow->getNumViews()}<br/>\n";
 224 ]]></programlisting>
 225     </sect2>
 226
 227     <sect2 id="zend.service.slideshare.getslideshowlist">
 228         <title>Retrieving Groups of Slide Shows</title>
 229
 230         <para>
 231             If you do not know the specific ID of a slide show you are interested in retrieving,
 232             you can retrieving groups of slide shows by using one of three methods:
 233         </para>
 234
 235         <itemizedlist mark="opencircle">
 236             <listitem>
 237                 <para>
 238                     <emphasis>Slide shows from a specific account</emphasis>
 239                 </para>
 240
 241                 <para>
 242                     You can retrieve slide shows from a specific account by using the
 243                     <methodname>getSlideShowsByUsername()</methodname> method and providing the
 244                     username from which the slide shows should be retrieved
 245                 </para>
 246             </listitem>
 247
 248             <listitem>
 249                 <para>
 250                     <emphasis>Slide shows which contain specific tags</emphasis>
 251                 </para>
 252
 253                 <para>
 254                     You can retrieve slide shows which contain one or more specific tags by using
 255                     the <code>getSlideShowsByTag</code> method and providing one or more tags which
 256                     the slide show must have assigned to it in order to be retrieved
 257                 </para>
 258             </listitem>
 259
 260             <listitem>
 261                 <para>
 262                     <emphasis>Slide shows by group</emphasis>
 263                 </para>
 264
 265                 <para>
 266                     You can retrieve slide shows which are a member of a specific group using the
 267                     <code>getSlideShowsByGroup</code> method and providing the name of the group
 268                     which the slide show must belong to in order to be retrieved
 269                 </para>
 270             </listitem>
 271         </itemizedlist>
 272
 273         <para>
 274             Each of the above methods of retrieving multiple slide shows a similar approach is
 275             used. An example of using each method is shown below:
 276         </para>
 277
 278         <programlisting language="php"><![CDATA[
 279 // Create a new instance of the component
 280 $ss = new Zend_Service_SlideShare('APIKEY',
 281                                   'SHAREDSECRET',
 282                                   'USERNAME',
 283                                   'PASSWORD');
 284
 285 $starting_offset = 0;
 286 $limit = 10;
 287
 288 // Retrieve the first 10 of each type
 289 $ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
 290 $ss_tags = $ss->getSlideShowsByTag('zend', $starting_offset, $limit);
 291 $ss_group = $ss->getSlideShowsByGroup('mygroup', $starting_offset, $limit);
 292
 293 // Iterate over the slide shows
 294 foreach($ss_user as $slideshow) {
 295    print "Slide Show Title: {$slideshow->getTitle}<br/>\n";
 296 }
 297 ]]></programlisting>
 298     </sect2>
 299
 300     <sect2 id="zend.service.slideshare.caching">
 301         <title>Zend_Service_SlideShare Caching policies</title>
 302
 303         <para>
 304             By default, <classname>Zend_Service_SlideShare</classname> will cache any request
 305             against the web service automatically to the filesystem (default path <code>/tmp</code>)
 306             for 12 hours. If you desire to change this behavior, you must provide your own
 307             <xref linkend="zend.cache" /> object using the <code>setCacheObject</code> method as
 308             shown:
 309         </para>
 310
 311         <programlisting language="php"><![CDATA[
 312 $frontendOptions = array(
 313                         'lifetime' => 7200,
 314                         'automatic_serialization' => true);
 315 $backendOptions  = array(
 316                         'cache_dir' => '/webtmp/');
 317
 318 $cache = Zend_Cache::factory('Core',
 319                              'File',
 320                              $frontendOptions,
 321                              $backendOptions);
 322
 323 $ss = new Zend_Service_SlideShare('APIKEY',
 324                                   'SHAREDSECRET',
 325                                   'USERNAME',
 326                                   'PASSWORD');
 327 $ss->setCacheObject($cache);
 328
 329 $ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
 330 ]]></programlisting>
 331     </sect2>
 332
 333     <sect2 id="zend.service.slideshare.httpclient">
 334         <title>Changing the behavior of the HTTP Client</title>
 335
 336         <para>
 337             If for whatever reason you would like to change the behavior of the
 338             <acronym>HTTP</acronym> client when making the web service request, you can do so by
 339             creating your own instance of the <classname>Zend_Http_Client</classname> object (see
 340             <xref linkend="zend.http" />). This is useful for instance when it is desirable to set
 341             the timeout for the connection to something other then default as shown:
 342         </para>
 343
 344         <programlisting language="php"><![CDATA[
 345 $client = new Zend_Http_Client();
 346 $client->setConfig(array('timeout' => 5));
 347
 348 $ss = new Zend_Service_SlideShare('APIKEY',
 349                                   'SHAREDSECRET',
 350                                   'USERNAME',
 351                                   'PASSWORD');
 352 $ss->setHttpClient($client);
 353 $ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
 354 ]]></programlisting>
 355     </sect2>
 356 </sect1>