Google Apps Script

Class Folder

A folder contains methods to create, find, and access files inside of itself.

 
// This example gets a folder named 'kittens' and logs the files it contains.
 var folder = DocsList.getFolder('kittens');
 var files = folder.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Methods

MethodReturn typeBrief description
addEditor(emailAddress)FolderAdds the given user to the list of editors for the Folder.
addEditor(user)FolderAdds the given user to the list of editors for the Folder.
addEditors(emailAddresses)FolderAdds the given array of users to the list of editors for the Folder.
addToFolder(parent)voidAdds the item to the given folder.
addViewer(emailAddress)FolderAdds the given user to the list of viewers for the Folder.
addViewer(user)FolderAdds the given user to the list of viewers for the Folder.
addViewers(emailAddresses)FolderAdds the given array of users to the list of viewers for the Folder.
createFile(blob)FileCreates a file using the data stored in this blob.
createFile(name, contents)FileCreates a file with the given name and contents in the current folder.
createFile(name, contents, mimeType)FileCreates a file with the given name and contents in the current folder with the given MIME type.
createFolder(name)FolderCreates a sub-folder with the given name in the current folder.
find(query)File[]Returns an array of all the files in the container that contain the given string.
findForPaging(query, number)FilesResultReturns the next number files maching the search query and a paging token.
findForPaging(query, number, token)FilesResultReturns the next number files maching the search query, picking up from where the token from the previous lookup left off.
getDateCreated()DateGets the date that this item was created.
getDescription()StringReturns the description of the item or null if a description doesn't exist.
getEditors()User[]Gets the list of editors for this Folder.
getFiles()File[]Returns all the files in the container (up to a maximum of DocsList.DEFAULT_RESULT_SIZE).
getFilesByType(type)File[]Returns all files of a given type.
getFilesByTypeForPaging(type, number)FilesResultReturns the next number files of the given type in this container and a paging token.
getFilesByTypeForPaging(type, number, token)FilesResultReturns the next number files of the given type in this container, picking up from where the token from the previous lookup left off.
getFilesForPaging(number)FilesResultReturns the next number files in this container and a paging token.
getFilesForPaging(number, token)FilesResultReturns the next number files in this container, picking up from where the token from the previous lookup left off.
getFolders()Folder[]Returns all the folders in this container (up to a maximum of DocsList.DEFAULT_RESULT_SIZE).
getFoldersForPaging(number)FoldersResultReturns the first number of folders in this container and a paging token.
getFoldersForPaging(number, token)FoldersResultReturns the next number folders in this container, picking up from where the token from the previous lookup left off.
getId()StringReturns the document ID associated with the item.
getLastUpdated()DateGets the date that this item was last updated.
getName()StringReturns the name of the item.
getOwner()UserGets the owner of the item.
getParents()Folder[]Returns the parent folders.
getSize()IntegerReturns the amount of disk space used by the item.
getUrl()StringReturns a URL to access the particular item.
getViewers()User[]Gets the list of viewers and commenters for this Folder.
isStarred()BooleanGets whether the item is starred.
isTrashed()BooleanChecks whether the item is trashed.
removeEditor(emailAddress)FolderRemoves the given user from the list of editors for the Folder.
removeEditor(user)FolderRemoves the given user from the list of editors for the Folder.
removeFromFolder(parent)voidRemoves this object from the given folder.
removeViewer(emailAddress)FolderRemoves the given user from the list of viewers and commenters for the Folder.
removeViewer(user)FolderRemoves the given user from the list of viewers and commenters for the Folder.
rename(newName)voidRename the item.
setDescription(description)voidUpdate's the item's description.
setStarred(starred)voidSets the item's starred status in drive.
setTrashed(trash)voidSets the trashed status of an item but does not permanently delete it.

Detailed documentation

addEditor(emailAddress)

Adds the given user to the list of editors for the Folder. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

Folder — this Folder, for chaining


addEditor(user)

Adds the given user to the list of editors for the Folder. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

NameTypeDescription
userUsera representation of the user to add

Return

Folder — this Folder, for chaining


addEditors(emailAddresses)

Adds the given array of users to the list of editors for the Folder. If any of the users were already on the list of viewers, this method promotes them out of the list of viewers.

Parameters

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

Folder — this Folder, for chaining


addToFolder(parent)

