documentation/manual/en/module_specs/Zend_Gdata_Spreadsheets.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.spreadsheets">
   4     <title>Using Google Spreadsheets</title>
   5
   6     <para>
   7         The Google Spreadsheets data <acronym>API</acronym> allows client applications to view
   8         and update Spreadsheets content in the form of Google data <acronym>API</acronym> feeds.
   9         Your client application can request a list of a user's spreadsheets,
  10         edit or delete content in an existing Spreadsheets worksheet, and
  11         query the content in an existing Spreadsheets worksheet.
  12     </para>
  13
  14     <para>
  15         See <ulink
  16             url="http://code.google.com/apis/spreadsheets/overview.html">http://code.google.com/apis/spreadsheets/overview.html</ulink>
  17         for more information about the Google Spreadsheets <acronym>API</acronym>.
  18     </para>
  19
  20     <sect2 id="zend.gdata.spreadsheets.creating">
  21         <title>Create a Spreadsheet</title>
  22
  23         <para>
  24             The Spreadsheets data <acronym>API</acronym> does not currently provide a way to
  25             programmatically create or delete a spreadsheet.
  26         </para>
  27     </sect2>
  28
  29     <sect2 id="zend.gdata.spreadsheets.listspreadsheets">
  30         <title>Get a List of Spreadsheets</title>
  31
  32         <para>
  33             You can get a list of spreadsheets for a particular user by using
  34             the <code>getSpreadsheetFeed</code> method of the Spreadsheets
  35             service. The service will return a
  36             <classname>Zend_Gdata_Spreadsheets_SpreadsheetFeed</classname> object
  37             containing a list of spreadsheets associated with the authenticated
  38             user.
  39         </para>
  40
  41         <programlisting language="php"><![CDATA[
  42 $service = Zend_Gdata_Spreadsheets::AUTH_SERVICE_NAME;
  43 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
  44 $spreadsheetService = new Zend_Gdata_Spreadsheets($client);
  45 $feed = $spreadsheetService->getSpreadsheetFeed();
  46 ]]></programlisting>
  47     </sect2>
  48
  49      <sect2 id="zend.gdata.spreadsheets.listworksheets">
  50         <title>Get a List of Worksheets</title>
  51
  52         <para>
  53             A given spreadsheet may contain multiple worksheets. For each
  54             spreadsheet, there's a worksheets metafeed listing all the
  55             worksheets in that spreadsheet.
  56         </para>
  57
  58         <para>
  59             Given the spreadsheet key from the &lt;id&gt; of a
  60             <classname>Zend_Gdata_Spreadsheets_SpreadsheetEntry</classname>
  61             object you've already retrieved, you can fetch a feed
  62             containing a list of worksheets associated with that spreadsheet.
  63         </para>
  64
  65         <programlisting language="php"><![CDATA[
  66 $query = new Zend_Gdata_Spreadsheets_DocumentQuery();
  67 $query->setSpreadsheetKey($spreadsheetKey);
  68 $feed = $spreadsheetService->getWorksheetFeed($query);
  69 ]]></programlisting>
  70
  71         <para>
  72             The resulting <classname>Zend_Gdata_Spreadsheets_WorksheetFeed</classname>
  73             object feed represents the response from the server. Among other
  74             things, this feed contains a list of
  75             <classname>Zend_Gdata_Spreadsheets_WorksheetEntry </classname>
  76             objects (<code>$feed->entries</code>), each of which represents a
  77             single worksheet.
  78         </para>
  79     </sect2>
  80
  81     <sect2 id="zend.gdata.spreadsheets.listfeeds">
  82         <title>Interacting With List-based Feeds</title>
  83
  84         <para>
  85             A given worksheet generally contains multiple rows, each
  86             containing multiple cells. You can request data from the
  87             worksheet either as a list-based feed, in which each entry
  88             represents a row, or as a cell-based feed, in which each
  89             entry represents a single cell. For information on cell-based feeds, see <link
  90                 linkend="zend.gdata.spreadsheets.cellfeeds">Interacting with cell-based
  91                 feeds</link>.
  92         </para>
  93
  94         <para>
  95             The following sections describe how to get a list-based feed,
  96             add a row to a worksheet, and send queries with various query
  97             parameters.
  98         </para>
  99
 100         <para>
 101             The list feed makes some assumptions about how the data is laid
 102             out in the spreadsheet.
 103         </para>
 104
 105         <para>
 106             In particular, the list feed treats the first row of the
 107             worksheet as a header row; Spreadsheets dynamically creates
 108             <acronym>XML</acronym> elements named after the contents of header-row cells.
 109             Users who want to provide Gdata feeds should not put any data
 110             other than column headers in the first row of a worksheet.
 111         </para>
 112
 113         <para>
 114             The list feed contains all rows after the first row up to the
 115             first blank row. The first blank row terminates the data set.
 116             If expected data isn't appearing in a feed, check the worksheet
 117             manually to see whether there's an unexpected blank row in the
 118             middle of the data. In particular, if the second row of the
 119             spreadsheet is blank, then the list feed will contain no data.
 120         </para>
 121
 122         <para>
 123             A row in a list feed is as many columns wide as the worksheet itself.
 124         </para>
 125
 126         <sect3 id="zend.gdata.spreadsheets.listfeeds.get">
 127             <title>Get a List-based Feed</title>
 128
 129             <para>
 130                 To retrieve a worksheet's list feed, use the
 131                 <code>getListFeed</code> method of the Spreadsheets service.
 132             </para>
 133
 134             <programlisting language="php"><![CDATA[
 135 $query = new Zend_Gdata_Spreadsheets_ListQuery();
 136 $query->setSpreadsheetKey($spreadsheetKey);
 137 $query->setWorksheetId($worksheetId);
 138 $listFeed = $spreadsheetService->getListFeed($query);
 139 ]]></programlisting>
 140
 141             <para>
 142                 The resulting <classname>Zend_Gdata_Spreadsheets_ListFeed</classname>
 143                 object <varname>$listfeed</varname> represents a response from the
 144                 server. Among other things, this feed contains an array of
 145                 <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> objects
 146                 (<code>$listFeed->entries</code>), each of which represents
 147                 a single row in a worksheet.
 148             </para>
 149
 150             <para>
 151                 Each <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> contains an
 152                 array, <code>custom</code>, which contains the data for that
 153                 row. You can extract and display this array:
 154             </para>
 155
 156             <programlisting language="php"><![CDATA[
 157 $rowData = $listFeed->entries[1]->getCustom();
 158 foreach($rowData as $customEntry) {
 159   echo $customEntry->getColumnName() . " = " . $customEntry->getText();
 160 }
 161 ]]></programlisting>
 162
 163             <para>
 164                 An alternate version of this array, <code>customByName</code>,
 165                 allows direct access to an entry's cells by name. This is
 166                 convenient when trying to access a specific header:
 167             </para>
 168
 169             <programlisting language="php"><![CDATA[
 170 $customEntry = $listFeed->entries[1]->getCustomByName('my_heading');
 171 echo $customEntry->getColumnName() . " = " . $customEntry->getText();
 172 ]]></programlisting>
 173         </sect3>
 174
 175         <sect3 id="zend.gdata.spreadsheets.listfeeds.reverse">
 176             <title>Reverse-sort Rows</title>
 177
 178             <para>
 179                 By default, rows in the feed appear in the same order as the
 180                 corresponding rows in the GUI; that is, they're in order by
 181                 row number. To get rows in reverse order, set the reverse
 182                 properties of the <classname>Zend_Gdata_Spreadsheets_ListQuery</classname>
 183                 object to <constant>TRUE</constant>:
 184             </para>
 185
 186             <programlisting language="php"><![CDATA[
 187 $query = new Zend_Gdata_Spreadsheets_ListQuery();
 188 $query->setSpreadsheetKey($spreadsheetKey);
 189 $query->setWorksheetId($worksheetId);
 190 $query->setReverse('true');
 191 $listFeed = $spreadsheetService->getListFeed($query);
 192 ]]></programlisting>
 193
 194             <para>
 195                 Note that if you want to order (or reverse sort) by a
 196                 particular column, rather than by position in the worksheet,
 197                 you can set the <code>orderby</code> value of the
 198                 <classname>Zend_Gdata_Spreadsheets_ListQuery</classname> object to
 199                 <code>column:&lt;the header of that column&gt;</code>.
 200             </para>
 201         </sect3>
 202
 203         <sect3 id="zend.gdata.spreadsheets.listfeeds.sq">
 204             <title>Send a Structured Query</title>
 205
 206             <para>
 207                 You can set a <classname>Zend_Gdata_Spreadsheets_ListQuery</classname>'s
 208                 <code>sq</code> value to produce a feed with entries that meet
 209                 the specified criteria. For example, suppose you have a worksheet
 210                 containing personnel data, in which each row represents
 211                 information about a single person. You wish to retrieve all rows
 212                 in which the person's name is "John" and the person's age is over
 213                 25. To do so, you would set <code>sq</code> as follows:
 214             </para>
 215
 216             <programlisting language="php"><![CDATA[
 217 $query = new Zend_Gdata_Spreadsheets_ListQuery();
 218 $query->setSpreadsheetKey($spreadsheetKey);
 219 $query->setWorksheetId($worksheetId);
 220 $query->setSpreadsheetQuery('name=John and age>25');
 221 $listFeed = $spreadsheetService->getListFeed($query);
 222 ]]></programlisting>
 223         </sect3>
 224
 225         <sect3 id="zend.gdata.spreadsheets.listfeeds.addrow">
 226             <title>Add a Row</title>
 227
 228             <para>
 229                 Rows can be added to a spreadsheet by using the
 230                 <code>insertRow</code> method of the Spreadsheet service.
 231             </para>
 232
 233             <programlisting language="php"><![CDATA[
 234 $insertedListEntry = $spreadsheetService->insertRow($rowData,
 235                                                     $spreadsheetKey,
 236                                                     $worksheetId);
 237 ]]></programlisting>
 238
 239             <para>
 240                 The <varname>$rowData</varname> parameter contains an array of column
 241                 keys to data values. The method returns a
 242                 <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname> object
 243                 which represents the inserted row.
 244             </para>
 245
 246             <para>
 247                 Spreadsheets inserts the new row immediately after the last row
 248                 that appears in the list-based feed, which is to say
 249                 immediately before the first entirely blank row.
 250             </para>
 251         </sect3>
 252
 253         <sect3 id="zend.gdata.spreadsheets.listfeeds.editrow">
 254             <title>Edit a Row</title>
 255
 256             <para>
 257                 Once a <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> object
 258                 is fetched, its rows can be updated by using the
 259                 <code>updateRow</code> method of the Spreadsheet service.
 260             </para>
 261
 262             <programlisting language="php"><![CDATA[
 263 $updatedListEntry = $spreadsheetService->updateRow($oldListEntry,
 264                                                    $newRowData);
 265 ]]></programlisting>
 266
 267             <para>
 268                 The <varname>$oldListEntry</varname> parameter contains the list entry
 269                 to be updated. <varname>$newRowData</varname> contains an array of
 270                 column keys to data values, to be used as the new row data.
 271                 The method returns a
 272                 <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname> object
 273                 which represents the updated row.
 274             </para>
 275         </sect3>
 276
 277         <sect3 id="zend.gdata.spreadsheets.listfeeds.deleterow">
 278             <title>Delete a Row</title>
 279
 280             <para>
 281                 To delete a row, simply invoke <code>deleteRow</code> on the
 282                 <classname>Zend_Gdata_Spreadsheets</classname> object with the existing
 283                 entry to be deleted:
 284             </para>
 285
 286             <programlisting language="php"><![CDATA[
 287 $spreadsheetService->deleteRow($listEntry);
 288 ]]></programlisting>
 289
 290             <para>
 291                 Alternatively, you can call the <code>delete</code> method of
 292                 the entry itself:
 293             </para>
 294
 295             <programlisting language="php"><![CDATA[
 296 $listEntry->delete();
 297 ]]></programlisting>
 298         </sect3>
 299     </sect2>
 300
 301     <sect2 id="zend.gdata.spreadsheets.cellfeeds">
 302         <title>Interacting With Cell-based Feeds</title>
 303
 304         <para>
 305             In a cell-based feed, each entry represents a single cell.
 306         </para>
 307
 308         <para>
 309             Note that we don't recommend interacting with both a cell-based
 310             feed and a list-based feed for the same worksheet at the same time.
 311         </para>
 312
 313         <sect3 id="zend.gdata.spreadsheets.cellfeeds.get">
 314             <title>Get a Cell-based Feed</title>
 315
 316             <para>
 317                 To retrieve a worksheet's cell feed, use the
 318                 <code>getCellFeed</code> method of the Spreadsheets service.
 319             </para>
 320
 321             <programlisting language="php"><![CDATA[
 322 $query = new Zend_Gdata_Spreadsheets_CellQuery();
 323 $query->setSpreadsheetKey($spreadsheetKey);
 324 $query->setWorksheetId($worksheetId);
 325 $cellFeed = $spreadsheetService->getCellFeed($query);
 326 ]]></programlisting>
 327
 328             <para>
 329                 The resulting <classname>Zend_Gdata_Spreadsheets_CellFeed</classname>
 330                 object <varname>$cellFeed</varname> represents a response from the
 331                 server. Among other things, this feed contains an array of
 332                 <classname>Zend_Gdata_Spreadsheets_CellEntry</classname> objects
 333                 (<code>$cellFeed>entries</code>), each of which represents
 334                 a single cell in a worksheet. You can display this information:
 335             </para>
 336
 337             <programlisting language="php"><![CDATA[
 338 foreach($cellFeed as $cellEntry) {
 339   $row = $cellEntry->cell->getRow();
 340   $col = $cellEntry->cell->getColumn();
 341   $val = $cellEntry->cell->getText();
 342   echo "$row, $col = $val\n";
 343 }
 344 ]]></programlisting>
 345         </sect3>
 346
 347         <sect3 id="zend.gdata.spreadsheets.cellfeeds.cellrangequery">
 348             <title>Send a Cell Range Query</title>
 349
 350             <para>
 351                 Suppose you wanted to retrieve the cells in the first column
 352                 of a worksheet. You can request a cell feed containing only
 353                 this column as follows:
 354             </para>
 355
 356             <programlisting language="php"><![CDATA[
 357 $query = new Zend_Gdata_Spreadsheets_CellQuery();
 358 $query->setMinCol(1);
 359 $query->setMaxCol(1);
 360 $query->setMinRow(2);
 361 $feed = $spreadsheetService->getCellsFeed($query);
 362 ]]></programlisting>
 363
 364             <para>
 365                 This requests all the data in column 1, starting with row 2.
 366             </para>
 367         </sect3>
 368
 369         <sect3 id="zend.gdata.spreadsheets.cellfeeds.updatecell">
 370             <title>Change Contents of a Cell</title>
 371
 372             <para>
 373                 To modify the contents of a cell, call
 374                 <code>updateCell</code> with the row, column,
 375                 and new value of the cell.
 376             </para>
 377
 378             <programlisting language="php"><![CDATA[
 379 $updatedCell = $spreadsheetService->updateCell($row,
 380                                                $col,
 381                                                $inputValue,
 382                                                $spreadsheetKey,
 383                                                $worksheetId);
 384 ]]></programlisting>
 385
 386             <para>
 387                 The new data is placed in the specified cell in the worksheet.
 388                 If the specified cell contains data already, it will be
 389                 overwritten. Note: Use <code>updateCell</code> to change
 390                 the data in a cell, even if the cell is empty.
 391             </para>
 392         </sect3>
 393     </sect2>
 394 </sect1>