The File IO API

The File I/O API

All functions in the File I/O API are methods of the DWfile object.

DWfile.copy()

Availability

Dreamweaver 3.

Description

This function copies the specified file to a new location.

Arguments

 originalURL, copyURL 

• The originalURL argument, which is expressed as a file:// URL, is the file you want to copy.

• The copyURL argument, which is expressed as a file:// URL, is the location where you want to save the copied file.

Returns

A Boolean value: true if the copy succeeds; false otherwise.

Example

The following code copies a file called myconfig.cfg to myconfig_backup.cfg:

 var fileURL = "file:///c|/Config/myconfig.cfg"; var newURL ="file:///c|/Config/myconfig_backup.cfg"; DWfile.copy(fileURL, newURL); 

DWfile.createFolder()

Availability

Dreamweaver 2.

Description

This function creates a folder at the specified location.

Arguments

 folderURL 

• The folderURL argument, which is expressed as a file:// URL, is the location of the folder you want to create.

Returns

A Boolean value: true if the folder is created successfully; false otherwise.

Example

The following code tries to create a folder called tempFolder at the top level of the C drive and displays an alert box that indicates whether the operation was successful:

 var folderURL = "file:///c|/tempFolder"; if (DWfile.createFolder(folderURL)){   alert("Created " + folderURL); }else{   alert("Unable to create " + folderURL); } 

DWfile.exists()

Availability

Dreamweaver 2.

Description

This function tests for the existence of the specified file.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the requested file.

Returns

A Boolean value: true if the file exists; false otherwise.

Example

The following code checks for the mydata.txt file and displays an alert message that tells the user whether the file exists:

 var fileURL = "file:///c|/temp/mydata.txt"; if (DWfile.exists(fileURL)){   alert(fileURL + " exists!"); }else{   alert(fileURL + " does not exist."); } 

DWfile.getAttributes()

Availability

Dreamweaver 2.

Description

This function gets the attributes of the specified file or folder.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file or folder for which you want to get attributes.

Returns

A string that represents the attributes of the specified file or folder. If the file or folder does not exist, this function returns a null value. The following characters in the string represent the attributes:

• R is read only.

• D is folder.

• H is hidden.

• S is system file or folder.

Example

The following code gets the attributes of the mydata.txt file and displays an alert box if the file is read only:

 var fileURL = "file:///c|/temp/mydata.txt"; var str = DWfile.getAttributes(fileURL); if (str && (str.indexOf("R") != -1)){   alert(fileURL + " is read only!"); } 

DWfile.getModificationDate()

Availability

Dreamweaver 2.

Description

This function gets the time when the file was last modified.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the last modified time.

Returns

A string that contains a hexadecimal number that represents the number of time units that have elapsed since some base time. The exact meaning of time units and base time is platform-dependent; in Windows, for example, a time unit is 100ns, and the base time is January 1st, 1600.

Example

It's useful to call the function twice and compare the return values because the value that this function returns is platform-dependent and is not a recognizable date and time. The following code example gets the modification dates of file1.txt and file2.txt and displays an alert message that indicates which file is newer:

 var file1 = "file:///c|/temp/file1.txt"; var file2 = "file:///c|/temp/file2.txt"; var time1 = DWfile.getModificationDate(file1); var time2 = DWfile.getModificationDate(file2); if (time1 == time2){   alert("file1 and file2 were saved at the same time"); }else if (time1 < time2){   alert("file1 older that file2"); }else{   alert("file1 is newer than file2"); } 

DWfile.getCreationDate()

Availability

Dreamweaver 4.

Description

This function gets the time when the file was created.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the creation time.

Returns

A string that contains a hexadecimal number that represents the number of time units that have elapsed since some base time. The exact meaning of time units and base time is platform-dependent; in Windows, for example, a time unit is 100ns, and the base time is January 1st, 1600.

Example

You can call this function and the DWfile.getModificationDate() function on a file to compare the modification date to the creation date:

 var file1 = "file:///c|/temp/file1.txt"; var time1 = DWfile.getCreationDate(file1); var time2 = DWfile.getModificationDate(file1); if (time1 == time2){   alert("file1 has not been modified since it was created"); }else if (time1 < time2){   alert("file1 was last modified on " + time2); } 

DWfile.getCreationDateObj()

Availability

Dreamweaver MX.

Description

This function gets the JavaScript object that represents the time when the file was created.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the creation time.

Returns

A JavaScript Date object that represents the date and time when the specified file was created.

DWfile.getModificationDateObj()

Availability

Dreamweaver MX.

Description

This function gets the JavaScript Date object that represents the time when the file was last modified.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the time of the most recent modification.