Adds the item to the given folder.

 
// This example creates a new file and adds it to a folder
 // Note: This can also be used on a folder to add it to another folder
 var file = DocsList.createFile('my test file', 'test file contents');
 var folder = DocsList.createFolder('My Test Folder');
 file.addToFolder(folder);
 Logger.log(file.getParents()[0].getName()); // logs 'My Test Folder'
 

Parameters

NameTypeDescription
parentFolderthe folder to add the item to

addViewer(emailAddress)

Adds the given user to the list of viewers for the Folder. If the user was already on the list of editors, this method has no effect.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

Folder — this Folder, for chaining


addViewer(user)

Adds the given user to the list of viewers for the Folder. If the user was already on the list of editors, this method has no effect.

Parameters

NameTypeDescription
userUsera representation of the user to add

Return

Folder — this Folder, for chaining


addViewers(emailAddresses)

Adds the given array of users to the list of viewers for the Folder. If any of the users were already on the list of editors, this method has no effect for them.

Parameters

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

Folder — this Folder, for chaining


createFile(blob)

Creates a file using the data stored in this blob.

 
// Fetches the Google logo and saves it to a folder
 var url = 'https://www.google.com/images/srpr/logo3w.png';
 var imageBlob = UrlFetchApp.fetch(url).getBlob();
 var folder = DocsList.createFolder('my folder');
 folder.createFile(imageBlob);
 

Parameters

NameTypeDescription
blobBlobSourcethe blob to create the file from

Return

File — the newly created file


createFile(name, contents)

Creates a file with the given name and contents in the current folder. If the file name does not contain an extension, it defaults to plain text.

 
// Creates a file called 'new kitten' in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 folder.createFile('new kitten', 'meow');
 

Parameters

NameTypeDescription
nameStringthe name of the new file
contentsStringthe contents of the new file

Return

File — the newly created file


createFile(name, contents, mimeType)

Creates a file with the given name and contents in the current folder with the given MIME type. If the file name does not contain an extension, it defaults to plain text.

 
// Creates a simple XML file in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var contents = '<kitten><name>Tiny</name><age>1</age></kitten>';
 folder.createFile('kittens.xml', contents, 'application/xml');
 

Parameters

NameTypeDescription
nameStringthe name of the new file
contentsStringthe new file contents
mimeTypeStringthe mime-type of the new file

Return

File — the newly created file


createFolder(name)

Creates a sub-folder with the given name in the current folder.

 
// Creates a subfolder in a folder called 'cats'
 var folder = DocsList.createFolder('cats');
 folder.createFolder('cool cats');
 

Parameters

NameTypeDescription
nameStringthe name of the new folder

Return

Folder — the newly created folder


find(query)

