repo_zf1/documentation/manual/en/module_specs/Zend_Service_SlideShare.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.slideshare">
    <title>Zend_Service_SlideShare</title>

    <para>
        The <classname>Zend_Service_SlideShare</classname> component is used to interact with the
        <ulink url="http://www.slideshare.net/">slideshare.net</ulink> web services for hosting
        slide shows online. With this component, you can embed slide shows which are hosted on this
        web site within a web site and even upload new slide shows to your account.
    </para>

    <sect2 id="zend.service.slideshare.basicusage">
        <title>Getting Started with Zend_Service_SlideShare</title>

        <para>
            In order to use the <classname>Zend_Service_SlideShare</classname> component you must
            first create an account on the slideshare.net servers (more information can be found
            <ulink url="http://www.slideshare.net/developers/">here</ulink>) in order to receive an
            <acronym>API</acronym> key, username, password and shared secret value -- all of which
            are needed in order to use the <classname>Zend_Service_SlideShare</classname> component.
        </para>

        <para>
            Once you have setup an account, you can begin using the
            <classname>Zend_Service_SlideShare</classname> component by creating a new instance of
            the <classname>Zend_Service_SlideShare</classname> object and providing these values as
            shown below:
        </para>

        <programlisting language="php"><![CDATA[
// Create a new instance of the component
$ss = new Zend_Service_SlideShare('APIKEY',
                                  'SHAREDSECRET',
                                  'USERNAME',
                                  'PASSWORD');
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.slideshare.slideshowobj">
        <title>The SlideShow object</title>

        <para>
            All slide shows in the <classname>Zend_Service_SlideShare</classname> component are
            represented using the <classname>Zend_Service_SlideShare_SlideShow</classname> object
            (both when retrieving and uploading new slide shows). For your reference a pseudo-code
            version of this class is provided below.
        </para>

        <programlisting language="php"><![CDATA[
class Zend_Service_SlideShare_SlideShow {

    /**
     * Retrieves the location of the slide show
     */
    public function getLocation() {
        return $this->_location;
    }

    /**
     * Gets the transcript for this slide show
     */
    public function getTranscript() {
        return $this->_transcript;
    }

    /**
     * Adds a tag to the slide show
     */
    public function addTag($tag) {
        $this->_tags[] = (string)$tag;
        return $this;
    }

    /**
     * Sets the tags for the slide show
     */
    public function setTags(Array $tags) {
        $this->_tags = $tags;
        return $this;
    }

    /**
     * Gets all of the tags associated with the slide show
     */
    public function getTags() {
        return $this->_tags;
    }

    /**
     * Sets the filename on the local filesystem of the slide show
     * (for uploading a new slide show)
     */
    public function setFilename($file) {
        $this->_slideShowFilename = (string)$file;
        return $this;
    }

    /**
     * Retrieves the filename on the local filesystem of the slide show
     * which will be uploaded
     */
    public function getFilename() {
        return $this->_slideShowFilename;
    }

    /**
     * Gets the ID for the slide show
     */
    public function getId() {
        return $this->_slideShowId;
    }

    /**
     * Retrieves the HTML embed code for the slide show
     */
    public function getEmbedCode() {
        return $this->_embedCode;
    }

    /**
     * Retrieves the Thumbnail URi for the slide show
     */
    public function getThumbnailUrl() {
        return $this->_thumbnailUrl;
    }

    /**
     * Sets the title for the Slide show
     */
    public function setTitle($title) {
        $this->_title = (string)$title;
        return $this;
    }

    /**
     * Retrieves the Slide show title
     */
    public function getTitle() {
        return $this->_title;
    }

    /**
     * Sets the description for the Slide show
     */
    public function setDescription($desc) {
        $this->_description = (string)$desc;
        return $this;
    }

    /**
     * Gets the description of the slide show
     */
    public function getDescription() {
        return $this->_description;
    }

    /**
     * Gets the numeric status of the slide show on the server
     */
    public function getStatus() {
        return $this->_status;
    }

    /**
     * Gets the textual description of the status of the slide show on
     * the server
     */
    public function getStatusDescription() {
        return $this->_statusDescription;
    }

    /**
     * Gets the permanent link of the slide show
     */
    public function getPermaLink() {
        return $this->_permalink;
    }

    /**
     * Gets the number of views the slide show has received
     */
    public function getNumViews() {
        return $this->_numViews;
    }
}
]]></programlisting>

        <note>
            <para>
                The above pseudo-class only shows those methods which should be used by end-user
                developers. Other available methods are internal to the component.
            </para>
        </note>

        <para>
            When using the <classname>Zend_Service_SlideShare</classname> component, this data class
            will be used frequently to browse or add new slide shows to or from the web service.
        </para>
    </sect2>

    <sect2 id="zend.service.slideshare.getslideshow">
        <title>Retrieving a single slide show</title>

        <para>
            The simplest usage of the <classname>Zend_Service_SlideShare</classname> component is
            the retrieval of a single slide show by slide show ID provided by the slideshare.net
            application and is done by calling the <methodname>getSlideShow()</methodname> method of
            a <classname>Zend_Service_SlideShare</classname> object and using the resulting
            <classname>Zend_Service_SlideShare_SlideShow</classname> object as shown.
        </para>

        <programlisting language="php"><![CDATA[
// Create a new instance of the component
$ss = new Zend_Service_SlideShare('APIKEY',
                                  'SHAREDSECRET',
                                  'USERNAME',
                                  'PASSWORD');

$slideshow = $ss->getSlideShow(123456);

print "Slide Show Title: {$slideshow->getTitle()}<br/>\n";
print "Number of views: {$slideshow->getNumViews()}<br/>\n";
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.slideshare.getslideshowlist">
        <title>Retrieving Groups of Slide Shows</title>

        <para>
            If you do not know the specific ID of a slide show you are interested in retrieving,
            you can retrieving groups of slide shows by using one of three methods:
        </para>

        <itemizedlist mark="opencircle">
            <listitem>
                <para>
                    <emphasis>Slide shows from a specific account</emphasis>
                </para>

                <para>
                    You can retrieve slide shows from a specific account by using the
                    <methodname>getSlideShowsByUsername()</methodname> method and providing the
                    username from which the slide shows should be retrieved
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Slide shows which contain specific tags</emphasis>
                </para>

                <para>
                    You can retrieve slide shows which contain one or more specific tags by using
                    the <methodname>getSlideShowsByTag()</methodname> method and providing one or
                    more tags which the slide show must have assigned to it in order to be retrieved
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Slide shows by group</emphasis>
                </para>

                <para>
                    You can retrieve slide shows which are a member of a specific group using the
                    <methodname>getSlideShowsByGroup()</methodname> method and providing the name of
                    the group which the slide show must belong to in order to be retrieved
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Each of the above methods of retrieving multiple slide shows a similar approach is
            used. An example of using each method is shown below:
        </para>

        <programlisting language="php"><![CDATA[
// Create a new instance of the component
$ss = new Zend_Service_SlideShare('APIKEY',
                                  'SHAREDSECRET',
                                  'USERNAME',
                                  'PASSWORD');

$starting_offset = 0;
$limit = 10;

// Retrieve the first 10 of each type
$ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
$ss_tags = $ss->getSlideShowsByTag('zend', $starting_offset, $limit);
$ss_group = $ss->getSlideShowsByGroup('mygroup', $starting_offset, $limit);

// Iterate over the slide shows
foreach($ss_user as $slideshow) {
   print "Slide Show Title: {$slideshow->getTitle}<br/>\n";
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.slideshare.caching">
        <title>Zend_Service_SlideShare Caching policies</title>

        <para>
            By default, <classname>Zend_Service_SlideShare</classname> will cache any request
            against the web service automatically to the filesystem (default path
            <filename>/tmp</filename>) for 12 hours. If you desire to change this behavior, you
            must provide your own <link linkend="zend.cache">Zend_Cache</link> object using the
            <methodname>setCacheObject()</methodname> method as shown:
        </para>

        <programlisting language="php"><![CDATA[
$frontendOptions = array(
                        'lifetime' => 7200,
                        'automatic_serialization' => true);
$backendOptions  = array(
                        'cache_dir' => '/webtmp/');

$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);

$ss = new Zend_Service_SlideShare('APIKEY',
                                  'SHAREDSECRET',
                                  'USERNAME',
                                  'PASSWORD');
$ss->setCacheObject($cache);

$ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.slideshare.httpclient">
        <title>Changing the behavior of the HTTP Client</title>

        <para>
            If for whatever reason you would like to change the behavior of the
            <acronym>HTTP</acronym> client when making the web service request, you can do so by
            creating your own instance of the <classname>Zend_Http_Client</classname> object (see
            <link linkend="zend.http">Zend_Http</link>). This is useful for instance when it is
            desirable to set the timeout for the connection to something other then default as
            shown:
        </para>

        <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client();
$client->setConfig(array('timeout' => 5));

$ss = new Zend_Service_SlideShare('APIKEY',
                                  'SHAREDSECRET',
                                  'USERNAME',
                                  'PASSWORD');
$ss->setHttpClient($client);
$ss_user = $ss->getSlideShowsByUser('username', $starting_offset, $limit);
]]></programlisting>
    </sect2>
</sect1>