Device Storage

• Local storage
  persistent storage of string value by key-value, also a string
• Session storage
  same, but removed at end of browser session.
• Application cache
  for offline use. A manifest (example) lists what should be stored in cache
• IndexDB
  SRU has an entire class on databases; simple SQL is beyond the scope of this course

Local Storage API

• localStorage is a PhoneGap object
• methods include: setItem , getItem, and clear
• localStorage.setItem ("key string", "value string");
• var value = localStorage.getItem ("key string");
• window.localStorage.clear();
• You can iterate through local storage:

  for ( var i in localStorage) 
  		alert (localStorage.getItem(i));
  

• Try it! Do steps 4-9 starting on page 67 of your text

Phonegaps two FileSystem API

• W3C Directories and System API
• W3C File API - asynchronous in Phone Gap
• More advanced filesystem APIs available, but not in phonegap. Webworkers (advanced stuff) available in Javascript. Permits quicker/smoother file system access using parallelism

• Through the window object, use the requestFileSystem method of the LocalFileSystem object
• First arguemnt is type of storage
  PERSISTENT - cannot be deleted by user agent without app permission
  TEMPORARY - can be deleted by user agent without app permission
• Second argument is amoung of space in bytes
• Third argument is success handler
• Fourth argument is error handler

  document.addEventListener('deviceready', onDeviceReady, false);
  function onDeviceReady(){
    var size =0;
    window.requestFileSystem(LocalFileSystem.PERSISTENT, size, onFSsuccess, onFSerror);
  }
  

• for reading a file system, use a size of 0
• on success is the function that you will want your code
• on error is the function where you should log or alert the error. The 12 errors and their codes can be found on page 79

  function onFSsuccess(FS){
    var Fin = FS.root.createReader();
    Fin.readEntries(parseDir, onFSerror);
  }
  function onFSerror(err){
    alert ("Error " + err);
  }
  

• note that Fin and FS are not special words and you can rename them to be anything
  Fin indicates we are inputting from a file
  FS stands for File Syste
• readEntries is a method of the Directories and System API (W3C defined)
• readEntries has two arguments - success handler and error handlers

• Directories are tables of information about each file or sub-directory
• Directory entries contain things like file name, file size, creation date,...
• The entries[] array in the API has many atrributes such as isDirectory and fullPath

  function parseDir (entries) {
    var dirs='Directories:<ul>';
    var files='Files: <ul>';
    for (var i=0, len=entries.length; i< len; i++) {
  	if (entries[i].isDirectory) {
      	dirs +='<li>' + entries[i].fullPath+ '</li>';
  	}
  	else
  		files +='<li>' + entries[i].fullPath+ '</li>'; 
  	}
  	dirs +='</ul>';
  	files +='</ul>';
  	document.getElementById("fileslist").innerHTML += dirs + files;
  	alert ("done parsing");
    }
  }
  

• I created two strings (your book has one): one for directory names and the other for file names

• The File API's root method has a getFile method with 4 arguments
  file name
  an object with 2 boolean flags: create and exclusive which can be set using this syntax
  {create: true, exclusive:false}
  success handler
  error handler
• Creating separate short functions for success and failure is tedious
• You can place the function code directly into the argument location. It doesn't look pretty, but it works.

  function onFSsuccess(FS){
     myRoot=FS.root;  
     myRoot.getFile('sample.txt', {create: true, exclusive:false}, function(fileEntry) {setUP(fileEntry, null, true);}, onCreateErr);
     alert ("Success for FS"); 
  }
  

• the 3rd argument above has an inline function. Note that the function is NOT named
• We could rewrite the code as:

  myRoot.getFile('sample.txt', {create: true, exclusive:false}, onGetSuccess , onCreateErr);
  function onGetSuccess (fileEntry) {
    setUP(fileEntry, null, true);
  }
  

• FileWriter object
  • createWriter method creates a writer object so that we can write data
  • write method of the writer object actually writes to the file
  • Events (see page 85 of your book):
    • onwritestart - called when FileWriter starts writing to the file
    • onwrite - called when FileWriter successfully completes write operation
    • Onabort - called when write interrupted
    • Onerror - called when write failes
• Yes, there is a lot of setup to read and write to the file system. Remember that the "root" is actually not the root of the file system, but the root of the sandbox.
• FileReader object
  Properties include: onload, onloadstart, onloadend
  Can read data as: URL (returns as base64 encode), text (UTF-8), binary, and array buffer (ArrayBuffer object returned)
• Setting create to true indicates we intend to write to the file
• the writeFile method prepares the file for writing

1. Create a new PhoneGap project
2. Get rid of the extra "stuff" but make sure the cordova.js is still included
3. Create 2 buttons

   <button type="button" onclick="writeIT()">write hello</button>
   <button type="button" onclick="readIT()">Read file</button>
    

4. Add the following inside script tags:

    document.addEventListener('deviceready', onDeviceReady, false);
   function onDeviceReady(){
     var size =0;
     window.requestFileSystem(LocalFileSystem.PERSISTENT, size, onFSsuccess, onFSerror);
   }
   function onFSsuccess(FS){
      myRoot=FS.root;
      myRoot.getFile('sample.txt', {create: true, exclusive:false}, function(fileEntry) {setUP(fileEntry, null, true);}, onCreateErr);
      alert ("Success for FS"); 
   }
   function getItReady(file)
   {
      writeFile(file, null);
   }
   function readIT() {
   //notice the ugly code for the file method. It can be beautified
      myFile.file(function (file) {
         var reader = new FileReader();
         reader.onloadend = function() {
             document.getElementById("filedata").innerHTML = this.result;
         };
         reader.readAsText(file);
       }, onReadErr);
   }
   function setUP(fileEntry, x, isAppend){
   	//setUP the file pointer for later use
       myFile=fileEntry;
   	  
   }
   function onFSerror(err){
   	alert ("FS Error " + err);
   }
   /*function parseData (entries) { //for finding a file in the dir
   		
   		  exists =-1;
   		  for (var i=0, len=entries.length; i< len; i++) {
   			if (entries[i].isFile && "sample.txt".test(entries[i].name)) {
   				exists=i;
   				break;
   			}
   		  }
   		  if (exists == -1) {
   		   alert ("The file isn't created yet");
   		   return;
   		  }
   		  else 
   		   myFile=entries[exists];
   		 
   		 alert ("Myfile is setup for use");
   }*/
   function onReadErr (err){
      alert ("Read Error " + err);
   }
   function onWriteErr (err){
      alert ("Write Error " + err);
   }
   function onCreateErr (err){
      alert ("Create Error " + err);
   }
   function writeIT() {
     //getfile already called and set up myFile
     myFile.createWriter(onGetWriter, onWriteErr);
   }
   function onGetWriter(myWriter) {
      //myWriter=writer;
      str="ta-da,3\n;ta-da,4";
      myWriter.seek(myWriter.length);
      myWriter.write(str);
   }
   

• Now, try the code on page 90 and 91 of your text
• Notice the similarity to what we have already done.
• This ugliness:
  (entry.isFile && (/\.(gif|jpg|jpeg|png)$/i).test(entry.name))
• checks to see if the entry is a file and tests the name of the entry against a regular expression. If you have had cpsc207, you should be able to figure it out. The pattern is enclosed in slashes; the backslash says that the period is to be handled as the character period instead of its special meaning; the vertical bars are ORs and the dollar sign means the string ending.
• Thus, any file name that has the extension of gif OR jpg OR jpeg or png