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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.gdata.docs">
    <title>Using Google Documents List Data API</title>

    <para>
        The Google Documents List Data <acronym>API</acronym> allows client applications to
        upload documents to Google Documents and list them in the form of
        Google Data <acronym>API</acronym> ("GData") feeds. Your client application can request
        a list of a user's documents, and query the content in an existing
        document.
    </para>

    <para>
        See <ulink
            url="http://code.google.com/apis/documents/overview.html">http://code.google.com/apis/documents/overview.html</ulink>
        for more information about the Google Documents List <acronym>API</acronym>.
    </para>

    <sect2 id="zend.gdata.docs.listdocuments">
        <title>Get a List of Documents</title>

        <para>
            You can get a list of the Google Documents for a particular user by using
            the <methodname>getDocumentListFeed()</methodname> method of the docs
            service. The service will return a
            <classname>Zend_Gdata_Docs_DocumentListFeed</classname> object
            containing a list of documents associated with the authenticated
            user.
        </para>

        <programlisting language="php"><![CDATA[
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;
$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$docs = new Zend_Gdata_Docs($client);
$feed = $docs->getDocumentListFeed();
]]></programlisting>

        <para>
        The resulting <classname>Zend_Gdata_Docs_DocumentListFeed</classname> object
        represents the response from the server. This feed contains a list of
        <classname>Zend_Gdata_Docs_DocumentListEntry</classname> objects
        (<command>$feed->entries</command>), each of which represents a single
        Google Document.
        </para>
    </sect2>

    <sect2 id="zend.gdata.docs.creating">
        <title>Upload a Document</title>

        <para>
            You can create a new Google Document by uploading a word
            processing document, spreadsheet, or presentation. This example
            is from the interactive Docs.php sample which comes with the
            library. It demonstrates uploading a file and printing
            information about the result from the server.
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Upload the specified document
 *
 * @param Zend_Gdata_Docs $docs The service object to use for communicating
 *     with the Google Documents server.
 * @param boolean $html True if output should be formatted for display in a
 *     web browser.
 * @param string $originalFileName The name of the file to be uploaded. The
 *     MIME type of the file is determined from the extension on this file
 *     name. For example, test.csv is uploaded as a comma separated volume
 *     and converted into a spreadsheet.
 * @param string $temporaryFileLocation (optional) The file in which the
 *     data for the document is stored. This is used when the file has been
 *     uploaded from the client's machine to the server and is stored in
 *     a temporary file which does not have an extension. If this parameter
 *     is null, the file is read from the originalFileName.
 */
function uploadDocument($docs, $html, $originalFileName,
                        $temporaryFileLocation) {
  $fileToUpload = $originalFileName;
  if ($temporaryFileLocation) {
    $fileToUpload = $temporaryFileLocation;
  }

  // Upload the file and convert it into a Google Document. The original
  // file name is used as the title of the document and the MIME type
  // is determined based on the extension on the original file name.
  $newDocumentEntry = $docs->uploadFile($fileToUpload, $originalFileName,
      null, Zend_Gdata_Docs::DOCUMENTS_LIST_FEED_URI);

  echo "New Document Title: ";

  if ($html) {
      // Find the URL of the HTML view of this document.
      $alternateLink = '';
      foreach ($newDocumentEntry->link as $link) {
          if ($link->getRel() === 'alternate') {
              $alternateLink = $link->getHref();
          }
      }
      // Make the title link to the document on docs.google.com.
      echo "<a href=\"$alternateLink\">\n";
  }
  echo $newDocumentEntry->title."\n";
  if ($html) {echo "</a>\n";}
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.gdata.docs.queries">
        <title>Searching the documents feed</title>

        <para>
            You can search the Document List using some of the <ulink
            url="http://code.google.com/apis/gdata/reference.html#Queries">standard
            Google Data <acronym>API</acronym> query parameters</ulink>. Categories are used to
            restrict the
            type of document (word processor document, spreadsheet) returned.
            The full-text query string is used to search the content of all
            the documents. More detailed information on parameters specific
            to the Documents List can be found in the <ulink
                url="http://code.google.com/apis/documents/reference.html#Parameters">Documents List
                Data <acronym>API</acronym> Reference Guide</ulink>.
        </para>

        <sect3 id="zend.gdata.docs.listwpdocuments">
            <title>Get a List of Word Processing Documents</title>

            <para>
                You can also request a feed containing all of your documents of a specific type. For
                example, to see a list of your work processing documents, you would perform a
                category query as follows.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $docs->getDocumentListFeed(
    'http://docs.google.com/feeds/documents/private/full/-/document');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.docs.listspreadsheets">
            <title>Get a List of Spreadsheets</title>

            <para>
                To request a list of your Google Spreadsheets, use the following category query:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $docs->getDocumentListFeed(
    'http://docs.google.com/feeds/documents/private/full/-/spreadsheet');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.docs.textquery">
            <title>Performing a text query</title>

            <para>
                You can search the content of documents by using a
                <classname>Zend_Gdata_Docs_Query</classname> in your request. A Query object
                can be used to construct the query <acronym>URI</acronym>, with the search term
                being passed in as a parameter. Here is an example method which queries
                the documents list for documents which contain the search string:
            </para>

            <programlisting language="php"><![CDATA[
$docsQuery = new Zend_Gdata_Docs_Query();
$docsQuery->setQuery($query);
$feed = $client->getDocumentListFeed($docsQuery);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>