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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.gdata.spreadsheets">
    <title>Using Google Spreadsheets</title>

    <para>
        The Google Spreadsheets data <acronym>API</acronym> allows client applications to view
        and update Spreadsheets content in the form of Google data <acronym>API</acronym> feeds.
        Your client application can request a list of a user's spreadsheets,
        edit or delete content in an existing Spreadsheets worksheet, and
        query the content in an existing Spreadsheets worksheet.
    </para>

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

    <sect2 id="zend.gdata.spreadsheets.creating">
        <title>Create a Spreadsheet</title>

        <para>
            The Spreadsheets data <acronym>API</acronym> does not currently provide a way to
            programmatically create or delete a spreadsheet.
        </para>
    </sect2>

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

        <para>
            You can get a list of spreadsheets for a particular user by using
            the <methodname>getSpreadsheetFeed()</methodname> method of the Spreadsheets
            service. The service will return a
            <classname>Zend_Gdata_Spreadsheets_SpreadsheetFeed</classname> object
            containing a list of spreadsheets associated with the authenticated
            user.
        </para>

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

     <sect2 id="zend.gdata.spreadsheets.listworksheets">
        <title>Get a List of Worksheets</title>

        <para>
            A given spreadsheet may contain multiple worksheets. For each
            spreadsheet, there's a worksheets metafeed listing all the
            worksheets in that spreadsheet.
        </para>

        <para>
            Given the spreadsheet key from the &lt;id&gt; of a
            <classname>Zend_Gdata_Spreadsheets_SpreadsheetEntry</classname>
            object you've already retrieved, you can fetch a feed
            containing a list of worksheets associated with that spreadsheet.
        </para>

        <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_DocumentQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$feed = $spreadsheetService->getWorksheetFeed($query);
]]></programlisting>

        <para>
            The resulting <classname>Zend_Gdata_Spreadsheets_WorksheetFeed</classname>
            object feed represents the response from the server. Among other
            things, this feed contains a list of
            <classname>Zend_Gdata_Spreadsheets_WorksheetEntry </classname>
            objects (<command>$feed->entries</command>), each of which represents a
            single worksheet.
        </para>
    </sect2>

    <sect2 id="zend.gdata.spreadsheets.listfeeds">
        <title>Interacting With List-based Feeds</title>

        <para>
            A given worksheet generally contains multiple rows, each
            containing multiple cells. You can request data from the
            worksheet either as a list-based feed, in which each entry
            represents a row, or as a cell-based feed, in which each
            entry represents a single cell. For information on cell-based feeds, see <link
                linkend="zend.gdata.spreadsheets.cellfeeds">Interacting with cell-based
                feeds</link>.
        </para>

        <para>
            The following sections describe how to get a list-based feed,
            add a row to a worksheet, and send queries with various query
            parameters.
        </para>

        <para>
            The list feed makes some assumptions about how the data is laid
            out in the spreadsheet.
        </para>

        <para>
            In particular, the list feed treats the first row of the
            worksheet as a header row; Spreadsheets dynamically creates
            <acronym>XML</acronym> elements named after the contents of header-row cells.
            Users who want to provide Gdata feeds should not put any data
            other than column headers in the first row of a worksheet.
        </para>

        <para>
            The list feed contains all rows after the first row up to the
            first blank row. The first blank row terminates the data set.
            If expected data isn't appearing in a feed, check the worksheet
            manually to see whether there's an unexpected blank row in the
            middle of the data. In particular, if the second row of the
            spreadsheet is blank, then the list feed will contain no data.
        </para>

        <para>
            A row in a list feed is as many columns wide as the worksheet itself.
        </para>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.get">
            <title>Get a List-based Feed</title>

            <para>
                To retrieve a worksheet's list feed, use the
                <methodname>getListFeed()</methodname> method of the Spreadsheets service.
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>

            <para>
                The resulting <classname>Zend_Gdata_Spreadsheets_ListFeed</classname>
                object <varname>$listfeed</varname> represents a response from the
                server. Among other things, this feed contains an array of
                <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> objects
                (<command>$listFeed->entries</command>), each of which represents
                a single row in a worksheet.
            </para>

            <para>
                Each <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> contains an
                array, <property>custom</property>, which contains the data for that
                row. You can extract and display this array:
            </para>

            <programlisting language="php"><![CDATA[
$rowData = $listFeed->entries[1]->getCustom();
foreach($rowData as $customEntry) {
  echo $customEntry->getColumnName() . " = " . $customEntry->getText();
}
]]></programlisting>

            <para>
                An alternate version of this array, <property>customByName</property>,
                allows direct access to an entry's cells by name. This is
                convenient when trying to access a specific header:
            </para>

            <programlisting language="php"><![CDATA[
$customEntry = $listFeed->entries[1]->getCustomByName('my_heading');
echo $customEntry->getColumnName() . " = " . $customEntry->getText();
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.reverse">
            <title>Reverse-sort Rows</title>

            <para>
                By default, rows in the feed appear in the same order as the
                corresponding rows in the GUI; that is, they're in order by
                row number. To get rows in reverse order, set the reverse
                properties of the <classname>Zend_Gdata_Spreadsheets_ListQuery</classname>
                object to <constant>TRUE</constant>:
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$query->setReverse('true');
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>

            <para>
                Note that if you want to order (or reverse sort) by a
                particular column, rather than by position in the worksheet,
                you can set the <property>orderby</property> value of the
                <classname>Zend_Gdata_Spreadsheets_ListQuery</classname> object to
                <emphasis>column:&lt;the header of that column&gt;</emphasis>.
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.sq">
            <title>Send a Structured Query</title>

            <para>
                You can set a <classname>Zend_Gdata_Spreadsheets_ListQuery</classname>'s
                <property>sq</property> value to produce a feed with entries that meet
                the specified criteria. For example, suppose you have a worksheet
                containing personnel data, in which each row represents
                information about a single person. You wish to retrieve all rows
                in which the person's name is "John" and the person's age is over
                25. To do so, you would set <property>sq</property> as follows:
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$query->setSpreadsheetQuery('name=John and age>25');
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.addrow">
            <title>Add a Row</title>

            <para>
                Rows can be added to a spreadsheet by using the
                <methodname>insertRow()</methodname> method of the Spreadsheet service.
            </para>

            <programlisting language="php"><![CDATA[
$insertedListEntry = $spreadsheetService->insertRow($rowData,
                                                    $spreadsheetKey,
                                                    $worksheetId);
]]></programlisting>

            <para>
                The <varname>$rowData</varname> parameter contains an array of column
                keys to data values. The method returns a
                <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname> object
                which represents the inserted row.
            </para>

            <para>
                Spreadsheets inserts the new row immediately after the last row
                that appears in the list-based feed, which is to say
                immediately before the first entirely blank row.
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.editrow">
            <title>Edit a Row</title>

            <para>
                Once a <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> object
                is fetched, its rows can be updated by using the
                <methodname>updateRow()</methodname> method of the Spreadsheet service.
            </para>

            <programlisting language="php"><![CDATA[
$updatedListEntry = $spreadsheetService->updateRow($oldListEntry,
                                                   $newRowData);
]]></programlisting>

            <para>
                The <varname>$oldListEntry</varname> parameter contains the list entry
                to be updated. <varname>$newRowData</varname> contains an array of
                column keys to data values, to be used as the new row data.
                The method returns a
                <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname> object
                which represents the updated row.
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.deleterow">
            <title>Delete a Row</title>

            <para>
                To delete a row, simply invoke <methodname>deleteRow()</methodname> on the
                <classname>Zend_Gdata_Spreadsheets</classname> object with the existing
                entry to be deleted:
            </para>

            <programlisting language="php"><![CDATA[
$spreadsheetService->deleteRow($listEntry);
]]></programlisting>

            <para>
                Alternatively, you can call the <methodname>delete()</methodname> method of
                the entry itself:
            </para>

            <programlisting language="php"><![CDATA[
$listEntry->delete();
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.spreadsheets.cellfeeds">
        <title>Interacting With Cell-based Feeds</title>

        <para>
            In a cell-based feed, each entry represents a single cell.
        </para>

        <para>
            Note that we don't recommend interacting with both a cell-based
            feed and a list-based feed for the same worksheet at the same time.
        </para>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.get">
            <title>Get a Cell-based Feed</title>

            <para>
                To retrieve a worksheet's cell feed, use the
                <methodname>getCellFeed()</methodname> method of the Spreadsheets service.
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_CellQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$cellFeed = $spreadsheetService->getCellFeed($query);
]]></programlisting>

            <para>
                The resulting <classname>Zend_Gdata_Spreadsheets_CellFeed</classname>
                object <varname>$cellFeed</varname> represents a response from the
                server. Among other things, this feed contains an array of
                <classname>Zend_Gdata_Spreadsheets_CellEntry</classname> objects
                (<command>$cellFeed>entries</command>), each of which represents
                a single cell in a worksheet. You can display this information:
            </para>

            <programlisting language="php"><![CDATA[
foreach($cellFeed as $cellEntry) {
  $row = $cellEntry->cell->getRow();
  $col = $cellEntry->cell->getColumn();
  $val = $cellEntry->cell->getText();
  echo "$row, $col = $val\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.cellrangequery">
            <title>Send a Cell Range Query</title>

            <para>
                Suppose you wanted to retrieve the cells in the first column
                of a worksheet. You can request a cell feed containing only
                this column as follows:
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_CellQuery();
$query->setMinCol(1);
$query->setMaxCol(1);
$query->setMinRow(2);
$feed = $spreadsheetService->getCellsFeed($query);
]]></programlisting>

            <para>
                This requests all the data in column 1, starting with row 2.
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.updatecell">
            <title>Change Contents of a Cell</title>

            <para>
                To modify the contents of a cell, call
                <methodname>updateCell()</methodname> with the row, column,
                and new value of the cell.
            </para>

            <programlisting language="php"><![CDATA[
$updatedCell = $spreadsheetService->updateCell($row,
                                               $col,
                                               $inputValue,
                                               $spreadsheetKey,
                                               $worksheetId);
]]></programlisting>

            <para>
                The new data is placed in the specified cell in the worksheet.
                If the specified cell contains data already, it will be
                overwritten. Note: Use <methodname>updateCell()</methodname> to change
                the data in a cell, even if the cell is empty.
            </para>
        </sect3>
    </sect2>
</sect1>