Author: steven
Date: Fri Feb 2 17:37:32 2018
New Revision: 1822991
URL: http://svn.apache.org/viewvc?rev=1822991&view=rev
Log:
Updated docs
Added:
cordova/site/public/howto/
cordova/site/public/howto/2018/
cordova/site/public/howto/2018/02/
cordova/site/public/howto/2018/02/02/
cordova/site/public/howto/2018/02/02/cordova-simulate.html
cordova/site/public/static/img/blog/
cordova/site/public/static/img/blog/2018/
cordova/site/public/static/img/blog/2018/cordova-simulate-1.png (with
props)
cordova/site/public/static/img/blog/2018/cordova-simulate-2.png (with
props)
cordova/site/public/static/img/blog/2018/cordova-simulate-3.png (with
props)
cordova/site/public/static/img/blog/2018/cordova-simulate-4.png (with
props)
Modified:
cordova/site/public/blog/index.html
cordova/site/public/feed.xml
cordova/site/public/news/2018/01/29/plugins-release.html
cordova/site/public/sitemap.xml
cordova/site/public/static/js/index.js
Modified: cordova/site/public/blog/index.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/blog/index.html?rev=1822991&r1=1822990&r2=1822991&view=diff
==============================================================================
--- cordova/site/public/blog/index.html (original)
+++ cordova/site/public/blog/index.html Fri Feb 2 17:37:32 2018
@@ -124,6 +124,34 @@
<li>
<header>
+ <div class="adorner" blogTime="Fri, 02 Feb 2018 00:00:00
+0000"></div>
+ <h2 class="title">
+ <a href="/howto/2018/02/02/cordova-simulate.html">A
Better Way to Exercise Cordova Plugins</a>
+ </h2>
+ <div class="details">
+ <span class="date">02 Feb 2018</span>
+ - by
+ <span class="author">
+
+ <a href="https://twitter.com/johnwargo";>John
M. Wargo</a>
+
+ </span>
+ <a class="comment"
href="/howto/2018/02/02/cordova-simulate.html#disqus_thread"></a>
+ </div>
+ </header>
+ <section class="post-excerpt">
+ <p><p>Cordova developers have several ways to test and
debug their Cordova applications. For functional testing, developers use
emulators, simulators, and physical devices. Devices can be on-premises, or
there are many cloud offerings available as well. There's even great tools
you can use to debug your applications such as the web app debugging
capabilities of Chrome and Safari, as well as the excellent debugging
capabilities of Microsoft's Visual Studio Code extension for Apache
Cordova.</p>
+
+<p>For debugging plugins, or debugging applications that utilize Cordova
plugins, things aren't that bad. For most plugins, I imagine that any
physical device has whatever's needed to work with a plugin, unless the
plugin requires some external hardware device or has other requirements that
aren't by every device. For several of the core Cordova plugins, the device
emulators and simulators expose capabilities that enable testers to simulate
things like the camera, accelerometer, compass, and other device-side
capabilities (although, surprisingly, early iOS simulators didn't support
camera simulation).</p>
+
+<p>When it comes to exercising all the capabilities of a plugin, especially
simulating error conditions so you can tell how the app responds, it gets
complicated. Developers often find themselves hacking away at plugin code,
either mocking up simulation scenarios, or manually changing the behavior of
the plugin during testing. In many cases, developers must manually force error
conditions in their plugins so they can validate error checking within their
app. I haven't written many Cordova plugins, but in the little work I have
done, I've wished that there was a better way. Well, it turns out that
there is.</p>
+</p>
+ <div><a
href="/howto/2018/02/02/cordova-simulate.html">More...</a></div>
+ </section>
+ </li>
+
+ <li>
+ <header>
<div class="adorner" blogTime="Mon, 29 Jan 2018 00:00:00
+0000"></div>
<h2 class="title">
<a
href="/news/2018/01/29/plugins-release.html">Plugins Release</a>
@@ -7201,7 +7229,7 @@ window.twttr = (function(d, s, id) {
<script>
window.onload = function(){
setTimeout(function(){
- var lastPostTime = new Date("Mon, 29 Jan 2018 00:00:00
+0000").getTime();
+ var lastPostTime = new Date("Fri, 02 Feb 2018 00:00:00
+0000").getTime();
setCookie("visitTime", lastPostTime, 365);
}, 2000);
};
Modified: cordova/site/public/feed.xml
URL:
http://svn.apache.org/viewvc/cordova/site/public/feed.xml?rev=1822991&r1=1822990&r2=1822991&view=diff
==============================================================================
--- cordova/site/public/feed.xml (original)
+++ cordova/site/public/feed.xml Fri Feb 2 17:37:32 2018
@@ -6,11 +6,314 @@
</description>
<link>https://cordova.apache.org/</link>
<atom:link href="https://cordova.apache.org/feed.xml"; rel="self"
type="application/rss+xml"/>
- <pubDate>Tue, 30 Jan 2018 18:07:02 +0000</pubDate>
- <lastBuildDate>Tue, 30 Jan 2018 18:07:02 +0000</lastBuildDate>
+ <pubDate>Fri, 02 Feb 2018 17:10:31 +0000</pubDate>
+ <lastBuildDate>Fri, 02 Feb 2018 17:10:31 +0000</lastBuildDate>
<generator>Jekyll v2.5.3</generator>
<item>
+ <title>A Better Way to Exercise Cordova Plugins</title>
+ <description><p>Cordova developers have several ways to test and
debug their Cordova applications. For functional testing, developers use
emulators, simulators, and physical devices. Devices can be on-premises, or
there are many cloud offerings available as well. There&#39;s even great
tools you can use to debug your applications such as the web app debugging
capabilities of Chrome and Safari, as well as the excellent debugging
capabilities of Microsoft&#39;s Visual Studio Code extension for Apache
Cordova.</p>
+
+<p>For debugging plugins, or debugging applications that utilize Cordova
plugins, things aren&#39;t that bad. For most plugins, I imagine that any
physical device has whatever&#39;s needed to work with a plugin, unless the
plugin requires some external hardware device or has other requirements that
aren&#39;t by every device. For several of the core Cordova plugins, the
device emulators and simulators expose capabilities that enable testers to
simulate things like the camera, accelerometer, compass, and other device-side
capabilities (although, surprisingly, early iOS simulators didn&#39;t
support camera simulation).</p>
+
+<p>When it comes to exercising all the capabilities of a plugin,
especially simulating error conditions so you can tell how the app responds, it
gets complicated. Developers often find themselves hacking away at plugin code,
either mocking up simulation scenarios, or manually changing the behavior of
the plugin during testing. In many cases, developers must manually force error
conditions in their plugins so they can validate error checking within their
app. I haven&#39;t written many Cordova plugins, but in the little work I
have done, I&#39;ve wished that there was a better way. Well, it turns out
that there is.</p>
+
+<!--more-->
+
+<p>Many, many years ago, a small company named Tiny Hippos created the
Ripple Emulator, a browser-based emulator for many mobile devices. Ripple was
interesting in many ways, but for the scope of this article, one of the
interesting features was its implementation of emulators for many of the core
Cordova plugins. As you ran your Cordova application in one pane, a separate
pane opened with options to control many aspects of the simulated environment
as shown in the following figure.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-1.png"
alt="Figure 1"></p>
+
+<p>Well, shortening a long story a bit, the folks at Research In Motion
(BlackBerry) purchased Tiny Hippos and maintained Ripple for a while before
finally contributing it to the Apache Foundation as an incubator project. Many
companies got involved, including Adobe, Microsoft, and others, but the project
never really took off, or ever became a stable product. It never actually made
it out of beta.</p>
+
+<p>Anyway, fast forward to today and you&#39;ll find that Microsoft
took the Ripple project and rebuilt it. We kept some of the original code (some
of the plugin simulation panels and supporting utility functions), rewrote some
parts, created some new code, then released it as an open source project called
Cordova Simulate (<a
href="https://github.com/Microsoft/cordova-simulate">https://github.com/Microsoft/cordova-simulate</a>).
We chose this approach, rather than investing in Ripple, because:</p>
+
+<ul>
+<li>We had regular reports of issues with Ripple starting and Visual
Studio not being able to connect to it successfully, so we wanted a simpler
architecture for rendering the Cordova web app (a separate browser window that
just hosted the app, and nothing else).</li>
+<li>Debugging Ripple was a challenge since you were effectively
debugging both the app and Ripple itself (you had to drill down into the Ripple
UI&#39;s HTML to find the hosted Cordova web app, and Ripple&#39;s
JavaScript code could easily be a part of your stack when debugging).</li>
+<li>Since Ripple and the Cordova web app render in the same browser
window, if the Cordova web app froze for any reason, Ripple also froze (or, in
less severe cases, the Ripple UI could look unresponsive when the Cordova web
app is busy).</li>
+</ul>
+
+<p>Cordova Simulate solves these issues:</p>
+
+<ul>
+<li>The app window doesn&#39;t also host the simulation UI - just
the app (and a small bit of code to enable communication with the simulation
UI). This solves the first two problems identified above.</li>
+<li>The simulation UI renders in a separate window, and all
communication is asynchronous, so an unresponsive app won&#39;t interfere
with the simulation UI. This solves the third problem.</li>
+</ul>
+
+<p>Another driving purpose for Cordova Simulate was that we wanted to
make it extensible; allowing plugins to define their own simulation
functionality (as you&#39;ll soon learn about).</p>
+
+<p>To my previous point about Ripple never making it out of beta, not
only is Cordova Simulate a complete, robust, and released solution,
it&#39;s even part of several Microsoft offerings (both commercial and open
source). Its bundled into Visual Studio Tools for Apache Cordova (TACO - <a
href="http://taco.visualstudio.com/">http://taco.visualstudio.com/</a>)
in Visual Studio 2017. It&#39;s also included as part of the Apache
Cordova extension for Visual Studio Code (<a
href="https://github.com/Microsoft/vscode-cordova">https://github.com/Microsoft/vscode-cordova</a>).
</p>
+
+<p>Why is this important to you? Well, let me explain...</p>
+
+<p>With Cordova Simulate, you now have access to a complete solution for
testing your apps against simulated versions of the core Cordova plugins. This
eliminates the need to hack up your code to simulate plugin responses as
Cordova Simulate takes care of that for you.</p>
+
+<p><strong>Note:</strong> If you just read the last
paragraph, and said to yourself &quot;so what?&quot; just hang on for a
little while longer.</p>
+
+<p>The most important benefit for you is that you can add support for
Cordova Simulate to each of your custom plugins as well. Then, when
you&#39;re exercising your plugins during plugin development, or when your
customers are using your plugins, you have a standard way to simulate the
capabilities of your plugin (including error scenarios). When third-party
providers add support for Cordova Simulate to their plugins, suddenly
developers can accurately test each aspect of their application using a variety
of plugins.</p>
+
+<p>Let me show you how to install and use Cordova Simulate, then
I&#39;ll show you how to add support for Cordova Simulate to your custom
plugins. If you&#39;re using someone else&#39;s plugin, and they
don&#39;t have support for Cordova Simulate in the plugin, add it yourself
and submit a pull request, it&#39;s not that hard.</p>
+
+<h2>Installing Cordova Simulate</h2>
+
+<p>As I mentioned before, Visual Studio Tools for Apache Cordova and the
Cordova extension for Visual Studio Code both include Cordova Simulate, so
there&#39;s no extra installation instructions to follow - just install the
tools, and you&#39;ll have what you need.</p>
+
+<p>You can also invoke Cordova Simulate from the command line, or from
third party IDEs. To install Cordova Simulate for those scenarios, open a
terminal window, and execute the following command:</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">npm install -g
cordova-simulate
+</code></pre></div>
+<p>That&#39;s it, that&#39;s all there is to it. When the
process completes, you&#39;ll now have a <code>simulate</code>
command at your disposal to launch Cordova Simulate.</p>
+
+<h2>Launching Cordova Simulate</h2>
+
+<p>The following sections describe how to launch Cordova Simulate in
different ways.</p>
+
+<h3>Visual Studio</h3>
+
+<p>If you&#39;re running an app in Visual Studio &amp; TACO,
just choose the <strong>Simulate in Browser</strong> option, and
the app launches Cordova Simulate. Cordova Simulate will open the Chrome
browser and run the web application part of your Cordova app. Cordova Simulate
will also open a simulator control window in Visual Studio (using Internet
Explorer, no surprise there). You&#39;ll interact with the app in the
Chrome window and simulate methods and properties in the plugins using the
simulator control window. I&#39;ll show you how in a minute.</p>
+
+<h3>Visual Studio Code</h3>
+
+<p>If you&#39;re using Visual Studio Code, go to the
<strong>Debug</strong> tab, enable <strong>Cordova
debugging</strong>, then execute either the <strong>Simulate
Android in browser</strong> or <strong>Simulate iOS in
browser</strong> options. Cordova Simulate will open the Chrome browser
and execute the web application part of your Cordova app. Cordova Simulate will
also open a simulator control window inside Visual Studio Code. You&#39;ll
interact with the app in the Chrome window and simulate methods and properties
in the plugins using the simulator control window. I&#39;ll show you how in
a minute.</p>
+
+<h3>Command-line</h3>
+
+<p>To launch Cordova Simulate from the command-line, open a terminal
window, navigate to a Cordova project folder, and execute the following
command:</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">simulate \[platform\]
+</code></pre></div>
+<p>Platform refers to one of the supported target platforms (for
example: <code>android</code>, <code>ios</code>, or
<code>browser</code>). For example, to simulate the Android version
of your Cordova application, you would use the following:</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">simulate android
+</code></pre></div>
+<p>Cordova Simulate will open the Chrome browser with two tabs, one
running the Cordova app web app, and the other displaying the simulator control
window shown in the following figure.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-2.png"
alt="Figure 2"></p>
+
+<p>By default, Cordova Simulate loads a default set of plugin
simulators:</p>
+
+<ul>
+<li>Since HTML has native support for geolocation, Cordova Simulate
automatically loads the Geolocation simulator pane.</li>
+<li>The event simulator pane loads automatically to enable developers to
trigger Cordova and device events as needed</li>
+<li>Persisted Exec Calls pane enables basic simulator support for
third-party plugins that don&#39;t include support for Cordova
Simulate.</li>
+<li>The Device simulator loads automatically to enable you to change the
target device used for rendering the web app.</li>
+</ul>
+
+<p>If I&#39;d added other Cordova core plugins to my project,
Cordova Simulate would load simulators for each, if available.</p>
+
+<p>At this point, you can interact with your app as needed, and switch
to the simulator control window to adjust plugin properties and method call
results. For example, if your Cordova app used the Geolocation plugin to track
the device&#39;s location, changing any of the values in the Geolocation
simulator pane would cause the app&#39;s next call to
<code>navigator.geolocation.getCurrentPosition</code> to receive
the updated value you entered into the pane.</p>
+
+<h2>Adding Cordova Simulate Support to Your Plugins</h2>
+
+<p>Alright, it&#39;s time to show you how to add Cordova Simulate
support to your own plugins. First, you must add a
<code>simulation</code> folder to your plugin&#39;s
<code>src</code> folder (so
<code>src/simulation/</code>). Inside that folder, you&#39;ll
create one or more of the following files based on the needs of your
plugin:</p>
+
+<ul>
+<li><code>app-host-clobbers.js</code></li>
+<li><code>app-host-handlers.js</code></li>
+<li><code>app-host.js</code></li>
+<li><code>sim-host-dialogs.html</code></li>
+<li><code>sim-host-handlers.js</code></li>
+<li><code>sim-host-panels.html</code></li>
+<li><code>sim-host.js</code></li>
+</ul>
+
+<p>For my simple example, I&#39;m only going to need three files,
but refer to the Cordova Simulate documentation at <a
href="https://github.com/Microsoft/cordova-simulate">https://github.com/Microsoft/cordova-simulate</a>
for details about each of these files.</p>
+
+<p>The plugin I used for my example is a simple Carrier plugin I created
many years ago for one of my Cordova books: <a
href="https://www.npmjs.com/package/johnwargo-cordova-plugin-carrier">https://www.npmjs.com/package/johnwargo-cordova-plugin-carrier</a>.
It exposes two methods:</p>
+
+<ul>
+<li><code>getCarrierName</code>: An asynchronous method that
retrieves the current carrier for the device running the application.</li>
+<li><code>getCountryCode</code>: An asynchronous method that
retrieves the country code for the device running the application</li>
+</ul>
+
+<p>When exercising this plugin, I&#39;ll need the ability to
validate my app&#39;s code against different carrier and country code
values. To simulate this, I&#39;ll need an HTML panel that offers multiple
carrier and country code choices. For this, I created a
<code>sim-host.panels.html</code> file in the plugin
project&#39;s <code>src/simulation/</code> folder. The file
creates a simple panel with two drop-down lists containing some country and
carrier values:</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">&lt;cordova-panel
id="johnwargo-cordova-plugin-carrier" caption="Carrier"
+ spoken-text="Carrier"&gt;
+ &lt;cordova-panel-row&gt;
+ Select carrier and country code options from the drop-down lists below.
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ &lt;cordova-label label="Carrier Name"
spoken="carrier name"&gt;&lt;/cordova-label&gt;
+ &lt;cordova-combo spoken-text="Simulated value for wireless
carrier"
+ id="carrier-select" style="width:auto; min-width:0;
display:inline;"&gt;
+ &lt;option value="AT&amp;T"
selected="selected"&gt;AT&amp;T&lt;/option&gt;
+ &lt;option
value="Sprint"&gt;Sprint&lt;/option&gt;
+ &lt;option
value="T-Mobile"&gt;T-Mobile&lt;/option&gt;
+ &lt;option value="US Cellular"&gt;US
Cellular&lt;/option&gt;
+ &lt;option
value="Verizon"&gt;Verizon&lt;/option&gt;
+ &lt;/cordova-combo&gt;
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ &lt;cordova-label label="Country Code"
spoken="country code"&gt;&lt;/cordova-label&gt;
+ &lt;cordova-combo spoken-text="Simulated value for country
code"
+ id="country-code-select" style="width:auto;
min-width:0; display:inline;"&gt;
+ &lt;option
value="CA"&gt;Canada&lt;/option&gt;
+ &lt;option
value="MX"&gt;Mexico&lt;/option&gt;
+ &lt;option value="US"
selected="selected"&gt;United States&lt;/option&gt;
+ &lt;/cordova-combo&gt;
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-checkbox id="is-error"
spoken=""&gt;Error condition&lt;/cordova-checkbox&gt;
+&lt;/cordova-panel&gt;
+</code></pre></div>
+<p>As you can see from the code, the panel makes use of special HTML
element types supported by Cordova Simulate. The simulator code for most of the
core Cordova plugins is included with the Cordova Simulate Github repository,
so you can find examples there of the available UI elements in use.</p>
+
+<p>Next, I added a <code>sim-host.js</code> file to the
folder. This file isn&#39;t necessary, but it provides an opportunity to
initialize the simulated plugin, and I use it to update the console whenever
the user makes a change in the simulation panel. Not critically important, but
useful as I sorted out what was happening as I built the simulation.</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">module.exports = {
+ initialize: function() {
+ //Get access to the carrier selection drop-down
+ var carrierSel = document.getElementById('carrier-select');
+ //Add a change event listener to the field
+ carrierSel.addEventListener('change', carrierChange);
+ //Get access to the country code selection drop-down
+ var ccSel = document.getElementById('country-code-select');
+ //Add a change event listener to the field
+ ccSel.addEventListener('change', ccChange);
+
+ function carrierChange() {
+ console.log("Carrier selection changed to " +
this.value);
+ }
+
+ function ccChange() {
+ console.log("Country code selection changed to " +
this.value);
+ }
+ }
+};
+</code></pre></div>
+<p>If you study the source code for the simulator capabilities in the
core Cordova plugins, you&#39;ll see that many of them use change events
like the ones just shown in the code to update properties for objects exposed
by the plugins. As developers change values in the simulator panel, the change
events register the change and updates a local object. Then, when a Cordova
application accesses one of those properties, the code returns the value from
the local object.</p>
+
+<p>Finally, I added a <code>sim-host-handlers.js</code> file
to the project. The code in this file overrides the
<code>cordova.exec</code> calls from the plugin in the simulated
environment. Here, I export the native methods supported by the plugin and pull
the selected values from the simulator panel and return them to the calling
application.</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">module.exports =
function(messages) {
+ return {
+ carrier: {
+ getCarrierName: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCarrierName
invoked");
+ //Get access to the carrier selection drop-down
+ var carrierSel =
document.getElementById('carrier-select');
+ //Pull the value from the selected item
+ var selValue =
carrierSel.options[carrierSel.selectedIndex].value;
+ console.log('Simulating carrier: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ },
+ getCountryCode: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCountryCode
invoked");
+ //Get access to the country code selection drop-down
+ var ccSel =
document.getElementById('country-code-select');
+ //Pull the value from the selected item
+ var selValue = ccSel.options[ccSel.selectedIndex].value;
+ console.log('Simulating country code: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ }
+ };
+};
+</code></pre></div>
+<p>This is a very simple example of what you can do, be sure to check
out the source code for the simulator capabilities included with core Cordova
plugins for more sophisticated examples.</p>
+
+<p>Now, when you create a Cordova application that uses this plugin,
then execute Cordova Simulate, you&#39;ll see the following panel exposed
on the Cordova Simulate Simulator Control window:</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-3.png"
alt="Figure 3"></p>
+
+<p>Make the appropriate changes to the panel, then call the associated
APIs from the Cordova application to see the selected results.</p>
+
+<p>If you think about what we&#39;ve done so far, we&#39;ve only
addressed success scenarios - changing the behavior of the plugin in the
simulated environment so we can test the app with different API results. Most
plugins also report error conditions, and in order to properly exercise the
plugin or an app using the plugin, you must be able to simulate error
conditions as well. Let me show you how to do that.</p>
+
+<p>First, I added a new row to the
<code>sim-host.panels.html</code> file:</p>
+<div class="highlight"><pre><code
class="language-"
data-lang="">&lt;cordova-panel-row&gt;
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+&lt;/cordova-panel-row&gt;
+&lt;cordova-checkbox id="is-error"
spoken=""&gt;Error condition&lt;/cordova-checkbox&gt;
+</code></pre></div>
+<p>This adds an Error checkbox to the panel, enabling developers to
return an error from each plugin API call. The updated
<code>sim-host.panels.html</code> file looks like this:</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">&lt;cordova-panel
id="johnwargo-cordova-plugin-carrier" caption="Carrier"
+ spoken-text="Carrier"&gt;
+ &lt;cordova-panel-row&gt;
+ Select carrier and country code options from the drop-down lists below.
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ &lt;cordova-label label="Carrier Name"
spoken="carrier name"&gt;&lt;/cordova-label&gt;
+ &lt;cordova-combo spoken-text="Simulated value for wireless
carrier"
+ id="carrier-select" style="width:auto; min-width:0;
display:inline;"&gt;
+ &lt;option value="AT&amp;T"
selected="selected"&gt;AT&amp;T&lt;/option&gt;
+ &lt;option
value="Sprint"&gt;Sprint&lt;/option&gt;
+ &lt;option
value="T-Mobile"&gt;T-Mobile&lt;/option&gt;
+ &lt;option value="US Cellular"&gt;US
Cellular&lt;/option&gt;
+ &lt;option
value="Verizon"&gt;Verizon&lt;/option&gt;
+ &lt;/cordova-combo&gt;
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ &lt;cordova-label label="Country Code"
spoken="country code"&gt;&lt;/cordova-label&gt;
+ &lt;cordova-combo spoken-text="Simulated value for country
code"
+ id="country-code-select" style="width:auto;
min-width:0; display:inline;"&gt;
+ &lt;option
value="CA"&gt;Canada&lt;/option&gt;
+ &lt;option
value="MX"&gt;Mexico&lt;/option&gt;
+ &lt;option value="US"
selected="selected"&gt;United States&lt;/option&gt;
+ &lt;/cordova-combo&gt;
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-panel-row&gt;
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+ &lt;/cordova-panel-row&gt;
+ &lt;cordova-checkbox id="is-error"
spoken=""&gt;Error condition&lt;/cordova-checkbox&gt;
+&lt;/cordova-panel&gt;
+</code></pre></div>
+<p>Now, in the <code>sim-host-handlers.js</code> file, I
added a check for the checkbox status in each of the methods exposed in the
file. For my plugin, with the checkbox checked, the method calls the error
callback function returning a dummy JSON object containing a simple error
message and code. For your plugins, you&#39;ll likely want to expand this
so you can simulate different error conditions.</p>
+<div class="highlight"><pre><code
class="language-" data-lang="">module.exports =
function(messages) {
+ return {
+ carrier: {
+ getCarrierName: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCarrierName
invoked");
+ if (document.getElementById('is-error').checked) {
+ console.error("Error condition enabled");
+ errorCallback({ code: 1, msg: "Simulated error
condition" });
+ } else {
+ //Get access to the carrier selection drop-down
+ var carrierSel =
document.getElementById('carrier-select');
+ //Pull the value from the selected item
+ var selValue =
carrierSel.options[carrierSel.selectedIndex].value;
+ console.log('Simulating carrier: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ },
+ getCountryCode: function(successCallback, errorCallback) {
+ if (document.getElementById('is-error').checked) {
+ console.error("Error condition enabled");
+ errorCallback({ code: 2, msg: "Simulated error
condition" });
+ } else {
+ console.log("Cordova-Simulate: getCountryCode
invoked");
+ //Get access to the country code selection drop-down
+ var ccSel =
document.getElementById('country-code-select');
+ //Pull the value from the selected item
+ var selValue = ccSel.options[ccSel.selectedIndex].value;
+ console.log('Simulating country code: ' +
selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ }
+ }
+ };
+};
+</code></pre></div>
+<p>Now, when I execute Cordova simulate I&#39;ll see the slightly
different panel shown below.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-4.png"
alt="Figure 4"></p>
+
+<p>That&#39;s it, that&#39;s all there is to enable simulation
in your own plugins. As you can hopefully see, Cordova Simulate gives
developers (plugin developers and developers who use those developer&#39;s
plugins in their applications) an easier way to exercise the plugin and test
applications using the plugin. </p>
+
+<p>Cordova Simulate is an open source project from Microsoft, but
we&#39;d love to have your help enhancing it and fixing issues as they
arise. Please follow the project on Github and take a look at how you can help
enhance this project.</p>
+</description>
+ <pubDate>Fri, 02 Feb 2018 00:00:00 +0000</pubDate>
+
<link>https://cordova.apache.org/howto/2018/02/02/cordova-simulate.html</link>
+ <guid
isPermaLink="true">https://cordova.apache.org/howto/2018/02/02/cordova-simulate.html</guid>
+
+
+ <category>howto</category>
+
+ </item>
+
+ <item>
<title>Plugins Release</title>
<description><p>The following plugins were updated
today:</p>
@@ -967,50 +1270,5 @@ cordova plugin add cordova-plugin-camera
</item>
- <item>
- <title>Cordova Android 6.4.0 Released!</title>
- <description><p>We would like to announce that
<code>Cordova Android 6.4.0</code> has been released! </p>
-
-<p>This release now uses the latest Android Gradle plugin that was
released with Android Studio 3.0.</p>
-
-<p>Due to the recent changes Google made to Android Studio, Cordova
Android now requires that Gradle is installed as a standalone dependency for
Android development on all platforms. You can do so by <a
href="https://gradle.org/install/">following these instructions at
gradle.org</a>.<br>
-We will be removing the code that uses Android Studio to provide Gradle as a
dependency in the near future.</p>
-
-<p>Google also has changed the Gradle DSL used and currently support for
the Crosswalk WebView is broken in this version of Cordova as a result.
Unfortunately, since Crosswalk is no longer supported by the <a
href="https://crosswalk-project.org/">Crosswalk Project</a>,
we do not know whether <a
href="https://github.com/crosswalk-project/cordova-plugin-crosswalk-webview/issues/183">this
issue</a> will be fixed.<br>
-If you require support for Crosswalk, we recommend that you continue using
cordova-android 6.3.0 at this time and avoid using or upgrading your project
with Android Studio.</p>
-
-<p>To upgrade:</p>
-<div class="highlight"><pre><code
class="language-" data-lang="">npm install -g cordova
-cd my_project
-cordova platform update [email protected]
-</code></pre></div>
-<p>To add it explicitly:</p>
-<div class="highlight"><pre><code
class="language-" data-lang="">cordova platform add
[email protected]
-</code></pre></div>
-<!--more-->
-
-<h2>What&#39;s new in Android</h2>
-
-<ul>
-<li><a
href="https://issues.apache.org/jira/browse/CB-13289">CB-13289</a>
Fixing build problems with Studio Three, but keeping
<strong>Windows</strong> Gradle fix for now, will be
deprecated</li>
-<li><a
href="https://issues.apache.org/jira/browse/CB-13289">CB-13289</a>
Fix test to work with new Google <strong>Android</strong> Gradle
DSL</li>
-<li><a
href="https://issues.apache.org/jira/browse/CB-13499">CB-13499</a>
Remove duplicate &quot;setting&quot; in error strings</li>
-<li><a
href="https://issues.apache.org/jira/browse/CB-13406">CB-13406</a>
Fixed AVD API level comparison when choosing sub-par API level match. Added
tests for the best_image method.</li>
-<li><a
href="https://issues.apache.org/jira/browse/CB-13404">CB-13404</a>
add <strong>Android</strong>-versions to bundledDependencies.
Ignore best emulator selection when parsed AVD information does not include API
level in the target</li>
-</ul>
-</description>
- <pubDate>Thu, 09 Nov 2017 00:00:00 +0000</pubDate>
-
<link>https://cordova.apache.org/announcements/2017/11/09/android-release.html</link>
- <guid
isPermaLink="true">https://cordova.apache.org/announcements/2017/11/09/android-release.html</guid>
-
- <category>news</category>
-
- <category>releases</category>
-
-
- <category>announcements</category>
-
- </item>
-
</channel>
</rss>
Added: cordova/site/public/howto/2018/02/02/cordova-simulate.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/howto/2018/02/02/cordova-simulate.html?rev=1822991&view=auto
==============================================================================
--- cordova/site/public/howto/2018/02/02/cordova-simulate.html (added)
+++ cordova/site/public/howto/2018/02/02/cordova-simulate.html Fri Feb 2
17:37:32 2018
@@ -0,0 +1,565 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta name="format-detection" content="telephone=no">
+ <meta name="viewport" content="user-scalable=no, initial-scale=1,
maximum-scale=1, minimum-scale=1, width=device-width" />
+ <meta name="description" content="Cordova developers have several ways to
test and debug their Cordova applications. For functional testing, developers
use emulators, simulators, and physical...">
+
+ <title>
+
+
+ A Better Way to Exercise Cordova Plugins - Apache Cordova
+
+
+ </title>
+
+ <link rel="SHORTCUT ICON" href="/favicon.ico"/>
+
+
+
+
+
+
+ <link rel="canonical"
href="https://cordova.apache.org/howto/2018/02/02/cordova-simulate.html";>
+
+ <!-- CSS -->
+ <link rel="stylesheet" type="text/css" href="/static/css/main.css">
+ <link rel="stylesheet" type="text/css" href="/static/css/lib/syntax.css">
+ <!-- Algolia Search CSS -->
+ <link rel="stylesheet"
href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"; />
+
+ <!-- Fonts -->
+ <!-- For attribution information, see www/attributions.html -->
+ <link
href='https://fonts.googleapis.com/css?family=Raleway:700,400,300,700italic,400italic,300italic'
rel='stylesheet' type='text/css'>
+
+ <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media
queries -->
+ <!--[if lt IE 9]>
+ <script
src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js";></script>
+ <script
src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js";></script>
+ <![endif]-->
+ <script type="text/javascript">
+ var disqus_developer = 1; // this would set it to developer mode
+ </script>
+
+ <!-- JS -->
+ <script defer type="text/javascript"
src="/static/js/lib/jquery-2.1.1.min.js"></script>
+ <script defer type="text/javascript"
src="/static/js/lib/bootstrap.min.js"></script>
+ <script defer type="text/javascript"
src="/static/js/lib/ZeroClipboard.js"></script>
+
+ <script>
+
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new
Date();a=s.createElement(o),
+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+ ga('create', 'UA-64283057-3', 'auto');
+ ga('send', 'pageview');
+</script>
+
+</head>
+
+<body>
+ <header>
+ <a class="scroll-point pt-top" name="top"></a>
+ <nav class="navbar navbar-inverse navbar-fixed-top">
+ <div class="container-fluid">
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target="#navbar" aria-expanded="false"
aria-controls="navbar">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+ <a class="navbar-brand" href="/"><img id="logo_top"
src="/static/img/cordova-logo-newbrand.svg"/></a>
+ </div>
+ <div id="navbar" class="navbar-collapse collapse">
+ <div class="nav_bar_center">
+ <ul class="nav navbar-nav">
+ <li >
+ <a href="/docs/en/latest/">Documentation</a>
+ </li>
+ <li >
+ <a href="/plugins">Plugins</a>
+ </li>
+ <li class="active">
+ <a href="/blog" id="blog_button">Blog<span
class="badge" id="new_blog_count"></span></a>
+ </li>
+ <li >
+ <a href="/contribute">Contribute</a>
+ </li>
+ <li>
+ <a href="/#getstarted">Get Started</a>
+ </li>
+ <li>
+ <form class="navbar-form navbar-right"
id="header-search-form" role="search">
+ <div class="input-group">
+
+
+
+ <input id="header-search-field"
type="text" placeholder="Search '7.x' docs..." class="form-control hidden-xs"
autocomplete="off">
+ </div>
+ </form>
+ </li>
+ </ul>
+ </div>
+ </div><!--/.navbar-collapse -->
+ </div>
+ </nav>
+ <div id="_fixed_navbar_spacer" style="padding-top:50px"></div>
+</header>
+
+<div class="page container">
+ <div class="blog">
+ <h1 class="blogHeader">
+ Blog
+ <span class="rss">
+ <img src="/static/img/subscribe.png"><a href="/feed.xml">RSS Feed</a>
+ </span>
+</h1>
+
+<div class="post">
+ <header>
+ <div class="title">A Better Way to Exercise Cordova Plugins</div>
+ <div class="author">By:
+
+ <a href="https://twitter.com/johnwargo";>John M. Wargo</a>
+
+ </div>
+ <div class="date">02 Feb 2018</div>
+ </header>
+ <section>
+ <div>
+ <p>Cordova developers have several ways to test and debug their
Cordova applications. For functional testing, developers use emulators,
simulators, and physical devices. Devices can be on-premises, or there are many
cloud offerings available as well. There's even great tools you can use to
debug your applications such as the web app debugging capabilities of Chrome
and Safari, as well as the excellent debugging capabilities of Microsoft's
Visual Studio Code extension for Apache Cordova.</p>
+
+<p>For debugging plugins, or debugging applications that utilize Cordova
plugins, things aren't that bad. For most plugins, I imagine that any
physical device has whatever's needed to work with a plugin, unless the
plugin requires some external hardware device or has other requirements that
aren't by every device. For several of the core Cordova plugins, the device
emulators and simulators expose capabilities that enable testers to simulate
things like the camera, accelerometer, compass, and other device-side
capabilities (although, surprisingly, early iOS simulators didn't support
camera simulation).</p>
+
+<p>When it comes to exercising all the capabilities of a plugin, especially
simulating error conditions so you can tell how the app responds, it gets
complicated. Developers often find themselves hacking away at plugin code,
either mocking up simulation scenarios, or manually changing the behavior of
the plugin during testing. In many cases, developers must manually force error
conditions in their plugins so they can validate error checking within their
app. I haven't written many Cordova plugins, but in the little work I have
done, I've wished that there was a better way. Well, it turns out that
there is.</p>
+
+<!--more-->
+
+<p>Many, many years ago, a small company named Tiny Hippos created the Ripple
Emulator, a browser-based emulator for many mobile devices. Ripple was
interesting in many ways, but for the scope of this article, one of the
interesting features was its implementation of emulators for many of the core
Cordova plugins. As you ran your Cordova application in one pane, a separate
pane opened with options to control many aspects of the simulated environment
as shown in the following figure.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-1.png" alt="Figure 1"></p>
+
+<p>Well, shortening a long story a bit, the folks at Research In Motion
(BlackBerry) purchased Tiny Hippos and maintained Ripple for a while before
finally contributing it to the Apache Foundation as an incubator project. Many
companies got involved, including Adobe, Microsoft, and others, but the project
never really took off, or ever became a stable product. It never actually made
it out of beta.</p>
+
+<p>Anyway, fast forward to today and you'll find that Microsoft took the
Ripple project and rebuilt it. We kept some of the original code (some of the
plugin simulation panels and supporting utility functions), rewrote some parts,
created some new code, then released it as an open source project called
Cordova Simulate (<a
href="https://github.com/Microsoft/cordova-simulate";>https://github.com/Microsoft/cordova-simulate</a>).
We chose this approach, rather than investing in Ripple, because:</p>
+
+<ul>
+<li>We had regular reports of issues with Ripple starting and Visual Studio
not being able to connect to it successfully, so we wanted a simpler
architecture for rendering the Cordova web app (a separate browser window that
just hosted the app, and nothing else).</li>
+<li>Debugging Ripple was a challenge since you were effectively debugging both
the app and Ripple itself (you had to drill down into the Ripple UI's HTML
to find the hosted Cordova web app, and Ripple's JavaScript code could
easily be a part of your stack when debugging).</li>
+<li>Since Ripple and the Cordova web app render in the same browser window, if
the Cordova web app froze for any reason, Ripple also froze (or, in less severe
cases, the Ripple UI could look unresponsive when the Cordova web app is
busy).</li>
+</ul>
+
+<p>Cordova Simulate solves these issues:</p>
+
+<ul>
+<li>The app window doesn't also host the simulation UI - just the app (and
a small bit of code to enable communication with the simulation UI). This
solves the first two problems identified above.</li>
+<li>The simulation UI renders in a separate window, and all communication is
asynchronous, so an unresponsive app won't interfere with the simulation
UI. This solves the third problem.</li>
+</ul>
+
+<p>Another driving purpose for Cordova Simulate was that we wanted to make it
extensible; allowing plugins to define their own simulation functionality (as
you'll soon learn about).</p>
+
+<p>To my previous point about Ripple never making it out of beta, not only is
Cordova Simulate a complete, robust, and released solution, it's even part
of several Microsoft offerings (both commercial and open source). Its bundled
into Visual Studio Tools for Apache Cordova (TACO - <a
href="http://taco.visualstudio.com/";>http://taco.visualstudio.com/</a>) in
Visual Studio 2017. It's also included as part of the Apache Cordova
extension for Visual Studio Code (<a
href="https://github.com/Microsoft/vscode-cordova";>https://github.com/Microsoft/vscode-cordova</a>).
</p>
+
+<p>Why is this important to you? Well, let me explain...</p>
+
+<p>With Cordova Simulate, you now have access to a complete solution for
testing your apps against simulated versions of the core Cordova plugins. This
eliminates the need to hack up your code to simulate plugin responses as
Cordova Simulate takes care of that for you.</p>
+
+<p><strong>Note:</strong> If you just read the last paragraph, and said to
yourself "so what?" just hang on for a little while longer.</p>
+
+<p>The most important benefit for you is that you can add support for Cordova
Simulate to each of your custom plugins as well. Then, when you're
exercising your plugins during plugin development, or when your customers are
using your plugins, you have a standard way to simulate the capabilities of
your plugin (including error scenarios). When third-party providers add support
for Cordova Simulate to their plugins, suddenly developers can accurately test
each aspect of their application using a variety of plugins.</p>
+
+<p>Let me show you how to install and use Cordova Simulate, then I'll show
you how to add support for Cordova Simulate to your custom plugins. If
you're using someone else's plugin, and they don't have support for
Cordova Simulate in the plugin, add it yourself and submit a pull request,
it's not that hard.</p>
+
+<h2>Installing Cordova Simulate</h2>
+
+<p>As I mentioned before, Visual Studio Tools for Apache Cordova and the
Cordova extension for Visual Studio Code both include Cordova Simulate, so
there's no extra installation instructions to follow - just install the
tools, and you'll have what you need.</p>
+
+<p>You can also invoke Cordova Simulate from the command line, or from third
party IDEs. To install Cordova Simulate for those scenarios, open a terminal
window, and execute the following command:</p>
+<div class="highlight"><pre><code class="language-" data-lang="">npm install
-g cordova-simulate
+</code></pre></div>
+<p>That's it, that's all there is to it. When the process completes,
you'll now have a <code>simulate</code> command at your disposal to launch
Cordova Simulate.</p>
+
+<h2>Launching Cordova Simulate</h2>
+
+<p>The following sections describe how to launch Cordova Simulate in different
ways.</p>
+
+<h3>Visual Studio</h3>
+
+<p>If you're running an app in Visual Studio & TACO, just choose the
<strong>Simulate in Browser</strong> option, and the app launches Cordova
Simulate. Cordova Simulate will open the Chrome browser and run the web
application part of your Cordova app. Cordova Simulate will also open a
simulator control window in Visual Studio (using Internet Explorer, no surprise
there). You'll interact with the app in the Chrome window and simulate
methods and properties in the plugins using the simulator control window.
I'll show you how in a minute.</p>
+
+<h3>Visual Studio Code</h3>
+
+<p>If you're using Visual Studio Code, go to the <strong>Debug</strong>
tab, enable <strong>Cordova debugging</strong>, then execute either the
<strong>Simulate Android in browser</strong> or <strong>Simulate iOS in
browser</strong> options. Cordova Simulate will open the Chrome browser and
execute the web application part of your Cordova app. Cordova Simulate will
also open a simulator control window inside Visual Studio Code. You'll
interact with the app in the Chrome window and simulate methods and properties
in the plugins using the simulator control window. I'll show you how in a
minute.</p>
+
+<h3>Command-line</h3>
+
+<p>To launch Cordova Simulate from the command-line, open a terminal window,
navigate to a Cordova project folder, and execute the following command:</p>
+<div class="highlight"><pre><code class="language-" data-lang="">simulate
\[platform\]
+</code></pre></div>
+<p>Platform refers to one of the supported target platforms (for example:
<code>android</code>, <code>ios</code>, or <code>browser</code>). For example,
to simulate the Android version of your Cordova application, you would use the
following:</p>
+<div class="highlight"><pre><code class="language-" data-lang="">simulate
android
+</code></pre></div>
+<p>Cordova Simulate will open the Chrome browser with two tabs, one running
the Cordova app web app, and the other displaying the simulator control window
shown in the following figure.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-2.png" alt="Figure 2"></p>
+
+<p>By default, Cordova Simulate loads a default set of plugin simulators:</p>
+
+<ul>
+<li>Since HTML has native support for geolocation, Cordova Simulate
automatically loads the Geolocation simulator pane.</li>
+<li>The event simulator pane loads automatically to enable developers to
trigger Cordova and device events as needed</li>
+<li>Persisted Exec Calls pane enables basic simulator support for third-party
plugins that don't include support for Cordova Simulate.</li>
+<li>The Device simulator loads automatically to enable you to change the
target device used for rendering the web app.</li>
+</ul>
+
+<p>If I'd added other Cordova core plugins to my project, Cordova Simulate
would load simulators for each, if available.</p>
+
+<p>At this point, you can interact with your app as needed, and switch to the
simulator control window to adjust plugin properties and method call results.
For example, if your Cordova app used the Geolocation plugin to track the
device's location, changing any of the values in the Geolocation simulator
pane would cause the app's next call to
<code>navigator.geolocation.getCurrentPosition</code> to receive the updated
value you entered into the pane.</p>
+
+<h2>Adding Cordova Simulate Support to Your Plugins</h2>
+
+<p>Alright, it's time to show you how to add Cordova Simulate support to
your own plugins. First, you must add a <code>simulation</code> folder to your
plugin's <code>src</code> folder (so <code>src/simulation/</code>). Inside
that folder, you'll create one or more of the following files based on the
needs of your plugin:</p>
+
+<ul>
+<li><code>app-host-clobbers.js</code></li>
+<li><code>app-host-handlers.js</code></li>
+<li><code>app-host.js</code></li>
+<li><code>sim-host-dialogs.html</code></li>
+<li><code>sim-host-handlers.js</code></li>
+<li><code>sim-host-panels.html</code></li>
+<li><code>sim-host.js</code></li>
+</ul>
+
+<p>For my simple example, I'm only going to need three files, but refer to
the Cordova Simulate documentation at <a
href="https://github.com/Microsoft/cordova-simulate";>https://github.com/Microsoft/cordova-simulate</a>
for details about each of these files.</p>
+
+<p>The plugin I used for my example is a simple Carrier plugin I created many
years ago for one of my Cordova books: <a
href="https://www.npmjs.com/package/johnwargo-cordova-plugin-carrier";>https://www.npmjs.com/package/johnwargo-cordova-plugin-carrier</a>.
It exposes two methods:</p>
+
+<ul>
+<li><code>getCarrierName</code>: An asynchronous method that retrieves the
current carrier for the device running the application.</li>
+<li><code>getCountryCode</code>: An asynchronous method that retrieves the
country code for the device running the application</li>
+</ul>
+
+<p>When exercising this plugin, I'll need the ability to validate my
app's code against different carrier and country code values. To simulate
this, I'll need an HTML panel that offers multiple carrier and country code
choices. For this, I created a <code>sim-host.panels.html</code> file in the
plugin project's <code>src/simulation/</code> folder. The file creates a
simple panel with two drop-down lists containing some country and carrier
values:</p>
+<div class="highlight"><pre><code class="language-"
data-lang=""><cordova-panel id="johnwargo-cordova-plugin-carrier"
caption="Carrier"
+ spoken-text="Carrier">
+ <cordova-panel-row>
+ Select carrier and country code options from the drop-down lists below.
+ </cordova-panel-row>
+ <cordova-panel-row>
+ <cordova-label label="Carrier Name" spoken="carrier
name"></cordova-label>
+ <cordova-combo spoken-text="Simulated value for wireless carrier"
+ id="carrier-select" style="width:auto; min-width:0;
display:inline;">
+ <option value="AT&T"
selected="selected">AT&T</option>
+ <option value="Sprint">Sprint</option>
+ <option value="T-Mobile">T-Mobile</option>
+ <option value="US Cellular">US Cellular</option>
+ <option value="Verizon">Verizon</option>
+ </cordova-combo>
+ </cordova-panel-row>
+ <cordova-panel-row>
+ <cordova-label label="Country Code" spoken="country
code"></cordova-label>
+ <cordova-combo spoken-text="Simulated value for country code"
+ id="country-code-select" style="width:auto; min-width:0;
display:inline;">
+ <option value="CA">Canada</option>
+ <option value="MX">Mexico</option>
+ <option value="US" selected="selected">United
States</option>
+ </cordova-combo>
+ </cordova-panel-row>
+ <cordova-panel-row>
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+ </cordova-panel-row>
+ <cordova-checkbox id="is-error" spoken="">Error
condition</cordova-checkbox>
+</cordova-panel>
+</code></pre></div>
+<p>As you can see from the code, the panel makes use of special HTML element
types supported by Cordova Simulate. The simulator code for most of the core
Cordova plugins is included with the Cordova Simulate Github repository, so you
can find examples there of the available UI elements in use.</p>
+
+<p>Next, I added a <code>sim-host.js</code> file to the folder. This file
isn't necessary, but it provides an opportunity to initialize the simulated
plugin, and I use it to update the console whenever the user makes a change in
the simulation panel. Not critically important, but useful as I sorted out what
was happening as I built the simulation.</p>
+<div class="highlight"><pre><code class="language-"
data-lang="">module.exports = {
+ initialize: function() {
+ //Get access to the carrier selection drop-down
+ var carrierSel = document.getElementById('carrier-select');
+ //Add a change event listener to the field
+ carrierSel.addEventListener('change', carrierChange);
+ //Get access to the country code selection drop-down
+ var ccSel = document.getElementById('country-code-select');
+ //Add a change event listener to the field
+ ccSel.addEventListener('change', ccChange);
+
+ function carrierChange() {
+ console.log("Carrier selection changed to " + this.value);
+ }
+
+ function ccChange() {
+ console.log("Country code selection changed to " + this.value);
+ }
+ }
+};
+</code></pre></div>
+<p>If you study the source code for the simulator capabilities in the core
Cordova plugins, you'll see that many of them use change events like the
ones just shown in the code to update properties for objects exposed by the
plugins. As developers change values in the simulator panel, the change events
register the change and updates a local object. Then, when a Cordova
application accesses one of those properties, the code returns the value from
the local object.</p>
+
+<p>Finally, I added a <code>sim-host-handlers.js</code> file to the project.
The code in this file overrides the <code>cordova.exec</code> calls from the
plugin in the simulated environment. Here, I export the native methods
supported by the plugin and pull the selected values from the simulator panel
and return them to the calling application.</p>
+<div class="highlight"><pre><code class="language-"
data-lang="">module.exports = function(messages) {
+ return {
+ carrier: {
+ getCarrierName: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCarrierName invoked");
+ //Get access to the carrier selection drop-down
+ var carrierSel = document.getElementById('carrier-select');
+ //Pull the value from the selected item
+ var selValue =
carrierSel.options[carrierSel.selectedIndex].value;
+ console.log('Simulating carrier: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ },
+ getCountryCode: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCountryCode invoked");
+ //Get access to the country code selection drop-down
+ var ccSel = document.getElementById('country-code-select');
+ //Pull the value from the selected item
+ var selValue = ccSel.options[ccSel.selectedIndex].value;
+ console.log('Simulating country code: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ }
+ };
+};
+</code></pre></div>
+<p>This is a very simple example of what you can do, be sure to check out the
source code for the simulator capabilities included with core Cordova plugins
for more sophisticated examples.</p>
+
+<p>Now, when you create a Cordova application that uses this plugin, then
execute Cordova Simulate, you'll see the following panel exposed on the
Cordova Simulate Simulator Control window:</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-3.png" alt="Figure 3"></p>
+
+<p>Make the appropriate changes to the panel, then call the associated APIs
from the Cordova application to see the selected results.</p>
+
+<p>If you think about what we've done so far, we've only addressed
success scenarios - changing the behavior of the plugin in the simulated
environment so we can test the app with different API results. Most plugins
also report error conditions, and in order to properly exercise the plugin or
an app using the plugin, you must be able to simulate error conditions as well.
Let me show you how to do that.</p>
+
+<p>First, I added a new row to the <code>sim-host.panels.html</code> file:</p>
+<div class="highlight"><pre><code class="language-"
data-lang=""><cordova-panel-row>
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+</cordova-panel-row>
+<cordova-checkbox id="is-error" spoken="">Error
condition</cordova-checkbox>
+</code></pre></div>
+<p>This adds an Error checkbox to the panel, enabling developers to return an
error from each plugin API call. The updated <code>sim-host.panels.html</code>
file looks like this:</p>
+<div class="highlight"><pre><code class="language-"
data-lang=""><cordova-panel id="johnwargo-cordova-plugin-carrier"
caption="Carrier"
+ spoken-text="Carrier">
+ <cordova-panel-row>
+ Select carrier and country code options from the drop-down lists below.
+ </cordova-panel-row>
+ <cordova-panel-row>
+ <cordova-label label="Carrier Name" spoken="carrier
name"></cordova-label>
+ <cordova-combo spoken-text="Simulated value for wireless carrier"
+ id="carrier-select" style="width:auto; min-width:0;
display:inline;">
+ <option value="AT&T"
selected="selected">AT&T</option>
+ <option value="Sprint">Sprint</option>
+ <option value="T-Mobile">T-Mobile</option>
+ <option value="US Cellular">US Cellular</option>
+ <option value="Verizon">Verizon</option>
+ </cordova-combo>
+ </cordova-panel-row>
+ <cordova-panel-row>
+ <cordova-label label="Country Code" spoken="country
code"></cordova-label>
+ <cordova-combo spoken-text="Simulated value for country code"
+ id="country-code-select" style="width:auto; min-width:0;
display:inline;">
+ <option value="CA">Canada</option>
+ <option value="MX">Mexico</option>
+ <option value="US" selected="selected">United
States</option>
+ </cordova-combo>
+ </cordova-panel-row>
+ <cordova-panel-row>
+ Enable the error checkbox to execute the error callback instead of the
success callback on plugin API calls.
+ </cordova-panel-row>
+ <cordova-checkbox id="is-error" spoken="">Error
condition</cordova-checkbox>
+</cordova-panel>
+</code></pre></div>
+<p>Now, in the <code>sim-host-handlers.js</code> file, I added a check for the
checkbox status in each of the methods exposed in the file. For my plugin, with
the checkbox checked, the method calls the error callback function returning a
dummy JSON object containing a simple error message and code. For your plugins,
you'll likely want to expand this so you can simulate different error
conditions.</p>
+<div class="highlight"><pre><code class="language-"
data-lang="">module.exports = function(messages) {
+ return {
+ carrier: {
+ getCarrierName: function(successCallback, errorCallback) {
+ console.log("Cordova-Simulate: getCarrierName invoked");
+ if (document.getElementById('is-error').checked) {
+ console.error("Error condition enabled");
+ errorCallback({ code: 1, msg: "Simulated error condition"
});
+ } else {
+ //Get access to the carrier selection drop-down
+ var carrierSel = document.getElementById('carrier-select');
+ //Pull the value from the selected item
+ var selValue =
carrierSel.options[carrierSel.selectedIndex].value;
+ console.log('Simulating carrier: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ },
+ getCountryCode: function(successCallback, errorCallback) {
+ if (document.getElementById('is-error').checked) {
+ console.error("Error condition enabled");
+ errorCallback({ code: 2, msg: "Simulated error condition"
});
+ } else {
+ console.log("Cordova-Simulate: getCountryCode invoked");
+ //Get access to the country code selection drop-down
+ var ccSel = document.getElementById('country-code-select');
+ //Pull the value from the selected item
+ var selValue = ccSel.options[ccSel.selectedIndex].value;
+ console.log('Simulating country code: ' + selValue);
+ //And return it to the calling method
+ successCallback(selValue);
+ }
+ }
+ }
+ };
+};
+</code></pre></div>
+<p>Now, when I execute Cordova simulate I'll see the slightly different
panel shown below.</p>
+
+<p><img src="/static/img/blog/2018/cordova-simulate-4.png" alt="Figure 4"></p>
+
+<p>That's it, that's all there is to enable simulation in your own
plugins. As you can hopefully see, Cordova Simulate gives developers (plugin
developers and developers who use those developer's plugins in their
applications) an easier way to exercise the plugin and test applications using
the plugin. </p>
+
+<p>Cordova Simulate is an open source project from Microsoft, but we'd
love to have your help enhancing it and fixing issues as they arise. Please
follow the project on Github and take a look at how you can help enhance this
project.</p>
+
+ </div>
+ </section>
+ <footer>
+ <div class="row">
+ <div class="col-sm-6">
+
+ <a
href="/news/2018/01/29/plugins-release.html">Previous</a>
+ <br>
+ <br>
+ <a class="title"
href="/news/2018/01/29/plugins-release.html">Plugins Release</a>
+ <div class="date"> 29 Jan 2018 - By Suraj Pindoria </div>
+ <p class="content">
+ The following plugins were updated today:
[email protected] [email protected]
[email protected] [email protected]
[email protected] You...
+ </p>
+
+ </div>
+ <div class="col-sm-6">
+
+ </div>
+ </div>
+ </footer>
+ <div class="disqus">
+ <div id="disqus_thread"></div>
+<script type="text/javascript">
+ /* * * CONFIGURATION VARIABLES * * */
+ var disqus_shortname = 'cordovablogs';
+
+ /* * * DON'T EDIT BELOW THIS LINE * * */
+ (function() {
+ var dsq = document.createElement('script'); dsq.type =
'text/javascript'; dsq.async = true;
+ dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
+ (document.getElementsByTagName('head')[0] ||
document.getElementsByTagName('body')[0]).appendChild(dsq);
+ })();
+</script>
+<noscript>Please enable JavaScript to view the <a
href="https://disqus.com/?ref_noscript"; rel="nofollow">comments powered by
Disqus.</a></noscript>
+
+ </div>
+</div>
+
+</div>
+
+</div>
+
+<div class="blue-divider"></div>
+<footer>
+ <div class="container">
+ <div class="row">
+ <div class="col-sm-9">
+ <h1>More Resources</h1>
+ <div class="row">
+ <div class="col-sm-4">
+ <h2>General</h2>
+ <ul class="nav">
+ <li>
+ <a target="_blank"
href="https://projects.apache.org/project.html?cordova";>Apache Project Page</a>
+ </li>
+ <li>
+ <a
href="http://www.apache.org/dyn/closer.cgi/cordova";>Source Distribution</a>
+ </li>
+ <li>
+ <a target="_blank"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a>
+ </li>
+ <li>
+ <a href="/artwork">Artwork</a>
+ </li>
+ </ul>
+ </div>
+ <div class="col-sm-4">
+ <h2>Development</h2>
+ <ul class="nav">
+ <li><a target="_blank"
href="https://github.com/apache?utf8=%E2%9C%93&q=cordova-";>Source
Code</a></li>
+ <li><a target="_blank"
href="https://issues.apache.org/jira/browse/CB/";>Issue Tracker</a></li>
+ <li><a target="_blank"
href="http://stackoverflow.com/questions/tagged/cordova";>Stack Overflow</a></li>
+ <li><a href="/contact">Mailing List</a></li>
+ <li><a href="/contribute/nightly_builds.html">Nightly
builds</a></li>
+ </ul>
+ </div>
+ <div class="col-sm-4">
+ <h2>Apache Software Foundation</h2>
+ <ul class="nav">
+ <li>
+ <a target="_blank" href="http://www.apache.org/";>About
ASF</a>
+ </li>
+ <li>
+ <a target="_blank"
href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a>
+ </li>
+ <li>
+ <a target="_blank"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a>
+ </li>
+ <li>
+ <a target="_blank"
href="http://www.apache.org/security/";>Security</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ <div class="col-sm-3">
+ <h1>Contribute</h1>
+ <p style="padding-top:20px"><strong>Help Cordova move
forward!</strong></p>
+ <p>Report bugs, improve the docs, or contribute to the code.</p>
+ <a href="/contribute" class="btn btn-lg btn-primary">
+ Learn More
+ </a>
+ <p style="padding-top:20px"> <a
href="https://twitter.com/apachecordova"; class="twitter-follow-button"
data-show-count="false">Follow @apachecordova</a></p>
+ <script async defer
src="https://slack-cordova-io.herokuapp.com/slackin.js";></script>
+ </div>
+</div>
+<p class="copyright_text">
+ Copyright © 2012, 2013, 2015 The Apache Software Foundation, Licensed
under the <a target="_blank"
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>
+ Apache and the Apache feather logos are <a target="_blank"
href="http://www.apache.org/foundation/marks/list/";>trademarks</a> of The
Apache Software Foundation.
+ <br/>
+ "Raleway" font used under license. For details see the <a
href="/attributions/">attributions page</a>.
+</p>
+
+ </div>
+</footer>
+
+
+ <script defer type="text/javascript" src="/static/js/index.js"></script>
+ <script defer type="text/javascript" src="/static/js/twitter.js"></script>
+
+
+
+
+
+
+
+
+<script type="text/javascript"
src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js";></script>
+<script type="text/javascript">
+ docsearch({
+ apiKey: '0a916ab198bd93d031aa70611271e42e',
+ indexName: 'cordova',
+ inputSelector: '#header-search-field',
+ algoliaOptions: { 'facetFilters': ["version: 7.x", "language: en"] }
+ });
+</script>
+
+</body>
+</html>
Modified: cordova/site/public/news/2018/01/29/plugins-release.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/news/2018/01/29/plugins-release.html?rev=1822991&r1=1822990&r2=1822991&view=diff
==============================================================================
--- cordova/site/public/news/2018/01/29/plugins-release.html (original)
+++ cordova/site/public/news/2018/01/29/plugins-release.html Fri Feb 2
17:37:32 2018
@@ -207,6 +207,26 @@ cordova plugin add cordova-plugin-camera
</div>
<div class="col-sm-6">
+ <a href="/howto/2018/02/02/cordova-simulate.html">Next</a>
+ <br>
+ <br>
+ <a class="title"
href="/howto/2018/02/02/cordova-simulate.html">A Better Way to Exercise Cordova
Plugins</a>
+ <div class="date"> 02 Feb 2018 - By John M. Wargo </div>
+ <p class="content">
+ <!--
+ NOTE:
+ the markdownify filter is used here
+ because posts are rendered in sequence;
+ that is, the next post's content isn't
+ yet rendered at the time that this post
+ is being rendered, so page.next.excerpt
+ is still in Markdown and not HTML
+
+ Reference:
https://github.com/jekyll/jekyll/issues/2860
+ -->
+ Cordova developers have several ways to test and debug
their Cordova applications....
+ </p>
+
</div>
</div>
</footer>
Modified: cordova/site/public/sitemap.xml
URL:
http://svn.apache.org/viewvc/cordova/site/public/sitemap.xml?rev=1822991&r1=1822990&r2=1822991&view=diff
==============================================================================
--- cordova/site/public/sitemap.xml (original)
+++ cordova/site/public/sitemap.xml Fri Feb 2 17:37:32 2018
@@ -4,6 +4,11 @@
<!-- posts -->
<url>
+
<loc>https://cordova.apache.org/howto/2018/02/02/cordova-simulate.html</loc>
+</url>
+
+
+<url>
<loc>https://cordova.apache.org/news/2018/01/29/plugins-release.html</loc>
</url>
Added: cordova/site/public/static/img/blog/2018/cordova-simulate-1.png
URL:
http://svn.apache.org/viewvc/cordova/site/public/static/img/blog/2018/cordova-simulate-1.png?rev=1822991&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cordova/site/public/static/img/blog/2018/cordova-simulate-1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: cordova/site/public/static/img/blog/2018/cordova-simulate-2.png
URL:
http://svn.apache.org/viewvc/cordova/site/public/static/img/blog/2018/cordova-simulate-2.png?rev=1822991&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cordova/site/public/static/img/blog/2018/cordova-simulate-2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: cordova/site/public/static/img/blog/2018/cordova-simulate-3.png
URL:
http://svn.apache.org/viewvc/cordova/site/public/static/img/blog/2018/cordova-simulate-3.png?rev=1822991&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cordova/site/public/static/img/blog/2018/cordova-simulate-3.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: cordova/site/public/static/img/blog/2018/cordova-simulate-4.png
URL:
http://svn.apache.org/viewvc/cordova/site/public/static/img/blog/2018/cordova-simulate-4.png?rev=1822991&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cordova/site/public/static/img/blog/2018/cordova-simulate-4.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: cordova/site/public/static/js/index.js
URL:
http://svn.apache.org/viewvc/cordova/site/public/static/js/index.js?rev=1822991&r1=1822990&r2=1822991&view=diff
==============================================================================
--- cordova/site/public/static/js/index.js (original)
+++ cordova/site/public/static/js/index.js Fri Feb 2 17:37:32 2018
@@ -77,6 +77,7 @@ function checkNotification() {
var dates = [];
if (lastVisit != "") {
+ dates.push('Fri, 02 Feb 2018 00:00:00 +0000');
dates.push('Mon, 29 Jan 2018 00:00:00 +0000');
dates.push('Sat, 30 Dec 2017 00:00:00 +0000');
dates.push('Wed, 20 Dec 2017 00:00:00 +0000');
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
