Accessing Google Docs documents

The Google Docs connector allows you to embed Google Docs™ documents in an XDIME page.

The Google Docs connector allows you to embed Google Docs™ documents in an XDIME page.

Note:

Only text documents are supported at the moment.

Note:

The Google Docs connector uses the Google Documents List Data API version 2.0.

Authentication

There are two mutually exclusive methods of authenticating with Google Docs. The first method requires an email address and the user's password. The second method is based on the Google AuthSub mechanism and requires a token. Refer to Authentication for Installed Applications and AuthSub Authentication for Web Applications for further information.

It is possible to create web applications that allow users to enter login credentials and access their own Google Docs resources. An authentication failure can either cause the whole operation to fail, or it can, for example, present a login page and allow users to update their password or answer a CAPTCHA challenge. The pipeline error functions allow page authors to achieve the desired functionality. See Handling pipeline errors for details. The authentication information can also be hard-coded in web applications. In this case an authentication failure can only be resolved by a system administrator who will therefore need to be notified about the failure.

The gdocs:authenticate element authenticates the user with Google Docs. The user-id and password attributes specify the user's email address and the user's password respectively.

<gdocs:authenticate user-id="antennatests@gmail.com" password="1antenna1"/>

An optional captcha-key attribute represents a key supplied by Google Docs as a part of a CAPTCHA challenge. The value of this attribute can be retrieved from the response using the pipeline:errorInfo function. The captcha-value attribute holds the value provided by the user in response to the CAPTCHA challenge.

The token attribute is mutually exclusive with the user-id and password attributes. The attribute is required by the token-based authentication method, and holds a token provided by the Google AuthSub service. Please note that it is your responsibility to obtain and maintain tokens.

<gdocs:authenticate token="DQAAAIQ..."/>

Listing available documents

The gdocs:list-docs element lists documents that belong to the specified user. Its category attribute defines the category of documents to return. This is a required attribute, and its value must be set to 'document'. The query attribute allows you to search documents by an arbitrary string. If specified, then only the documents that contain this string will be returned.

The xml:id attribute is used by the pipeline:errorSourceID function to identify the gdocs:list-docs or gdocs:fetch elements.

As the number of returned documents may be large, the response can be split into pages. You can specify the maximum number of documents in each response page using the page-size attribute. The page-index attribute specifies the number of a page to be returned. 

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:pipeline="http://www.volantis.com/xmlns/marlin-pipeline"
  xmlns:gdocs="http://www.volantis.com/xmlns/2008/08/gdocs">
  <head>
    <title>gdocs:list-docs</title>
  </head>
  <body>
    <div>
      <pipeline:transform href="list2xdime.xsl">
        <gdocs:list-docs xml:id="first-list" category="document">
          <gdocs:authenticate user-id="antennatests@gmail.com" password="1antenna1"/>
        </gdocs:list-docs>
      </pipeline:transform>
    </div>
  </body>
</html>

The Google Docs service returns the list of available documents in the form of a feed. You must use an XSL transform to convert the feed to an XDIME presentation markup.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:atom="http://www.w3.org/2005/Atom"
  version="2.0">
  <xsl:template match="atom:feed">
    <h1>
      <xsl:value-of select="atom:title"/>
    </h1>
    <xsl:for-each select="atom:entry">
      <div>
        <a>
          <xsl:attribute name="href">
            <xsl:value-of select="atom:content/@src"/>
          </xsl:attribute>
          <xsl:value-of select="atom:title"/>
        </a>
      </div>
    </xsl:for-each>
  </xsl:template>
</xsl:stylesheet>

Accessing the contents of documents

You use the gdocs:fetch element to embed a single document from Google Docs in an XDIME page. The href attribute specifies the URL of a document to retrieve. The category attribute must be set to 'document'.

Note:

The format of the URL is determined solely by Google Docs. It is recommended to use a URL that was returned in the response from a previous use of the gdocs:list-docs operation. The src attribute of the atom:content element in a feed returned by Google Docs contains valid URL.

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:pipeline="http://www.volantis.com/xmlns/marlin-pipeline"
  xmlns:gdocs="http://www.volantis.com/xmlns/2008/08/gdocs">
  <head>
    <title>gdocs:fetch</title>
    <link rel="mcs:layout" href="test.mlyt"/>
  </head>
  <body>
    <div>
      <pipeline:transform href="fetch2xdime.xsl">
        <gdocs:fetch xml:id="first fetch"
          href="https://docs.google.com/feeds/download/documents/Export?docID=dcg224t7_2d92rmb64&amp;exportFormat=html">
          <gdocs:authenticate user-id="antennatests@gmail.com" password="1antenna1"/>
        </gdocs:fetch>
      </pipeline:transform>
    </div>
  </body>
</html>

The Google Docs service returns the contents of the requested document as HTML. You must use an XSL transform to convert the response to XDIME. Refer to gdocs:fetch for an example of such a transformation.

An XDIME fragment returned by the pipeline operation must be targeted at a region. Note that if the layout is not specified explicitly, then the current container is automatically set to the anonymous region. Refer to the topic entitled XDIME 2 in layouts for more information.

Note:

You can find more XDIME examples illustrating the use of this connector in the ${MCS_HOME}/webapps/mcs.war/projects/connectors/gdocs directory.

Handling errors

The connector supports the use of the pipeline error functions. These functions enable trapping and handling errors that occur during pipeline processing. The following table lists all the errors supported by the connector. The errors are in the http://www.volantis.com/xmlns/2008/08/gdata namespace. Refer to the topics entitled Handling pipeline errors and Pipeline error functions for more information about the pipeline error functions.

Name Description
authentication-failure

An error due to missing or incorrect authentication information.

The following error properties are accessible using the pipeline:errorInfo function: 'captcha-key', 'captcha-url' and 'login'. The 'captcha-key' property identifies the CAPTCHA challenge and is passed back to Google Docs along with the answer provided by the user. The 'captcha-url' property contains the URL to the image, which the user must interpret in order to answer the CAPTCHA challenge. The 'login' property provides feedback on the login credentials. Possible values are: 'valid' and 'invalid'. If 'invalid' is returned, then the user must re-enter her/his login information.
Failed Errors, other than authentication failures, from which there is now way to recover.

Related topics