Returns

A JavaScript Date object that represents the date and time when the specified file was last modified.

DWfile.getSize()

Availability

Dreamweaver MX.

Description

This function gets the size of a specified file.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the size.

Returns

An integer that represents the actual size, in bytes, of the specified file.

DWfile.listFolder()

Availability

Dreamweaver 2.

Description

This function gets a list of the contents of the specified folder.

Arguments

 folderURL, {constraint} 

• The folderURL argument is the folder for which you want a contents list, which is expressed as a file:// URL, plus an optional wildcard file mask. Valid wildcards are asterisks (*), which match one or more characters, and question marks (?), which match a single character.

• The constraint argument, if it is supplied, must be either "files" (return only files) or "directories" (return only folders). If it is omitted, the function returns files and folders.

Returns

An array of strings that represents the contents of the folder.

Example

The following code gets a list of all the text (TXT) files in the C:/temp folder and displays the list in an alert message:

 var folderURL = "file:///c|/temp"; var fileMask = "*.txt"; var list = DWfile.listFolder(folderURL + "/" + fileMask, "files"); if (list){   alert(folderURL + " contains: " + list.join("\n")); } 

DWfile.read()

Availability

Dreamweaver 2.

Description

This function reads the contents of the specified file into a string.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file you want to read.

Returns

A string that contains the contents of the file or a null value if the read fails.

Example

The following code reads the mydata.txt file and, if it is successful, displays an alert message with the contents of the file:

 var fileURL = "file:///c|/temp/mydata.txt"; var str = DWfile.read(fileURL); if (str){   alert(fileURL + " contains: " + str); } 

DWfile.remove()

Availability

Dreamweaver 3.

Description

This function deletes the specified file.

Arguments

 fileURL 

• The fileURL argument, which is expressed as a file:// URL, is the file you want to remove.

Returns

A Boolean value: TRue value if the operation succeeds; false otherwise.

Example

The following example uses the DWfile.getAttributes() function to determine whether the file is read-only and the confirm() function to display a Yes/No dialog box to the user:

 function deleteFile(){   var delAnyway = false;   var selIndex = document.theForm.menu.selectedIndex;   var selFile = document.theForm.menu.options[selIndex].value;   if (DWfile.getAttributes(selFile).indexOf('R') != -1){     delAnyway = confirm('This file is read-only. Delete anyway?');     if (delAnyway){       DWfile.remove(selFile);      }   } } 

DWfile.setAttributes()

Availability

Dreamweaver MX.

Description

This function sets the system-level attributes of a particular file.

Arguments

 fileURL, strAttrs 

• The fileURL argument, which is expressed as a file:// URL, identifies the file for which you are setting the attributes.

• The strAttrs argument specifies the system-level attributes for the file that is identified by the fileURL argument. The following table describes valid attribute values and their meaning:

  Attribute Value	Description
  R	Read only
  W	Writable (overrides R)
  H	Hidden
  V	Visible (overrides H)

  
  

  Acceptable values for the strAttrs string are R, W, H, V, RH, RV, WH, or WV.

  You should not use R and W together because they are mutually exclusive. If you combine them, R becomes meaningless, and the file is set as writable (W). You should not use H and V together because they are also mutually exclusive. If you combine them, H becomes meaningless, and the file is set as visible (V).

  If you specify H or V without specifying an R or W read/write attribute, the existing read/write attribute for the file is not changed. Likewise, if you specify R or W, without specifying an H or V visibility attribute, the existing visibility attribute for the file is not changed.

Returns

Nothing.

DWfile.write()

Availability

Dreamweaver 2.

Description

This function writes the specified string to the specified file. If the specified file does not yet exist, it is created.

Arguments

 fileURL, text, {mode} 

• The fileURL argument, which is expressed as a file:// URL, is the file to which you are writing.

• The text argument is the string to be written.

• The mode argument, if it is supplied, must be "append". If this argument is omitted, the contents of the file are overwritten by the string.

Returns

A Boolean value: TRue if the string is successfully written to the file; false otherwise.

Example

The following code attempts to write the string "xxx" to the mydata.txt file and displays an alert message if the write operation succeeds. It then tries to append the string "aaa" to the file and displays a second alert if the write succeeds. After executing this script, the mydata.txt file contains the text xxxaaa and nothing else.

 var fileURL = "file:///c|/temp/mydata.txt"; if (DWfile.write(fileURL, "xxx")){   alert("Wrote xxx to " + fileURL); } if (DWfile.write(fileURL, "aaa", "append")){   alert("Appended aaa to " + fileURL); }