Returns an array of all the files in the container that contain the given string.

 
// Logs the name of all the files resulting from a search for 'cool cats'
 var folder = DocsList.getFolder('cats');
 var coolCats = folder.find('cool cats');
 for (var i in coolCats) {
   Logger.log(coolCats[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string

Return

File[] — the matching files


findForPaging(query, number)

Returns the next number files maching the search query and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the name of the first 3 files resulting from a search for 'cool cats'
 var folder = DocsList.getFolder('cats');
 var filesResult = folder.findForPaging('cool cats', 3);
 var files = FilesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string
numberIntegerthe number of objects to return

Return

FilesResult — the requested number of matching files and a paging token


findForPaging(query, number, token)

Returns the next number files maching the search query, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 file names resulting from a search but does it 3 at
 // a time.
 var folder = DocsList.getFolder('cats');
 var filesResult = folder.findForPaging('cool cats', 3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 filesResult = folder.findForPaging('cool cats', 3, token); // pass in previous token
 files = filesResult.getFiles();
 // log the next 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string
numberIntegerthe number of objects to return
tokenTokenthe token from the previous lookup

Return

FilesResult — the requested number of matching files and a paging token


getDateCreated()

Gets the date that this item was created.

 
// This example logs the date the first file was created.
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getDateCreated());
 

Return

Date — the date this item was created


getDescription()

Returns the description of the item or null if a description doesn't exist.

 
// Gets the first document's description.
 // Note: This can also be used on a folder
 var doc = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(doc.getDescription());
 

Return

String — the item's description


getEditors()

Gets the list of editors for this Folder. If the user who executes the script does not have edit access to the Folder, this method throws an exception.

Return

User[] — an array of users with edit permission


getFiles()

Returns all the files in the container (up to a maximum of DocsList.DEFAULT_RESULT_SIZE).

 
// Logs the number of files in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var files = folder.getFiles();
 Logger.log(files.length);
 

Return

File[] — the requested files


getFilesByType(type)

Returns all files of a given type. See FileType for the list of possible file types.

 
// Logs the names of the first document in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var file = folder.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(file.getName());
 

Parameters

NameTypeDescription
typeFileTypethe type of files to get

Return

File[] — the requested files

See also


getFilesByTypeForPaging(type, number)

Returns the next number files of the given type in this container and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 3 document names (or less if there are fewer
 // than 3 documents) from the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3);
 var files = FilesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
typeFileTypethe type of files to get
numberIntegerthe number of files to get

Return

FilesResult — the requested files and a paging token

See also


getFilesByTypeForPaging(type, number, token)

Returns the next number files of the given type in this container, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 document names in the 'kittens' folder but does it 3 at
 // a time.
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 document names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 // pass in previous token
 filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3, token);
 files = filesResult.getFiles();
 // log the next 3 document names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
typeFileTypethe type of files to return
numberIntegerthe number of files to return
tokenTokenthe token from the previous lookup

Return

FilesResult — the requested files and paging token


getFilesForPaging(number)

Returns the next number files in this container and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 3 file names (or less if there are fewer
 // than 3 files) from the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(3);
 var files = filesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of files to return

Return

FilesResult — the requested files and paging token


getFilesForPaging(number, token)

Returns the next number files in this container, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 file names in the 'kittens' folder but does it 3 at
 // a time.
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 filesResult = folder.getFilesForPaging(3, token); // pass in previous token
 files = filesResult.getFiles();
 // log the next 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of files to return
tokenTokenthe paging token from the previous lookup

Return

FilesResult — the requested files and paging token


getFolders()

Returns all the folders in this container (up to a maximum of DocsList.DEFAULT_RESULT_SIZE).

 
// Logs the number of folders in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var subFolders = folder.getFolders();
 Logger.log(subFolders.length);
 

Return

Folder[] — the requested folders


getFoldersForPaging(number)

Returns the first number of folders in this container and a paging token. If the requested number of folders do not exist, it returns the available folders.

 
// Logs the first 3 folder names (or less if there are fewer
 // than 3 folders) from the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var subFoldersResult = folder.getFoldersForPaging(3);
 var subFolders = subFoldersResult.getFolders();
 for (var i in subFolders) {
   Logger.log(subFolders[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of folders to return

Return

FoldersResult — the requested folders and a paging token


getFoldersForPaging(number, token)

Returns the next number folders in this container, picking up from where the token from the previous lookup left off. If the requested number of folders do not exist, it returns the available folders.

 
// Logs the first 6 folder names in the 'kittens' folder but does it 3 at
 // a time.
 var folder = DocsList.getFolder('kittens');
 var foldersResult = folder.getFoldersForPaging(3);
 var subFolders = foldersResult.getFolders();
 var token = foldersResult.getToken();
 // log the first 3 sub folder names
 for (var i in subFolders) {
   Logger.log(subFolders[i].getName());
 }
 folderResult = folder.getAllFoldersForPaging(3, token); // pass in previous token
 subFolders = foldersResult.getFolders();
 // log the next 3 sub folder names
 for (var i in subFolders) {
   Logger.log(subFolders[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of folders to return
tokenTokenthe token from the previous lookup

Return

FoldersResult — the requested folders and paging token


getId()

Returns the document ID associated with the item.

 
// Logs the first file's document ID.
 // Note: This can also be used on a folder.
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getId());
 

Return

String — the document ID of the item


getLastUpdated()

Gets the date that this item was last updated.

 
// This example logs the date the first file was last updated.
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getLastUpdated());
 

Return

Date — the date this item was last updated


getName()

Returns the name of the item.

 
// Logs the first file's name.
 // Note: This can also be used on a folder.
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getName());
 

Return

String — the name of the item


getOwner()

Gets the owner of the item.

 
// This example creates a file and logs the owner's email address
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 Logger.log(file.getOwner().getEmail()); // logs your own email address
 

Return

User — the owner of the item


getParents()

Returns the parent folders. If called on a top level item, it returns the root folder. An item can be placed in multiple folders in drive. See the drive documentation.

 
// This example logs the name of the parent folder of the first doc.
 // Note: This can also be used on a folder to get its parent
 var file = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(file.getParents()[0].getName());
 

Return

Folder[] — the parent folders containing the item


getSize()

Returns the amount of disk space used by the item. Note that it returns zero if called on an item that does not consume disk space, such as a Google document type file.

 
// This example logs the first file's size in bytes
 // Note: This can also be used on a folder to get the size of its contents
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getSize());
 

Return

Integer — the item's size in bytes, or zero if the item is a Google document type or does not consume space


getUrl()

Returns a URL to access the particular item.

 
// This example logs the first file's URL
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getUrl());
 

Return

String — the item's URL


getViewers()

Gets the list of viewers and commenters for this Folder. If the user who executes the script does not have edit access to the Folder, this method throws an exception.

Return

User[] — an array of users with view or comment permission


isStarred()

Gets whether the item is starred.

 
// This example creates a new file, stars it, and tests whether it is starred.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setStarred(true); // the file should be starred in drive
 Logger.log(file.isStarred()); // logs true
 

Return

Boolean — true if the item is starred


isTrashed()

Checks whether the item is trashed.

 
// This example creates a new file and then sets it trashed.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setTrashed(true); // the file should be trashed in drive
 Logger.log(file.isTrashed()); // logs true
 

Return

Boolean — true if the item is trashed


removeEditor(emailAddress)

Removes the given user from the list of editors for the Folder. This method does not block users from accessing the Folder if they belong to a class of users who have general access — for example, if the Folder is shared with the user's entire domain.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

Folder — this Folder, for chaining


removeEditor(user)

Removes the given user from the list of editors for the Folder. This method does not block users from accessing the Folder if they belong to a class of users who have general access — for example, if the Folder is shared with the user's entire domain.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

Folder — this Folder, for chaining


removeFromFolder(parent)

Removes this object from the given folder. If the item does not belong to the folder, this does nothing.

 
// This example creates a new file, adds it to a folder, and then removes
  // it from the folder.
 // Note: This can also be used on a folder to remove it from another folder
 var file = DocsList.createFile('my test file', 'test file contents');
 var folder = DocsList.createFolder('My Test Folder');
 file.addToFolder(folder);
 Logger.log(folder.getFiles().length); // logs 1
 file.removeFromFolder(folder);
 Logger.log(folder.getFiles().length); // logs 0
 

Parameters

NameTypeDescription
parentFolderthe folder to remove the item from

removeViewer(emailAddress)

Removes the given user from the list of viewers and commenters for the Folder. This method has no effect if the user is an editor, not a viewer or commenter. This method also does not block users from accessing the Folder if they belong to a class of users who have general access — for example, if the Folder is shared with the user's entire domain.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

Folder — this Folder for chaining


removeViewer(user)

Removes the given user from the list of viewers and commenters for the Folder. This method has no effect if the user is an editor, not a viewer. This method also does not block users from accessing the Folder if they belong to a class of users who have general access — for example, if the Folder is shared with the user's entire domain.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

Folder — this Folder for chaining


rename(newName)

Rename the item.

 
// Creates a file called 'Old File' and renames it 'New File'.
 // Note: This can also be used on a folder
 var oldFile = DocsList.createFile('Old File', '');
 oldFile.rename('New File');
 Logger.log(oldFile.getName()); // This should log "New File"
 

Parameters

NameTypeDescription
newNameStringthe new name of the item

setDescription(description)

Update's the item's description.

 
// This example sets the first document's description
 // Note: This can also be used on a folder
 var doc = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 doc.setDescription('My First Doc');
 Logger.log(doc.getDescription()); // logs 'My First Doc'
 

Parameters

NameTypeDescription
descriptionStringthe item's description

setStarred(starred)

Sets the item's starred status in drive.

 
// This example creates a new file and stars it.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setStarred(true); // the file should be starred in drive
 

Parameters

NameTypeDescription
starredBooleanstars the item if true; unstars it if false

setTrashed(trash)

Sets the trashed status of an item but does not permanently delete it.

 
// This example creates a new file and then sets it trashed.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setTrashed(true); // the file should be trashed in drive
 Logger.log(file.isTrashed()); // logs true
 

Parameters

NameTypeDescription
trashBooleantrashes the item if true; untrashes it if false

Deprecated methods






Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.