file

(plugins.file)

Returned Types

JSFile,JSProgressMonitor,

Methods Summarized

Methods Detailed

appendToTXTFile(file, text)

Appends a string given in parameter to a file, using default platform encoding.

Parameters

• JSFile file a local JSFile

• String text the text to append to the file

Returns: Boolean true if appending worked

Sample

// append some text to a text file:
	var ok = plugins.file.appendToTXTFile('myTextFile.txt', '\nMy fantastic new line of text\n');

appendToTXTFile(file, text, encoding)

Appends a string given in parameter to a file, using the specified encoding.

Parameters

• JSFile file a local JSFile

• String text the text to append to the file

• String encoding the encoding to use

Returns: Boolean true if appending worked

Sample

// append some text to a text file:
	var ok = plugins.file.appendToTXTFile('myTextFile.txt', '\nMy fantastic new line of text\n');

appendToTXTFile(file, text)

Appends a string given in parameter to a file, using default platform encoding.

Parameters

• String file the file path as a String

• String text the text to append to the file

Returns: Boolean true if appending worked

Sample

// append some text to a text file:
	var ok = plugins.file.appendToTXTFile('myTextFile.txt', '\nMy fantastic new line of text\n');

appendToTXTFile(file, text, encoding)

Appends a string given in parameter to a file, using the specified encoding.

Parameters

• String file the file path as a String

• String text the text to append to the file

• String encoding the encoding to use

Returns: Boolean

Sample

// append some text to a text file:
	var ok = plugins.file.appendToTXTFile('myTextFile.txt', '\nMy fantastic new line of text\n');

convertToJSFile(file)

Returns a JSFile instance corresponding to an alternative representation of a file (for example a string).

Parameters

• Object file ;

Returns: JSFile JSFile

Sample

var f = plugins.file.convertToJSFile("story.txt");
if (f.canRead())
	application.output("File can be read.");

convertToRemoteJSFile(path)

Convenience return to get a JSFile representation of a server file based on its path.

Parameters

• String path the path representing a file on the server (should start with "/")

Returns: JSFile the JSFile

Sample

var f = plugins.file.convertToRemoteJSFile('/story.txt');
if (f && f.canRead())
	application.output('File can be read.');

copyFile(source, destination)

Copies the source file to the destination file. Returns true if the copy succeeds, false if any error occurs.

Parameters

• Object source ;

• Object destination ;

Returns: Boolean

Sample

// Copy based on file names.
if (!plugins.file.copyFile("story.txt", "story.txt.copy"))
	application.output("Copy failed.");
// Copy based on JSFile instances.
var f = plugins.file.createFile("story.txt");
var fcopy = plugins.file.createFile("story.txt.copy2");
if (!plugins.file.copyFile(f, fcopy))
	application.output("Copy failed.");

copyFolder(source, destination)

Copies the sourcefolder to the destination folder, recursively. Returns true if the copy succeeds, false if any error occurs.

Parameters

• Object source ;

• Object destination ;

Returns: Boolean success boolean

Sample

// Copy folder based on names.
if (!plugins.file.copyFolder("stories", "stories_copy"))
	application.output("Folder copy failed.");
// Copy folder based on JSFile instances.
var d = plugins.file.createFile("stories");
var dcopy = plugins.file.createFile("stories_copy_2");
if (!plugins.file.copyFolder(d, dcopy))
	application.output("Folder copy failed.");

createFile(targetFile)

Creates a JSFile instance. Does not create the file on disk.

Parameters

• Object targetFile ;

Returns: JSFile

Sample

// Create the JSFile instance based on the file name.
var f = plugins.file.createFile("newfile.txt");
// Create the file on disk.
if (!f.createNewFile())
	application.output("The file could not be created.");

createFolder(destination)

Creates the folder by the given pathname, including anynecessary but nonexistent parent folders. Note that if this operation fails it may have succeeded in creating some of the necessary parent folders. Will return true if it could make this folder or if the folder did already exist.

Parameters

• Object destination ;

Returns: Boolean

Sample

var d = plugins.file.convertToJSFile("newfolder");
if (!plugins.file.createFolder(d))
	application.output("Folder could not be created.");

createTempFile(prefix, suffix)

Creates a temporary file on disk. A prefix and an extension are specified and they will be part of the file name.

Parameters

• String prefix ;

• String suffix ;

Returns: JSFile

Sample

var tempFile = plugins.file.createTempFile('myfile','.txt');
application.output('Temporary file created as: ' + tempFile.getAbsolutePath());
plugins.file.writeTXTFile(tempFile, 'abcdefg');

deleteFile(destination)

Removes a file from disk. Returns true on success, false otherwise.

Parameters

• Object destination ;

Returns: Boolean

Sample

if (plugins.file.deleteFile('story.txt'))
	application.output('File deleted.');

//In case the file to delete is a remote file:
var file = plugins.file.convertToRemoteJSFile('/story.txt');
plugins.file.deleteFile(file);

deleteFolder(destination, showWarning)

Deletes a folder from disk recursively. Returns true on success, false otherwise. If the second parameter is set to true, then a warning will be issued to the user before actually removing the folder.

Parameters

• Object destination ;

