Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-file/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-file/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-file/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-file/index.html Mon May 16 21:17:45 2016 @@ -2690,7 +2690,7 @@ The HTML5 File API <a href="http://www.w3.org/TR/FileAPI/";>http://www.w3.org/TR/FileAPI/</a></p> -<p>The (now-defunct) Directories and System extensions +<p>The Directories and System extensions Latest: <a href="http://www.w3.org/TR/2012/WD-file-system-api-20120417/";>http://www.w3.org/TR/2012/WD-file-system-api-20120417/</a> Although most of the plugin code was written when an earlier spec was current: @@ -2699,10 +2699,14 @@ Although most of the plugin code was wri <p>It also implements the FileWriter spec : <a href="http://dev.w3.org/2009/dap/file-system/file-writer.html";>http://dev.w3.org/2009/dap/file-system/file-writer.html</a></p> -<p>For usage, please refer to HTML5 Rocks' excellent <a href="http://www.html5rocks.com/en/tutorials/file/filesystem/";>FileSystem article.</a></p> +<blockquote> +<p><em>Note</em> While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed in the <em>Supported Platforms</em> list, with the exception of the Browser platform.</p> +</blockquote> + +<p>To get a few ideas how to use the plugin, check out the <a href="#sample">sample</a> at the bottom of this page. For additional examples (browser focused), see the HTML5 Rocks' <a href="http://www.html5rocks.com/en/tutorials/file/filesystem/";>FileSystem article.</a></p> <p>For an overview of other storage options, refer to Cordova's -<a href="http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html";>storage guide</a>.</p> +<a href="http://cordova.apache.org/docs/en/latest/cordova/storage/storage.html";>storage guide</a>.</p> <p>This plugin defines global <code>cordova.file</code> object.</p> @@ -3267,6 +3271,14 @@ persistent filesystem, then the <code>In adding <code>src/android/build-extras.gradle</code> to the root of your android project (also requires cordova-android@4.0.0 or greater).</p> +<h3>Permisson to write to external storage when it's not mounted on Marshmallow</h3> + +<p>Marshmallow requires the apps to ask for permissions when reading/writing to external locations. By +<a href="http://developer.android.com/guide/topics/data/data-storage.html#filesExternal";>default</a>, your app has permission to write to +<code>cordova.file.applicationStorageDirectory</code> and <code>cordova.file.externalApplicationStorageDirectory</code>, and the plugin doesn't request permission +for these two directories unless external storage is not mounted. However due to a limitation, when external storage is not mounted, it would ask for +permission to write to <code>cordova.file.externalApplicationStorageDirectory</code>.</p> + <h2>iOS Quirks</h2> <ul> @@ -3589,6 +3601,277 @@ filesystems to be installed. By default, <p>By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, <code>library-nosync</code> and <code>documents-nosync</code>, which represent a special non-synced directory within the <code>/Library</code> or <code>/Documents</code> filesystem.</p> +<h2>Sample: Create Files and Directories, Write, Read, and Append files <a name="sample"></a></h2> + +<p>The File plugin allows you to do things like store files in a temporary or persistent storage location for your app (sandboxed storage) and to store files in other platform-dependent locations. The code snippets in this section demonstrate different tasks including:</p> + +<ul> +<li><a href="#persistent">Accessing the file system</a></li> +<li>Using cross-platform Cordova file URLs to <a href="#appendFile">store your files</a> (see <em>Where to Store Files</em> for more info)</li> +<li>Creating <a href="#persistent">files</a> and <a href="#createDir">directories</a></li> +<li><a href="#writeFile">Writing to files</a></li> +<li><a href="#readFile">Reading files</a></li> +<li><a href="#appendFile">Appending files</a></li> +<li><a href="#displayImage">Display an image file</a></li> +</ul> + +<h2>Create a persistent file <a name="persistent"></a></h2> + +<p>Before you use the File plugin APIs, you can get access to the file system using <code>requestFileSystem</code>. When you do this, you can request either persistent or temporary storage. Persistent storage will not be removed unless permission is granted by the user.</p> + +<p>When you get file system access using <code>requestFileSystem</code>, access is granted for the sandboxed file system only (the sandbox limits access to the app itself), not for general access to any file system location on the device. (To access file system locations outside the sandboxed storage, use other methods such as window.requestLocalFileSystemURL, which support platform-specific locations. For one example of this, see <em>Append a File</em>.)</p> + +<p>Here is a request for persistent storage.</p> + +<blockquote> +<p><em>Note</em> When targeting WebView clients (instead of a browser) or native apps (Windows), you dont need to use <code>requestQuota</code> before using persistent storage.</p> +</blockquote> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nb">window</span><span class="p">.</span><span class="nx">requestFileSystem</span><span class="p">(</span><span class="nx">LocalFileSystem</span><span class="p">.</span><span class="nx">PERSISTENT</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fs</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'file system open: '</span> <span class="o">+</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span> + <span class="nx">fs</span><span class="p">.</span><span class="nx">root</span><span class="p">.</span><span class="nx">getFile</span><span class="p">(</span><span class="s2">"newPersistentFile.txt"</span><span class="p">,</span> <span class="p">{</span> <span class="na">create</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">exclusive</span><span class="p">:</span> <span class="kc">false</span> <span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"fileEntry is file?"</span> <span class="o">+</span> <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">isFile</span><span class="p">.</span><span class="nx">toString</span><span class="p">());</span> + <span class="c1">// fileEntry.name == 'someFile.txt'</span> + <span class="c1">// fileEntry.fullPath == '/someFile.txt'</span> + <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="kc">null</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorCreateFile</span><span class="p">);</span> + +<span class="p">},</span> <span class="nx">onErrorLoadFs</span><span class="p">);</span> +</code></pre></div> +<p>The success callback receives FileSystem object (fs). Use <code>fs.root</code> to return a DirectoryEntry object, which you can use to create or get a file (by calling <code>getFile</code>). In this example, <code>fs.root</code> is a DirectoryEntry object that represents the persistent storage in the sandboxed file system.</p> + +<p>The success callback for <code>getFile</code> receives a FileEntry object. You can use this to perform file write and file read operations.</p> + +<h2>Create a temporary file</h2> + +<p>Here is an example of a request for temporary storage. Temporary storage may be deleted by the operating system if the device runs low on memory.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nb">window</span><span class="p">.</span><span class="nx">requestFileSystem</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">TEMPORARY</span><span class="p">,</span> <span class="mi">5</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fs</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'file system open: '</span> <span class="o">+</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span> + <span class="nx">createFile</span><span class="p">(</span><span class="nx">fs</span><span class="p">.</span><span class="nx">root</span><span class="p">,</span> <span class="s2">"newTempFile.txt"</span><span class="p">,</span> <span class="kc">false</span><span class="p">);</span> + +<span class="p">},</span> <span class="nx">onErrorLoadFs</span><span class="p">);</span> +</code></pre></div> +<p>When you are using temporary storage, you can create or get the file by calling <code>getFile</code>. As in the persistent storage example, this will give you a FileEntry object that you can use for read or write operations.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">createFile</span><span class="p">(</span><span class="nx">dirEntry</span><span class="p">,</span> <span class="nx">fileName</span><span class="p">,</span> <span class="nx">isAppend</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Creates a new file or returns the file if it already exists.</span> + <span class="nx">dirEntry</span><span class="p">.</span><span class="nx">getFile</span><span class="p">(</span><span class="nx">fileName</span><span class="p">,</span> <span class="p">{</span><span class="na">create</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">exclusive</span><span class="p">:</span> <span class="kc">false</span><span class="p">},</span> <span class="kd">function</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="nx">isAppend</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorCreateFile</span><span class="p">);</span> + +<span class="p">}</span> +</code></pre></div> +<h2>Write to a file <a name="writeFile"></a></h2> + +<p>Once you have a FileEntry object, you can write to the file by calling <code>createWriter</code>, which returns a FileWriter object in the success callback. Call the <code>write</code> method of FileWriter to write to the file.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="nx">dataObj</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Create a FileWriter object for our FileEntry (log.txt).</span> + <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">createWriter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">fileWriter</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onwriteend</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file read..."</span><span class="p">);</span> + <span class="nx">readFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">);</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Failed file read: "</span> <span class="o">+</span> <span class="nx">e</span><span class="p">.</span><span class="nx">toString</span><span class="p">());</span> + <span class="p">};</span> + + <span class="c1">// If data object is not passed in,</span> + <span class="c1">// create a new Blob instead.</span> + <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">dataObj</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">dataObj</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Blob</span><span class="p">([</span><span class="s1">'some file data'</span><span class="p">],</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="s1">'text/plain'</span> <span class="p">});</span> + <span class="p">}</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="nx">dataObj</span><span class="p">);</span> + <span class="p">});</span> +<span class="p">}</span> +</code></pre></div> +<h2>Read a file <a name="readFile"></a></h2> + +<p>You also need a FileEntry object to read an existing file. Use the file property of FileEntry to get the file reference, and then create a new FileReader object. You can use methods like <code>readAsText</code> to start the read operation. When the read operation is complete, <code>this.result</code> stores the result of the read operation.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">readFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">file</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">file</span><span class="p">)</span> <span class="p">{</span> + <span class="kd">var</span> <span class="nx">reader</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">FileReader</span><span class="p">();</span> + + <span class="nx">reader</span><span class="p">.</span><span class="nx">onloadend</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file read: "</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">result</span><span class="p">);</span> + <span class="nx">displayFileData</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">.</span><span class="nx">fullPath</span> <span class="o">+</span> <span class="s2">": "</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">result</span><span class="p">);</span> + <span class="p">};</span> + + <span class="nx">reader</span><span class="p">.</span><span class="nx">readAsText</span><span class="p">(</span><span class="nx">file</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorReadFile</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<h2>Append a file using alternative methods <a name="appendFile"></a></h2> + +<p>Of course, you will often want to append existing files instead of creating new ones. Here is an example of that. This example shows another way that you can access the file system using window.resolveLocalFileSystemURL. In this example, pass the cross-platform Cordova file URL, cordova.file.dataDirectory, to the function. The success callback receives a DirectoryEntry object, which you can use to do things like create a file.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nb">window</span><span class="p">.</span><span class="nx">resolveLocalFileSystemURL</span><span class="p">(</span><span class="nx">cordova</span><span class="p">.</span><span class="nx">file</span><span class="p">.</span><span class="nx">dataDirectory</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">dirEntry</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'file system open: '</span> <span class="o">+</span> <span class="nx">dirEntry</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span> + <span class="kd">var</span> <span class="nx">isAppend</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span> + <span class="nx">createFile</span><span class="p">(</span><span class="nx">dirEntry</span><span class="p">,</span> <span class="s2">"fileToAppend.txt"</span><span class="p">,</span> <span class="nx">isAppend</span><span class="p">);</span> +<span class="p">},</span> <span class="nx">onErrorLoadFs</span><span class="p">);</span> +</code></pre></div> +<p>In addition to this usage, you can use <code>resolveLocalFileSystemURL</code> to get access to some file system locations that are not part of the sandboxed storage system. See <em>Where to store Files</em> for more information; many of these storage locations are platform-specific. You can also pass cross-platform file system locations to <code>resolveLocalFileSystemURL</code> using the <em>cdvfile protocol</em>.</p> + +<p>For the append operation, there is nothing new in the <code>createFile</code> function that is called in the preceding code (see the preceding examples for the actual code). <code>createFile</code> calls <code>writeFile</code>. In <code>writeFile</code>, you check whether an append operation is requested.</p> + +<p>Once you have a FileWriter object, call the <code>seek</code> method, and pass in the index value for the position where you want to write. In this example, you also test whether the file exists. After calling seek, then call the write method of FileWriter.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="nx">dataObj</span><span class="p">,</span> <span class="nx">isAppend</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Create a FileWriter object for our FileEntry (log.txt).</span> + <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">createWriter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">fileWriter</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onwriteend</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file read..."</span><span class="p">);</span> + <span class="nx">readFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">);</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Failed file read: "</span> <span class="o">+</span> <span class="nx">e</span><span class="p">.</span><span class="nx">toString</span><span class="p">());</span> + <span class="p">};</span> + + <span class="c1">// If we are appending data to file, go to the end of the file.</span> + <span class="k">if</span> <span class="p">(</span><span class="nx">isAppend</span><span class="p">)</span> <span class="p">{</span> + <span class="k">try</span> <span class="p">{</span> + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">seek</span><span class="p">(</span><span class="nx">fileWriter</span><span class="p">.</span><span class="nx">length</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">catch</span> <span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"file doesn't exist!"</span><span class="p">);</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="nx">dataObj</span><span class="p">);</span> + <span class="p">});</span> +<span class="p">}</span> +</code></pre></div> +<h2>Store an existing binary file <a name="binaryFile"></a></h2> + +<p>We already showed how to write to a file that you just created in the sandboxed file system. What if you need to get access to an existing file and convert that to something you can store on your device? In this example, you obtain a file using an xhr request, and then save it to the cache in the sandboxed file system.</p> + +<p>Before you get the file, get a FileSystem reference using <code>requestFileSystem</code>. By passing window.TEMPORARY in the method call (same as before), the returned FileSystem object (fs) represents the cache in the sandboxed file system. Use <code>fs.root</code> to get the DirectoryEntry object that you need.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nb">window</span><span class="p">.</span><span class="nx">requestFileSystem</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">TEMPORARY</span><span class="p">,</span> <span class="mi">5</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fs</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'file system open: '</span> <span class="o">+</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span> + <span class="nx">getSampleFile</span><span class="p">(</span><span class="nx">fs</span><span class="p">.</span><span class="nx">root</span><span class="p">);</span> + +<span class="p">},</span> <span class="nx">onErrorLoadFs</span><span class="p">);</span> +</code></pre></div> +<p>For completeness, here is the xhr request to get a Blob image. There is nothing Cordova-specific in this code, except that you forward the DirectoryEntry reference that you already obtained as an argument to the saveFile function. You will save the blob image and display it later after reading the file (to validate the operation).</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">getSampleFile</span><span class="p">(</span><span class="nx">dirEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="kd">var</span> <span class="nx">xhr</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">XMLHttpRequest</span><span class="p">();</span> + <span class="nx">xhr</span><span class="p">.</span><span class="nx">open</span><span class="p">(</span><span class="s1">'GET'</span><span class="p">,</span> <span class="s1">'http://cordova.apache.org/static/img/cordova_bot.png'</span><span class="p">,</span> <span class="kc">true</span><span class="p">);</span> + <span class="nx">xhr</span><span class="p">.</span><span class="nx">responseType</span> <span class="o">=</span> <span class="s1">'blob'</span><span class="p">;</span> + + <span class="nx">xhr</span><span class="p">.</span><span class="nx">onload</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + <span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">status</span> <span class="o">==</span> <span class="mi">200</span><span class="p">)</span> <span class="p">{</span> + + <span class="kd">var</span> <span class="nx">blob</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Blob</span><span class="p">([</span><span class="k">this</span><span class="p">.</span><span class="nx">response</span><span class="p">],</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="s1">'image/png'</span> <span class="p">});</span> + <span class="nx">saveFile</span><span class="p">(</span><span class="nx">dirEntry</span><span class="p">,</span> <span class="nx">blob</span><span class="p">,</span> <span class="s2">"downloadedImage.png"</span><span class="p">);</span> + <span class="p">}</span> + <span class="p">};</span> + <span class="nx">xhr</span><span class="p">.</span><span class="nx">send</span><span class="p">();</span> +<span class="p">}</span> +</code></pre></div> +<blockquote> +<p><em>Note</em> For Cordova 5 security, the preceding code requires that you add the domain name, http://cordova.apache.org, to the Content-Security-Policy <meta> element in index.html.</p> +</blockquote> + +<p>After getting the file, copy the contents to a new file. The current DirectoryEntry object is already associated with the app cache.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">saveFile</span><span class="p">(</span><span class="nx">dirEntry</span><span class="p">,</span> <span class="nx">fileData</span><span class="p">,</span> <span class="nx">fileName</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">dirEntry</span><span class="p">.</span><span class="nx">getFile</span><span class="p">(</span><span class="nx">fileName</span><span class="p">,</span> <span class="p">{</span> <span class="na">create</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">exclusive</span><span class="p">:</span> <span class="kc">false</span> <span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="nx">fileData</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorCreateFile</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<p>In writeFile, you pass in the Blob object as the dataObj and you will save that in the new file.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">writeFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">,</span> <span class="nx">dataObj</span><span class="p">,</span> <span class="nx">isAppend</span><span class="p">)</span> <span class="p">{</span> + + <span class="c1">// Create a FileWriter object for our FileEntry (log.txt).</span> + <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">createWriter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">fileWriter</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onwriteend</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file write..."</span><span class="p">);</span> + <span class="k">if</span> <span class="p">(</span><span class="nx">dataObj</span><span class="p">.</span><span class="nx">type</span> <span class="o">==</span> <span class="s2">"image/png"</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">readBinaryFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">else</span> <span class="p">{</span> + <span class="nx">readFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">);</span> + <span class="p">}</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Failed file write: "</span> <span class="o">+</span> <span class="nx">e</span><span class="p">.</span><span class="nx">toString</span><span class="p">());</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="nx">dataObj</span><span class="p">);</span> + <span class="p">});</span> +<span class="p">}</span> +</code></pre></div> +<p>After writing to the file, read it and display it. You saved the image as binary data, so you can read it using FileReader.readAsArrayBuffer.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">readBinaryFile</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">file</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">file</span><span class="p">)</span> <span class="p">{</span> + <span class="kd">var</span> <span class="nx">reader</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">FileReader</span><span class="p">();</span> + + <span class="nx">reader</span><span class="p">.</span><span class="nx">onloadend</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file write: "</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">result</span><span class="p">);</span> + <span class="nx">displayFileData</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">.</span><span class="nx">fullPath</span> <span class="o">+</span> <span class="s2">": "</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">result</span><span class="p">);</span> + + <span class="kd">var</span> <span class="nx">blob</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Blob</span><span class="p">([</span><span class="k">new</span> <span class="nx">Uint8Array</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">result</span><span class="p">)],</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="s2">"image/png"</span> <span class="p">});</span> + <span class="nx">displayImage</span><span class="p">(</span><span class="nx">blob</span><span class="p">);</span> + <span class="p">};</span> + + <span class="nx">reader</span><span class="p">.</span><span class="nx">readAsArrayBuffer</span><span class="p">(</span><span class="nx">file</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorReadFile</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<p>After reading the data, you can display the image using code like this. Use window.URL.createObjectURL to get a DOM string for the Blob image.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">displayImage</span><span class="p">(</span><span class="nx">blob</span><span class="p">)</span> <span class="p">{</span> + + <span class="c1">// Displays image if result is a valid DOM string for an image.</span> + <span class="kd">var</span> <span class="nx">elem</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'imageFile'</span><span class="p">);</span> + <span class="c1">// Note: Use window.URL.revokeObjectURL when finished with image.</span> + <span class="nx">elem</span><span class="p">.</span><span class="nx">src</span> <span class="o">=</span> <span class="nb">window</span><span class="p">.</span><span class="nx">URL</span><span class="p">.</span><span class="nx">createObjectURL</span><span class="p">(</span><span class="nx">blob</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<h2>Display an image file <a name="displayImage"></a></h2> + +<p>To display an image using a FileEntry, you can call the <code>toURL</code> method.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">displayImageByFileURL</span><span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + <span class="kd">var</span> <span class="nx">elem</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'imageFile'</span><span class="p">);</span> + <span class="nx">elem</span><span class="p">.</span><span class="nx">src</span> <span class="o">=</span> <span class="nx">fileEntry</span><span class="p">.</span><span class="nx">toURL</span><span class="p">();</span> +<span class="p">}</span> +</code></pre></div> +<p>If you are using some platform-specific URIs instead of a FileEntry and you want to display an image, you may need to include the main part of the URI in the Content-Security-Policy <meta> element in index.html. For example, on Windows 10, you can include <code>ms-appdata:</code> in your <meta> element. Here is an example.</p> +<div class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt"><meta</span> <span class="na">http-equiv=</span><span class="s">"Content-Security-Policy"</span> <span class="na">content=</span><span class="s">"default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"</span><span class="nt">></span> +</code></pre></div> +<h2>Create Directories <a name="createDir"></a> +<p>In the code here, you create directories in the root of the app storage location. You could use this code with any writable storage location (that is, any DirectoryEntry). Here, you write to the application cache (assuming that you used window.TEMPORARY to get your FileSystem object) by passing fs.root into this function.</p> + +<p>This code creates the /NewDirInRoot/images folder in the application cache. For platform-specific values, look at <em>File System Layouts</em>.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">createDirectory</span><span class="p">(</span><span class="nx">rootDirEntry</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">rootDirEntry</span><span class="p">.</span><span class="nx">getDirectory</span><span class="p">(</span><span class="s1">'NewDirInRoot'</span><span class="p">,</span> <span class="p">{</span> <span class="na">create</span><span class="p">:</span> <span class="kc">true</span> <span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">dirEntry</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">dirEntry</span><span class="p">.</span><span class="nx">getDirectory</span><span class="p">(</span><span class="s1">'images'</span><span class="p">,</span> <span class="p">{</span> <span class="na">create</span><span class="p">:</span> <span class="kc">true</span> <span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">subDirEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">createFile</span><span class="p">(</span><span class="nx">subDirEntry</span><span class="p">,</span> <span class="s2">"fileInNewSubDir.txt"</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorGetDir</span><span class="p">);</span> + <span class="p">},</span> <span class="nx">onErrorGetDir</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<p>When creating subfolders, you need to create each folder separately as shown in the preceding code.</p> + </div> </div>
Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-geolocation/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-geolocation/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-geolocation/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-geolocation/index.html Mon May 16 21:17:45 2016 @@ -2685,12 +2685,18 @@ <h1>cordova-plugin-geolocation</h1> <p>This plugin provides information about the device's location, such as -latitude and longitude. Common sources of location information include +latitude and longitude.</p> + +<p>Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs. There is no guarantee that the API returns the device's actual location.</p> +<blockquote> +<p>To get a few ideas, check out the <a href="#sample">sample</a> at the bottom of this page or go straight to the <a href="#reference">reference</a> content.</p> +</blockquote> + <p>This API is based on the <a href="http://dev.w3.org/geo/api/spec-source.html";>W3C Geolocation API Specification</a>, and only executes on devices that don't already provide an implementation.</p> @@ -2722,6 +2728,8 @@ are not available until after the <code> <span class="p">}</span> </code></pre></div> +<h2><a id="reference"></a>Reference</h2> + <h2>Installation</h2> <p>This requires cordova 5.0+ ( current stable 1.0.0 )</p> Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-inappbrowser/index.html Mon May 16 21:17:45 2016 @@ -2884,6 +2884,76 @@ opened with <code>target='_blank' <li><p><strong>callback</strong>: the function that executes when the event fires. The function is passed an <code>InAppBrowserEvent</code> object as a parameter.</p></li> </ul> +<h2>Example</h2> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="kd">var</span> <span class="nx">inAppBrowserRef</span> <span class="o">=</span> <span class="kc">undefined</span><span class="p">;</span> + +<span class="kd">function</span> <span class="nx">showHelp</span><span class="p">(</span><span class="nx">url</span><span class="p">)</span> <span class="p">{</span> + + <span class="kd">var</span> <span class="nx">target</span> <span class="o">=</span> <span class="s2">"_blank"</span><span class="p">;</span> + + <span class="kd">var</span> <span class="nx">options</span> <span class="o">=</span> <span class="s2">"location=yes,hidden=yes"</span><span class="p">;</span> + + <span class="nx">inAppBrowserRef</span> <span class="o">=</span> <span class="nx">cordova</span><span class="p">.</span><span class="nx">InAppBrowser</span><span class="p">.</span><span class="nx">open</span><span class="p">(</span><span class="nx">url</span><span class="p">,</span> <span class="nx">target</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span> + + <span class="kd">with</span> <span class="p">(</span><span class="nx">inAppBrowserRef</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loadstart'</span><span class="p">,</span> <span class="nx">loadStartCallBack</span><span class="p">);</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loadstop'</span><span class="p">,</span> <span class="nx">loadStopCallBack</span><span class="p">);</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loaderror'</span><span class="p">,</span> <span class="nx">loadErrorCallBack</span><span class="p">);</span> + <span class="p">}</span> + +<span class="p">}</span> + +<span class="kd">function</span> <span class="nx">loadStartCallBack</span><span class="p">()</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">"loading please wait ..."</span><span class="p">);</span> + +<span class="p">}</span> + +<span class="kd">function</span> <span class="nx">loadStopCallBack</span><span class="p">()</span> <span class="p">{</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">inAppBrowserRef</span> <span class="o">!=</span> <span class="kc">undefined</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">insertCSS</span><span class="p">({</span> <span class="na">code</span><span class="p">:</span> <span class="s2">"body{font-size: 25px;"</span> <span class="p">});</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">""</span><span class="p">);</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">show</span><span class="p">();</span> + <span class="p">}</span> + +<span class="p">}</span> + +<span class="kd">function</span> <span class="nx">loadErrorCallBack</span><span class="p">(</span><span class="nx">params</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">""</span><span class="p">);</span> + + <span class="kd">var</span> <span class="nx">scriptErrorMesssage</span> <span class="o">=</span> + <span class="s2">"alert('Sorry we cannot open that page. Message from the server is : "</span> + <span class="o">+</span> <span class="nx">params</span><span class="p">.</span><span class="nx">message</span> <span class="o">+</span> <span class="s2">"');"</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">executeScript</span><span class="p">({</span> <span class="na">code</span><span class="p">:</span> <span class="nx">scriptErrorMesssage</span> <span class="p">},</span> <span class="nx">executeScriptCallBack</span><span class="p">);</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">close</span><span class="p">();</span> + + <span class="nx">inAppBrowserRef</span> <span class="o">=</span> <span class="kc">undefined</span><span class="p">;</span> + +<span class="p">}</span> + +<span class="kd">function</span> <span class="nx">executeScriptCallBack</span><span class="p">(</span><span class="nx">params</span><span class="p">)</span> <span class="p">{</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">params</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span> + <span class="s2">"Sorry we couldn't open that page. Message from the server is : '"</span> + <span class="o">+</span> <span class="nx">params</span><span class="p">.</span><span class="nx">message</span> <span class="o">+</span> <span class="s2">"'"</span><span class="p">);</span> + <span class="p">}</span> + +<span class="p">}</span> + +</code></pre></div> <h3>InAppBrowserEvent Properties</h3> <ul> @@ -3088,6 +3158,150 @@ ref.addEventListener('loadstop', functio ref.insertCSS({file: "mystyles.css"}); }); </code></pre></div> +<p>__</p> + +<h2><a id="sample"></a>Sample: Show help pages with an InAppBrowser</h2> + +<p>You can use this plugin to show helpful documentation pages within your app. Users can view online help documents and then close them without leaving the app.</p> + +<p>Here's a few snippets that show how you do this.</p> + +<ul> +<li><a href="#give">Give users a way to ask for help</a>.</li> +<li><a href="#load">Load a help page</a>.</li> +<li><a href="#let">Let users know that you're getting their page ready</a>.</li> +<li><a href="#show">Show the help page</a>.</li> +<li><a href="#handle">Handle page errors</a>.</li> +</ul> + +<h3><a id="give"></a>Give users a way to ask for help</h3> + +<p>There's lots of ways to do this in your app. A drop down list is a simple way to do that.</p> +<div class="highlight"><pre><code class="language-html" data-lang="html"> +<span class="nt"><select</span> <span class="na">id=</span><span class="s">"help-select"</span><span class="nt">></span> + <span class="nt"><option</span> <span class="na">value=</span><span class="s">"default"</span><span class="nt">></span>Need help?<span class="nt"></option></span> + <span class="nt"><option</span> <span class="na">value=</span><span class="s">"article"</span><span class="nt">></span>Show me a helpful article<span class="nt"></option></span> + <span class="nt"><option</span> <span class="na">value=</span><span class="s">"video"</span><span class="nt">></span>Show me a helpful video<span class="nt"></option></span> + <span class="nt"><option</span> <span class="na">value=</span><span class="s">"search"</span><span class="nt">></span>Search for other topics<span class="nt"></option></span> +<span class="nt"></select></span> + +</code></pre></div> +<p>Gather the users choice in the <code>onDeviceReady</code> function of the page and then send an appropriate URL to a helper function in some shared library file. Our helper function is named <code>showHelp()</code> and we'll write that function next.</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="nx">$</span><span class="p">(</span><span class="s1">'#help-select'</span><span class="p">).</span><span class="nx">on</span><span class="p">(</span><span class="s1">'change'</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + + <span class="kd">var</span> <span class="nx">url</span><span class="p">;</span> + + <span class="k">switch</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">value</span><span class="p">)</span> <span class="p">{</span> + + <span class="k">case</span> <span class="s2">"article"</span><span class="err">:</span> + <span class="nx">url</span> <span class="o">=</span> <span class="s2">"https://cordova.apache.org/docs/en/latest/";</span> + <span class="o">+</span> <span class="s2">"reference/cordova-plugin-inappbrowser/index.html"</span><span class="p">;</span> + <span class="k">break</span><span class="p">;</span> + + <span class="k">case</span> <span class="s2">"video"</span><span class="err">:</span> + <span class="nx">url</span> <span class="o">=</span> <span class="s2">"https://youtu.be/F-GlVrTaeH0";</span><span class="p">;</span> + <span class="k">break</span><span class="p">;</span> + + <span class="k">case</span> <span class="s2">"search"</span><span class="err">:</span> + <span class="nx">url</span> <span class="o">=</span> <span class="s2">"https://www.google.com/#q=inAppBrowser+plugin";</span><span class="p">;</span> + <span class="k">break</span><span class="p">;</span> + <span class="p">}</span> + + <span class="nx">showHelp</span><span class="p">(</span><span class="nx">url</span><span class="p">);</span> + +<span class="p">});</span> + +</code></pre></div> +<h3><a id="load"></a>Load a help page</h3> + +<p>We'll use the <code>open</code> function to load the help page. We're setting the <code>hidden</code> property to <code>yes</code> so that we can show the browser only after the page content has loaded. That way, users don't see a blank browser while they wait for content to appear. When the <code>loadstop</code> event is raised, we'll know when the content has loaded. We'll handle that event shortly.</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="kd">function</span> <span class="nx">showHelp</span><span class="p">(</span><span class="nx">url</span><span class="p">)</span> <span class="p">{</span> + + <span class="kd">var</span> <span class="nx">target</span> <span class="o">=</span> <span class="s2">"_blank"</span><span class="p">;</span> + + <span class="kd">var</span> <span class="nx">options</span> <span class="o">=</span> <span class="s2">"location=yes,hidden=yes"</span><span class="p">;</span> + + <span class="nx">inAppBrowserRef</span> <span class="o">=</span> <span class="nx">cordova</span><span class="p">.</span><span class="nx">InAppBrowser</span><span class="p">.</span><span class="nx">open</span><span class="p">(</span><span class="nx">url</span><span class="p">,</span> <span class="nx">target</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span> + + <span class="kd">with</span> <span class="p">(</span><span class="nx">inAppBrowserRef</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loadstart'</span><span class="p">,</span> <span class="nx">loadStartCallBack</span><span class="p">);</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loadstop'</span><span class="p">,</span> <span class="nx">loadStopCallBack</span><span class="p">);</span> + + <span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'loaderror'</span><span class="p">,</span> <span class="nx">loadErrorCallBack</span><span class="p">);</span> + <span class="p">}</span> + +<span class="p">}</span> + +</code></pre></div> +<h3><a id="let"></a>Let users know that you're getting their page ready</h3> + +<p>Because the browser doesn't immediately appear, we can use the <code>loadstart</code> event to show a status message, progress bar, or other indicator. This assures users that content is on the way.</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="kd">function</span> <span class="nx">loadStartCallBack</span><span class="p">()</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">"loading please wait ..."</span><span class="p">);</span> + +<span class="p">}</span> + +</code></pre></div> +<h3><a id="show"></a>Show the help page</h3> + +<p>When the <code>loadstopcallback</code> event is raised, we know that the content has loaded and we can make the browser visible. This sort of trick can create the impression of better performance. The truth is that whether you show the browser before content loads or not, the load times are exactly the same.</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="kd">function</span> <span class="nx">loadStopCallBack</span><span class="p">()</span> <span class="p">{</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">inAppBrowserRef</span> <span class="o">!=</span> <span class="kc">undefined</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">insertCSS</span><span class="p">({</span> <span class="na">code</span><span class="p">:</span> <span class="s2">"body{font-size: 25px;"</span> <span class="p">});</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">""</span><span class="p">);</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">show</span><span class="p">();</span> + <span class="p">}</span> + +<span class="p">}</span> + +</code></pre></div> +<p>You might have noticed the call to the <code>insertCSS</code> function. This serves no particular purpose in our scenario. But it gives you an idea of why you might use it. In this case, we're just making sure that the font size of your pages have a certain size. You can use this function to insert any CSS style elements. You can even point to a CSS file in your project.</p> + +<h3><a id="handle"></a>Handle page errors</h3> + +<p>Sometimes a page no longer exists, a script error occurs, or a user lacks permission to view the resource. How or if you handle that situation is completely up to you and your design. You can let the browser show that message or you can present it in another way.</p> + +<p>We'll try to show that error in a message box. We can do that by injecting a script that calls the <code>alert</code> function. That said, this won't work in browsers on Windows devices so we'll have to look at the parameter of the <code>executeScript</code> callback function to see if our attempt worked. If it didn't work out for us, we'll just show the error message in a <code><div></code> on the page.</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"> +<span class="kd">function</span> <span class="nx">loadErrorCallBack</span><span class="p">(</span><span class="nx">params</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span><span class="s2">""</span><span class="p">);</span> + + <span class="kd">var</span> <span class="nx">scriptErrorMesssage</span> <span class="o">=</span> + <span class="s2">"alert('Sorry we cannot open that page. Message from the server is : "</span> + <span class="o">+</span> <span class="nx">params</span><span class="p">.</span><span class="nx">message</span> <span class="o">+</span> <span class="s2">"');"</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">executeScript</span><span class="p">({</span> <span class="na">code</span><span class="p">:</span> <span class="nx">scriptErrorMesssage</span> <span class="p">},</span> <span class="nx">executeScriptCallBack</span><span class="p">);</span> + + <span class="nx">inAppBrowserRef</span><span class="p">.</span><span class="nx">close</span><span class="p">();</span> + + <span class="nx">inAppBrowserRef</span> <span class="o">=</span> <span class="kc">undefined</span><span class="p">;</span> + +<span class="p">}</span> + +<span class="kd">function</span> <span class="nx">executeScriptCallBack</span><span class="p">(</span><span class="nx">params</span><span class="p">)</span> <span class="p">{</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">params</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">$</span><span class="p">(</span><span class="s1">'#status-message'</span><span class="p">).</span><span class="nx">text</span><span class="p">(</span> + <span class="s2">"Sorry we couldn't open that page. Message from the server is : '"</span> + <span class="o">+</span> <span class="nx">params</span><span class="p">.</span><span class="nx">message</span> <span class="o">+</span> <span class="s2">"'"</span><span class="p">);</span> + <span class="p">}</span> + +<span class="p">}</span> + +</code></pre></div> </div> </div> Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-media-capture/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-media-capture/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-media-capture/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-media-capture/index.html Mon May 16 21:17:45 2016 @@ -3331,6 +3331,37 @@ the following default values:</p> <li><p><strong>duration</strong>: Supported: audio and video files only.</p></li> </ul> +<h2>Android Lifecycle Quirks</h2> + +<p>When capturing audio, video, or images on the Android platform, there is a chance that the +application will get destroyed after the Cordova Webview is pushed to the background by +the native capture application. See the <a href="http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#lifecycle-guide";>Android Lifecycle Guide</a> for +a full description of the issue. In this case, the success and failure callbacks passed +to the capture method will not be fired and instead the results of the call will be +delivered via a document event that fires after the Cordova <a href="http://cordova.apache.org/docs/en/latest/cordova/events/events.html#resume";>resume event</a>.</p> + +<p>In your app, you should subscribe to the two possible events like so:</p> +<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kd">function</span> <span class="nx">onDeviceReady</span><span class="p">()</span> <span class="p">{</span> + <span class="c1">// pendingcaptureresult is fired if the capture call is successful</span> + <span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'pendingcaptureresult'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">mediaFiles</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Do something with result</span> + <span class="p">});</span> + + <span class="c1">// pendingcaptureerror is fired if the capture call is unsuccessful</span> + <span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'pendingcaptureerror'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Handle error case</span> + <span class="p">});</span> +<span class="p">}</span> + +<span class="c1">// Only subscribe to events after deviceready fires</span> +<span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">'deviceready'</span><span class="p">,</span> <span class="nx">onDeviceReady</span><span class="p">);</span> +</code></pre></div> +<p>It is up you to track what part of your code these results are coming from. Be sure to +save and restore your app's state as part of the <a href="http://cordova.apache.org/docs/en/latest/cordova/events/events.html#pause";>pause</a> and +<a href="http://cordova.apache.org/docs/en/latest/cordova/events/events.html#resume";>resume</a> events as appropriate. Please note that these events will only +fire on the Android platform and only when the Webview was destroyed during a capture +operation.</p> + </div> </div> Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-media/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-media/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-media/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-media/index.html Mon May 16 21:17:45 2016 @@ -2759,7 +2759,9 @@ function onDeviceReady() { <li><p><code>media.getDuration</code>: Returns the duration of an audio file.</p></li> <li><p><code>media.play</code>: Start or resume playing an audio file.</p></li> <li><p><code>media.pause</code>: Pause playback of an audio file.</p></li> +<li><p><code>media.pauseRecord</code>: Pause recording of an audio file.</p></li> <li><p><code>media.release</code>: Releases the underlying operating system's audio resources.</p></li> +<li><p><code>media.resumeRecord</code>: Resume recording of an audio file.</p></li> <li><p><code>media.seekTo</code>: Moves the position within the audio file.</p></li> <li><p><code>media.setVolume</code>: Set the volume for audio playback.</p></li> <li><p><code>media.startRecord</code>: Start recording an audio file.</p></li> @@ -2903,6 +2905,42 @@ function playAudio(url) { }, 10000); } </code></pre></div> +<h2>media.pauseRecord</h2> + +<p>Pauses recording an audio file.</p> +<div class="highlight"><pre><code class="language-" data-lang="">media.pauseRecord(); +</code></pre></div> +<h3>Supported Platforms</h3> + +<ul> +<li>iOS</li> +</ul> + +<h3>Quick Example</h3> +<div class="highlight"><pre><code class="language-" data-lang="">// Record audio +// +function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + }); + + // Record audio + mediaRec.startRecord(); + + // Pause Recording after 5 seconds + setTimeout(function() { + my_media.pauseRecord(); + }, 5000); +} +</code></pre></div> <h2>media.play</h2> <p>Starts or resumes playing an audio file.</p> @@ -2967,6 +3005,47 @@ my_media.play(); my_media.stop(); my_media.release(); </code></pre></div> +<h2>media.resumeRecord</h2> + +<p>Resume recording an audio file.</p> +<div class="highlight"><pre><code class="language-" data-lang="">media.resumeRecord(); +</code></pre></div> +<h3>Supported Platforms</h3> + +<ul> +<li>iOS</li> +</ul> + +<h3>Quick Example</h3> +<div class="highlight"><pre><code class="language-" data-lang="">// Record audio +// +function recordAudio() { + var src = "myrecording.mp3"; + var mediaRec = new Media(src, + // success callback + function() { + console.log("recordAudio():Audio Success"); + }, + + // error callback + function(err) { + console.log("recordAudio():Audio Error: "+ err.code); + }); + + // Record audio + mediaRec.startRecord(); + + // Pause Recording after 5 seconds + setTimeout(function() { + my_media.pauseRecord(); + }, 5000); + + // Resume Recording after 10 seconds + setTimeout(function() { + my_media.resumeRecord(); + }, 10000); +} +</code></pre></div> <h2>media.seekTo</h2> <p>Sets the current position within an audio file.</p> Modified: cordova/site/public/docs/en/6.x/reference/cordova-plugin-network-information/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/reference/cordova-plugin-network-information/index.html?rev=1744142&r1=1744141&r2=1744142&view=diff ============================================================================== --- cordova/site/public/docs/en/6.x/reference/cordova-plugin-network-information/index.html (original) +++ cordova/site/public/docs/en/6.x/reference/cordova-plugin-network-information/index.html Mon May 16 21:17:45 2016 @@ -2689,8 +2689,14 @@ It provides information about the device's cellular and wifi connection, and whether the device has an internet connection.</p> +<blockquote> +<p>To get a few ideas how to use the plugin, check out the <a href="#sample">sample</a> at the bottom of this page or go straight to the <a href="#reference">reference</a> content.</p> +</blockquote> + <p>Report issues with this plugin on the <a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Network%20Information%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC";>Apache Cordova issue tracker</a>.</p> +<h2><a name="reference"></a>Reference</h2> + <h2>Installation</h2> <div class="highlight"><pre><code class="language-" data-lang="">cordova plugin add cordova-plugin-network-information </code></pre></div> @@ -2894,6 +2900,110 @@ at least a second to fire, prior to whic <p>The Emulator reports the connection type as <code>Cellular</code>, which does not change, so events does <em>not</em> fire.</p> +<h2>Sample: Upload a File Depending on your Network State <a name="sample"></a></h2> + +<p>The code examples in this section show examples of changing app behavior using the online and offline events and your network connection status.</p> + +<p>To start with, create a new FileEntry object (data.txt) to use for sample data. Call this function from the <code>deviceready</code> handler.</p> + +<blockquote> +<p><em>Note</em> This code example requires the File plugin.</p> +</blockquote> +<div class="highlight"><pre><code class="language-js" data-lang="js"> +<span class="kd">var</span> <span class="nx">dataFileEntry</span><span class="p">;</span> + +<span class="kd">function</span> <span class="nx">createSomeData</span><span class="p">()</span> <span class="p">{</span> + + <span class="nb">window</span><span class="p">.</span><span class="nx">requestFileSystem</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">TEMPORARY</span><span class="p">,</span> <span class="mi">5</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">,</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fs</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'file system open: '</span> <span class="o">+</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span> + <span class="c1">// Creates a new file or returns an existing file.</span> + <span class="nx">fs</span><span class="p">.</span><span class="nx">root</span><span class="p">.</span><span class="nx">getFile</span><span class="p">(</span><span class="s2">"data.txt"</span><span class="p">,</span> <span class="p">{</span> <span class="na">create</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">exclusive</span><span class="p">:</span> <span class="kc">false</span> <span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">fileEntry</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">dataFileEntry</span> <span class="o">=</span> <span class="nx">fileEntry</span><span class="p">;</span> + + <span class="p">},</span> <span class="nx">onErrorCreateFile</span><span class="p">);</span> + + <span class="p">},</span> <span class="nx">onErrorLoadFs</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<p>Next, add listeners for the online and offline events in the <code>deviceready</code> handler.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"offline"</span><span class="p">,</span> <span class="nx">onOffline</span><span class="p">,</span> <span class="kc">false</span><span class="p">);</span> +<span class="nb">document</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">"online"</span><span class="p">,</span> <span class="nx">onOnline</span><span class="p">,</span> <span class="kc">false</span><span class="p">);</span> +</code></pre></div> +<p>The app's <code>onOnline</code> function handles the online event. In the event handler, check the current network state. In this app, treat any connection type as good except Connection.NONE. If you have a connection, you try to upload a file.</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">onOnline</span><span class="p">()</span> <span class="p">{</span> + <span class="c1">// Handle the online event</span> + <span class="kd">var</span> <span class="nx">networkState</span> <span class="o">=</span> <span class="nx">navigator</span><span class="p">.</span><span class="nx">connection</span><span class="p">.</span><span class="nx">type</span><span class="p">;</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">networkState</span> <span class="o">!==</span> <span class="nx">Connection</span><span class="p">.</span><span class="nx">NONE</span><span class="p">)</span> <span class="p">{</span> + <span class="k">if</span> <span class="p">(</span><span class="nx">dataFileEntry</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">tryToUploadFile</span><span class="p">();</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="nx">display</span><span class="p">(</span><span class="s1">'Connection type: '</span> <span class="o">+</span> <span class="nx">networkState</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> +<p>When the online event fires in the preceding code, call the app's <code>tryToUploadFile</code> function.</p> + +<p>If the FileTransfer object's upload function fails, call the app's <code>offlineWrite</code> function to save the current data somewhere.</p> + +<blockquote> +<p><em>Note</em> This example requires the FileTransfer plugin.</p> +</blockquote> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">tryToUploadFile</span><span class="p">()</span> <span class="p">{</span> + <span class="c1">// !! Assumes variable fileURL contains a valid URL to a text file on the device,</span> + <span class="kd">var</span> <span class="nx">fileURL</span> <span class="o">=</span> <span class="nx">getDataFileEntry</span><span class="p">().</span><span class="nx">toURL</span><span class="p">();</span> + + <span class="kd">var</span> <span class="nx">success</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">r</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Response = "</span> <span class="o">+</span> <span class="nx">r</span><span class="p">.</span><span class="nx">response</span><span class="p">);</span> + <span class="nx">display</span><span class="p">(</span><span class="s2">"Uploaded. Response: "</span> <span class="o">+</span> <span class="nx">r</span><span class="p">.</span><span class="nx">response</span><span class="p">);</span> + <span class="p">}</span> + + <span class="kd">var</span> <span class="nx">fail</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"An error has occurred: Code = "</span> <span class="o">+</span> <span class="nx">error</span><span class="p">.</span><span class="nx">code</span><span class="p">);</span> + <span class="nx">offlineWrite</span><span class="p">(</span><span class="s2">"Failed to upload: some offline data"</span><span class="p">);</span> + <span class="p">}</span> + + <span class="kd">var</span> <span class="nx">options</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">FileUploadOptions</span><span class="p">();</span> + <span class="nx">options</span><span class="p">.</span><span class="nx">fileKey</span> <span class="o">=</span> <span class="s2">"file"</span><span class="p">;</span> + <span class="nx">options</span><span class="p">.</span><span class="nx">fileName</span> <span class="o">=</span> <span class="nx">fileURL</span><span class="p">.</span><span class="nx">substr</span><span class="p">(</span><span class="nx">fileURL</span><span class="p">.</span><span class="nx">lastIndexOf</span><span class="p">(</span><span class="s1">'/'</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">);</span> + <span class="nx">options</span><span class="p">.</span><span class="nx">mimeType</span> <span class="o">=</span> <span class="s2">"text/plain"</span><span class="p">;</span> + + <span class="kd">var</span> <span class="nx">ft</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">FileTransfer</span><span class="p">();</span> + <span class="c1">// Make sure you add the domain of your server URL to the</span> + <span class="c1">// Content-Security-Policy <meta> element in index.html.</span> + <span class="nx">ft</span><span class="p">.</span><span class="nx">upload</span><span class="p">(</span><span class="nx">fileURL</span><span class="p">,</span> <span class="nb">encodeURI</span><span class="p">(</span><span class="nx">SERVER</span><span class="p">),</span> <span class="nx">success</span><span class="p">,</span> <span class="nx">fail</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span> +<span class="p">};</span> +</code></pre></div> +<p>Here is the code for the <code>offlineWrite</code> function.</p> + +<blockquote> +<p><em>Note</em> This code examples requires the File plugin.</p> +</blockquote> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">offlineWrite</span><span class="p">(</span><span class="nx">offlineData</span><span class="p">)</span> <span class="p">{</span> + <span class="c1">// Create a FileWriter object for our FileEntry.</span> + <span class="nx">dataFileEntry</span><span class="p">.</span><span class="nx">createWriter</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">fileWriter</span><span class="p">)</span> <span class="p">{</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onwriteend</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Successful file write..."</span><span class="p">);</span> + <span class="nx">display</span><span class="p">(</span><span class="nx">offlineData</span><span class="p">);</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"Failed file write: "</span> <span class="o">+</span> <span class="nx">e</span><span class="p">.</span><span class="nx">toString</span><span class="p">());</span> + <span class="p">};</span> + + <span class="nx">fileWriter</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="nx">offlineData</span><span class="p">);</span> + <span class="p">});</span> +<span class="p">}</span> +</code></pre></div> +<p>If the offline event occurs, just do something like notify the user (for this example, just log it).</p> +<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">onOffline</span><span class="p">()</span> <span class="p">{</span> + <span class="c1">// Handle the offline event</span> + <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">"lost connection"</span><span class="p">);</span> +<span class="p">}</span> +</code></pre></div> </div> </div> --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
