Issues

ZF-4976: Add new DocumentsList Data API functionality for Folders

Description

File your documents: You can now create new folders in the API, move documents in and out of folders and have full access to nested folders. (Issue 377, Issue 383)

Comments

Here's an initial patch that adds folder creation support.

Once you patch this in, you can also move and delete folders relatively easily with code outside the Gdata library.

Hi Matthew, Thanks for the patch. Unfortunately, before we can accept your contributions, you need to sign and submit the Zend Framework CLA. This can be found here:

http://framework.zend.com/wiki/display/…

Once this is done and you're added to the zf-framework-dev group in JIRA, let me know and I'll process this patch.

Hi Trevor,

My CLA has been accepted and Hilary has added my account to the contributor group. Please proceed with processing this patch. Thanks!

Thanks Matthew. A couple of suggestions/comments.

  • DOCUMENTS_FOLDER_FEED_URI should not have a trailing '/folder'

  • It would be nice to have an additional (optional) argument $resource_id for creating a folder within another folder. This is similar to creating documents in folders: http://code.google.com/apis/documents/…

public function createFolder($folderName, $folderResourceId=null) { ... if ($folderResourceId != null) { $uri = self::DOCUMENTS_FOLDER_FEED_URI . '/' . $folderResourceId; } else { $uri = self::DOCUMENTS_LIST_FEED_URI; } return $this->insertEntry($entry, $uri); }

You could additionally allow $folderResourceId to be a full URI (http://docs.google.com/feeds/folders/…)

Hi guys,

Sorry it's taken me so long to get back to this. I've implemented Eric's suggestions (thanks Eric) and have attached an updated patch.

Would be great to see this in the next release.

Cheers, Matt

Hi Matt. Looks good. Just a few comments from me.

My comments are preceded with a !. Eric may have additional review comments as well.


--- Docs.php    (revision 20086)
+++ Docs.php    (working copy)
@@ -37,6 +37,12 @@
 require_once 'Zend/Gdata/Docs/DocumentListEntry.php';
 
 /**
+ * App Extensions
+ */

! Because of the way phpdoc works, using this style of comment to group
! require_once statements doesn't work. Please stick with the existing
! convention, namely an @see $CLASS_NAME for each require_once.

+require_once 'Zend/Gdata/App/Extension/Category.php';
+require_once 'Zend/Gdata/App/Extension/Title.php';
+
+/**
  * Service class for interacting with the Google Document List data API
  * @link http://code.google.com/apis/documents/
  *
@@ -50,19 +56,29 @@
 {
 
     const DOCUMENTS_LIST_FEED_URI = 'http://docs.google.com/feeds/documents/…';
+    const DOCUMENTS_FOLDER_FEED_URI = 'http://docs.google.com/feeds/folders/private/full';
+    const DOCUMENTS_CATEGORY_SCHEMA = 'http://schemas.google.com/g/2005#kind';
+    const DOCUMENTS_CATEGORY_TERM = 'http://schemas.google.com/docs/2007#folder';
     const AUTH_SERVICE_NAME = 'writely';
 
     protected $_defaultPostUri = self::DOCUMENTS_LIST_FEED_URI;
 
     private static $SUPPORTED_FILETYPES = array(
+      'TXT'=>'text/plain',
       'CSV'=>'text/csv',
+      'TSV'=>'text/tab-separated-values',
+      'TAB'=>'text/tab-separated-values',
+      'HTML'=>'text/html',
+      'HTM'=>'text/html',
       'DOC'=>'application/msword',
       'ODS'=>'application/vnd.oasis.opendocument.spreadsheet',
       'ODT'=>'application/vnd.oasis.opendocument.text',
       'RTF'=>'application/rtf',
       'SXW'=>'application/vnd.sun.xml.writer',
-      'TXT'=>'text/plain',
-      'XLS'=>'application/vnd.ms-excel');
+      'XLS'=>'application/vnd.ms-excel',
+      'XLSX'=>'application/vnd.ms-excel',
+      'PPT'=>'application/vnd.ms-powerpoint',
+      'PPS'=>'application/vnd.ms-powerpoint');
 
     /**
      * Create Gdata_Docs object
@@ -235,6 +251,31 @@
     }
 
     /**
+     * Creates a new folder in Google Docs
+     *
+     * @param string $folderName The folder name to create
+     * @param string $folderResourceId The parent folder to create it in ("folder%3Amy_parent_folder")

! This actually accepts string|null.

+     *

! Remove extra newline here.

+     * @return boolean
+     */
+    public function createFolder($folderName, $folderResourceId=null) {
+        $category = new Zend_Gdata_App_Extension_Category(self::DOCUMENTS_CATEGORY_TERM, 
+                                                          self::DOCUMENTS_CATEGORY_SCHEMA);
+        $title = new Zend_Gdata_App_Extension_Title($folderName);
+        $entry = new Zend_Gdata_Entry();
+
+        $entry->setCategory(array($category));
+        $entry->setTitle($title);
+
+        $uri = self::DOCUMENTS_LIST_FEED_URI;
+        if ($folderResourceId != null) {
+            $uri = self::DOCUMENTS_FOLDER_FEED_URI . '/' . $folderResourceId;
+        }
+
+        return $this->insertEntry($entry, $uri);
+    }
+
+    /**
      * Inserts an entry to a given URI and returns the response as an Entry.
      *
      * @param mixed  $data The Zend_Gdata_Docs_DocumentListEntry or media

Looks good to me.

Hi guys, I've updated the patch file to include your comments. Hope that makes integration easier.

One last change. I'll just go ahead and make this for you.


 /**
+ * @see Zend_Gdata_App_Extension_Category
+ * @see Zend_Gdata_App_Extension_Title
+ */
+require_once 'Zend/Gdata/App/Extension/Category.php';
+require_once 'Zend/Gdata/App/Extension/Title.php';

Each @see line needs to come immediately before it's respective require_once line.

As it currently stands, Zend_Gdata_App_Extension_Category will have too "See Also" lines in it's documentation, and Zend_Gdata_App_Extension_Title will have none.

Commited to trunk as r20112. Scheduled for next minor release. Thanks for the patch!

I've created ZF-8732 to track some additional changes that need to be made to this, but that don't block integration.

commit 4e85fb9f4d222d2eb8603a4938625520683a8261
Author: tjohns 
Date:   Thu Jan 7 02:39:32 2010 +0000

    ZF-4976: Add createFolder() method to Zend_Gdata_Docs.
    
    Tests and a minor doc changes added by me. All other changes submitted
    via patch.
    
    Patch by: Matthew Romaine (mromaine)
    
    git-svn-id: http://framework.zend.com/svn/framework/… 44c647ce-9c0f-0410-b52a-842

 library/Zend/Gdata/Docs.php   |   51 ++++++++++++++++++++++++++++++++++++-
 tests/Zend/Gdata/DocsTest.php |   55 ++++++++++++++++++++++++++++++++++++++---
 2 files changed, 100 insertions(+), 6 deletions(-)