• Boolean showWarning ;

Returns: Boolean

Sample

if (plugins.file.deleteFolder('stories', true))
	application.output('Folder deleted.');

//In case the file to delete is a remote folder:
plugins.file.deleteFolder(plugins.file.convertToRemoteJSFile('/stories'), true);

getDefaultUploadLocation()

Returns the default upload location path of the server.

Returns: String the location as canonical path

Sample

// get the (server-side) default upload location path:
var serverPath = plugins.file.getDefaultUploadLocation();

getDesktopFolder()

Returns a JSFile instance that corresponds to the Desktop folder of the currently logged in user.

Returns: JSFile

Sample

var d = plugins.file.getDesktopFolder();
application.output('desktop folder is: ' + d.getAbsolutePath());

getDiskList()

Returns an Array of JSFile instances correponding to the file system root folders.

Returns: Array

Sample

var roots = plugins.file.getDiskList();
for (var i = 0; i < roots.length; i++)
	application.output(roots[i].getAbsolutePath());

getFileSize(fileOrPath)

Returns the size of the specified file.

Parameters

• Object fileOrPath can be a (remote) JSFile or a local file path

Returns: Number

Sample

var f = plugins.file.convertToJSFile('story.txt');
application.output('file size: ' + plugins.file.getFileSize(f));

//In case the file is remote, located on the server side inside the default upload folder:
var f = plugins.file.convertToRemoteJSFile('/story.txt');
application.output('file size: ' + plugins.file.getFileSize(f));

getFolderContents(targetFolder)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder JSFile object.

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption, visibleOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption, visibleOption, lockedOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

• Number lockedOption 1=locked, 2=nonlocked

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• String targetFolder File path.

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• String targetFolder File path.

• Object fileFilter Filter or array of filters for files in folder.

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• String targetFolder File path.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption, visibleOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• String targetFolder File path.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getFolderContents(targetFolder, fileFilter, fileOption, visibleOption, lockedOption)

Returns an array of JSFile instances corresponding to content of the specified folder. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• String targetFolder File path.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

• Number lockedOption 1=locked, 2=nonlocked

Returns: Array

Sample

var files = plugins.file.getFolderContents('stories', '.txt');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

getHomeFolder()

Returns a JSFile instance corresponding to the home folder of the logged in used.

Returns: JSFile

Sample

var d = plugins.file.getHomeFolder();
application.output('home folder: ' + d.getAbsolutePath());

getModificationDate(fileOrPath)

Returns the modification date of a file.

Parameters

• Object fileOrPath can be a (remote) JSFile or a local file path

Returns: Date

Sample

var f = plugins.file.convertToJSFile('story.txt');
application.output('last changed: ' + plugins.file.getModificationDate(f));

//In case the file is remote, located on the server side inside the default upload folder:
var f = plugins.file.convertToRemoteJSFile('/story.txt');
application.output('file size: ' + plugins.file.getModificationDate(f));

getRemoteFolderContents(targetFolder)

Returns an array of JSFile instances corresponding to content of the specified folder on the server side. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder ;

Returns: Array the array of file names

Sample

// retrieves an array of files located on the server side inside the default upload folder:
var files = plugins.file.getRemoteFolderContents(plugins.file.convertToRemoteJSFile('/'), '.txt');

getRemoteFolderContents(targetFolder, fileFilter)

Returns an array of JSFile instances corresponding to content of the specified folder on the server side. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder Folder as JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

Returns: Array the array of file names

Sample

// retrieves an array of files located on the server side inside the default upload folder:
var files = plugins.file.getRemoteFolderContents(plugins.file.convertToRemoteJSFile('/'), '.txt');

getRemoteFolderContents(targetFolder, fileFilter, fileOption)

Returns an array of JSFile instances corresponding to content of the specified folder on the server side. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder Folder as JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

Returns: Array the array of file names

Sample

// retrieves an array of files located on the server side inside the default upload folder:
var files = plugins.file.getRemoteFolderContents(plugins.file.convertToRemoteJSFile('/'), '.txt');

getRemoteFolderContents(targetFolder, fileFilter, fileOption, visibleOption)

Returns an array of JSFile instances corresponding to content of the specified folder on the server side. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder Folder as JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

Returns: Array the array of file names

Sample

// retrieves an array of files located on the server side inside the default upload folder:
var files = plugins.file.getRemoteFolderContents(plugins.file.convertToRemoteJSFile('/'), '.txt');

getRemoteFolderContents(targetFolder, fileFilter, fileOption, visibleOption, lockedOption)

Returns an array of JSFile instances corresponding to content of the specified folder on the server side. The content can be filtered by optional name filter(s), by type, by visibility and by lock status.

Parameters

• JSFile targetFolder Folder as JSFile object.

• Object fileFilter Filter or array of filters for files in folder.

• Number fileOption 1=files, 2=dirs

• Number visibleOption 1=visible, 2=nonvisible

• Number lockedOption 1=locked, 2=nonlocked

Returns: Array the array of file names

Sample

// retrieves an array of files located on the server side inside the default upload folder:
var files = plugins.file.getRemoteFolderContents(plugins.file.convertToRemoteJSFile('/'), '.txt');