documentation/manual/en/module_specs/Zend_Gdata_Docs.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.docs">
   4     <title>Using Google Documents List Data API</title>
   5
   6     <para>
   7         The Google Documents List Data <acronym>API</acronym> allows client applications to
   8         upload documents to Google Documents and list them in the form of
   9         Google Data <acronym>API</acronym> ("GData") feeds. Your client application can request
  10         a list of a user's documents, and query the content in an existing
  11         document.
  12     </para>
  13
  14     <para>
  15         See <ulink
  16             url="http://code.google.com/apis/documents/overview.html">http://code.google.com/apis/documents/overview.html</ulink>
  17         for more information about the Google Documents List <acronym>API</acronym>.
  18     </para>
  19
  20     <sect2 id="zend.gdata.docs.listdocuments">
  21         <title>Get a List of Documents</title>
  22
  23         <para>
  24             You can get a list of the Google Documents for a particular user by using
  25             the <methodname>getDocumentListFeed()</methodname> method of the docs
  26             service. The service will return a
  27             <classname>Zend_Gdata_Docs_DocumentListFeed</classname> object
  28             containing a list of documents associated with the authenticated
  29             user.
  30         </para>
  31
  32         <programlisting language="php"><![CDATA[
  33 $service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;
  34 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
  35 $docs = new Zend_Gdata_Docs($client);
  36 $feed = $docs->getDocumentListFeed();
  37 ]]></programlisting>
  38
  39         <para>
  40         The resulting <classname>Zend_Gdata_Docs_DocumentListFeed</classname> object
  41         represents the response from the server. This feed contains a list of
  42         <classname>Zend_Gdata_Docs_DocumentListEntry</classname> objects
  43         (<command>$feed->entries</command>), each of which represents a single
  44         Google Document.
  45         </para>
  46     </sect2>
  47
  48     <sect2 id="zend.gdata.docs.creating">
  49         <title>Upload a Document</title>
  50
  51         <para>
  52             You can create a new Google Document by uploading a word
  53             processing document, spreadsheet, or presentation. This example
  54             is from the interactive Docs.php sample which comes with the
  55             library. It demonstrates uploading a file and printing
  56             information about the result from the server.
  57         </para>
  58
  59         <programlisting language="php"><![CDATA[
  60 /**
  61  * Upload the specified document
  62  *
  63  * @param Zend_Gdata_Docs $docs The service object to use for communicating
  64  *     with the Google Documents server.
  65  * @param boolean $html True if output should be formatted for display in a
  66  *     web browser.
  67  * @param string $originalFileName The name of the file to be uploaded. The
  68  *     MIME type of the file is determined from the extension on this file
  69  *     name. For example, test.csv is uploaded as a comma separated volume
  70  *     and converted into a spreadsheet.
  71  * @param string $temporaryFileLocation (optional) The file in which the
  72  *     data for the document is stored. This is used when the file has been
  73  *     uploaded from the client's machine to the server and is stored in
  74  *     a temporary file which does not have an extension. If this parameter
  75  *     is null, the file is read from the originalFileName.
  76  */
  77 function uploadDocument($docs, $html, $originalFileName,
  78                         $temporaryFileLocation) {
  79   $fileToUpload = $originalFileName;
  80   if ($temporaryFileLocation) {
  81     $fileToUpload = $temporaryFileLocation;
  82   }
  83
  84   // Upload the file and convert it into a Google Document. The original
  85   // file name is used as the title of the document and the MIME type
  86   // is determined based on the extension on the original file name.
  87   $newDocumentEntry = $docs->uploadFile($fileToUpload, $originalFileName,
  88       null, Zend_Gdata_Docs::DOCUMENTS_LIST_FEED_URI);
  89
  90   echo "New Document Title: ";
  91
  92   if ($html) {
  93       // Find the URL of the HTML view of this document.
  94       $alternateLink = '';
  95       foreach ($newDocumentEntry->link as $link) {
  96           if ($link->getRel() === 'alternate') {
  97               $alternateLink = $link->getHref();
  98           }
  99       }
 100       // Make the title link to the document on docs.google.com.
 101       echo "<a href=\"$alternateLink\">\n";
 102   }
 103   echo $newDocumentEntry->title."\n";
 104   if ($html) {echo "</a>\n";}
 105 }
 106 ]]></programlisting>
 107     </sect2>
 108
 109     <sect2 id="zend.gdata.docs.queries">
 110         <title>Searching the documents feed</title>
 111
 112         <para>
 113             You can search the Document List using some of the <ulink
 114             url="http://code.google.com/apis/gdata/reference.html#Queries">standard
 115             Google Data <acronym>API</acronym> query parameters</ulink>. Categories are used to
 116             restrict the
 117             type of document (word processor document, spreadsheet) returned.
 118             The full-text query string is used to search the content of all
 119             the documents. More detailed information on parameters specific
 120             to the Documents List can be found in the <ulink
 121                 url="http://code.google.com/apis/documents/reference.html#Parameters">Documents List
 122                 Data <acronym>API</acronym> Reference Guide</ulink>.
 123         </para>
 124
 125         <sect3 id="zend.gdata.docs.listwpdocuments">
 126             <title>Get a List of Word Processing Documents</title>
 127
 128             <para>
 129                 You can also request a feed containing all of your documents of a specific type. For
 130                 example, to see a list of your work processing documents, you would perform a
 131                 category query as follows.
 132             </para>
 133
 134             <programlisting language="php"><![CDATA[
 135 $feed = $docs->getDocumentListFeed(
 136     'http://docs.google.com/feeds/documents/private/full/-/document');
 137 ]]></programlisting>
 138         </sect3>
 139
 140         <sect3 id="zend.gdata.docs.listspreadsheets">
 141             <title>Get a List of Spreadsheets</title>
 142
 143             <para>
 144                 To request a list of your Google Spreadsheets, use the following category query:
 145             </para>
 146
 147             <programlisting language="php"><![CDATA[
 148 $feed = $docs->getDocumentListFeed(
 149     'http://docs.google.com/feeds/documents/private/full/-/spreadsheet');
 150 ]]></programlisting>
 151         </sect3>
 152
 153         <sect3 id="zend.gdata.docs.textquery">
 154             <title>Performing a text query</title>
 155
 156             <para>
 157                 You can search the content of documents by using a
 158                 <classname>Zend_Gdata_Docs_Query</classname> in your request. A Query object
 159                 can be used to construct the query <acronym>URI</acronym>, with the search term
 160                 being passed in as a parameter. Here is an example method which queries
 161                 the documents list for documents which contain the search string:
 162             </para>
 163
 164             <programlisting language="php"><![CDATA[
 165 $docsQuery = new Zend_Gdata_Docs_Query();
 166 $docsQuery->setQuery($query);
 167 $feed = $client->getDocumentListFeed($docsQuery);
 168 ]]></programlisting>
 169         </sect3>
 170     </sect2>
 171 </sect1>