Out of all the features included in Appcelerator Titanium which sets it apart from a conventional web application is not things like the SQLite database, which is included in the HTML 5 spec, and so will be in browsers everywhere soon, or the menu system, which can be easily replicated using CSS, but rather, it is Titanium’s ability to read and write files to and from the local file system that truly makes the platform a desktop-friendly platform, while keeping the flexibility of a web app.

File access in Titanium is very similar to how it is done in other languages like PHP or C#. The objects used are the File and FileStream objects, and the Titanium.Filesystem namespace.

So, to write some data to a file, the code is as follows:

   var contents = "Some contents to write";
   var filename = 'test.txt';
   var userDir = Titanium.Filesystem.getUserDirectory();
   var writeFile = Titanium.Filesystem.getFile(userDir, filename);
   var writeStream = Titanium.Filesystem.getFileStream(writeFile);

Titanium.Filesystem.getUserDirectory() gets the user directory of the currently logged in user. Other useful options here are getDocumentsDirectory(), getApplicationDirectory() and getDesktopDirectory(). The directory can also be a string representing any folder on the user’s machine but these functions provide a cross-platform method of obtaining the most common directories needed.

We then get the full file path as a string, using the directory (in this case the user directory) and the filename, after which we create an instance of the file stream, using the file path as a parameter.

Once we have created the file stream, we need to open the stream. For write access, we set the parameter to Titanium.Filesystem.MODE_WRITE.

All we need to do to write data to the file is call writeStream.write(contents) where contents is any arbitrary variable. To write data line by line we can use .writeLine().

Once we are done writing, we need to close the stream.

If the file we are trying to write to does not exist, then a new file will be created. If the file already exists then the original file will be overwritten. If you need to preserve the original file you can use Titanium.Filesystem.MODE_APPEND as the parameter when opening the stream, which will allow you to add data to the end of an existing file.

To read data from a file is just as easy:

   var readContents;
   var filename = 'test.txt';
   var userDir = Titanium.Filesystem.getUserDirectory();
   var readFile = Titanium.Filesystem.getFile(userDir, filename);
   if (readFile.exists()){
      var readStream = Titanium.Filesystem.getFileStream(readFile);
      readContents = readStream.read();

The main differences to the code for writing compared to reading files, is that before we can open the file stream, we need to make sure the file exists first.

If the file exists we can create the instance of the stream, and then open the stream in read mode.

Once that is open we can call readStream.read() to read the contents of the file, which we can then store in a variable. We can also use .readLine() if wewant to read the data line by line, instead of as one large chunk.

For more information on the file access objects in Titanium, you can refer to the Titanium API Documentation.