Permalink
Browse files

Updated tutorials, started writing blogposts.

  • Loading branch information...
1 parent 187e1d7 commit e69c0724e0535b2d82cca9fa6b78feab97fc512a Mikael Kindborg committed Jan 9, 2013
@@ -0,0 +1,130 @@
+<h1>How To Extend JavaScript With Custom C++ Code - Opening Google Maps From A Hybrid App</h1>
+
+<!-- C:\md>perl Markdown.pl C:\MoSyncProjects\MoSyncApps\PlatformRequestDemo\Tutorial\PlatformRequestDemo.md > C:\MoSyncProjects\MoSyncApps\PlatformRequestDemo\Tutorial\PlatformRequestDemo.html -->
+
+<!--
+<style type="text/css">
+p>img {
+ width: 550px;
+}
+</style>
+-->
+
+<p>This tutorial shows how write a MoSync Hybrid App that invokes a small piece of C++ code to open web sites in a new window (activity). This is useful if you for example wish to open Google Maps from your application.</p>
+
+<p>The source code for this tutorial is available on <a href="https://github.com/divineprog/MoSyncApps/tree/master/PlatformRequestDemo">GitHub</a>.</p>
+
+<h2>Background</h2>
+
+<p>In a Hybrid App, there is a WebView widget that displays HTML content. This WebView is not a fully featured browser in terms of navigation support, cookies etc. When opening a link (e.g. by clicking on it) the target is opened in the same WebView. This can cause problems, for example if you wish to navigate back to the original page displayed in the WebView. Complex web sites may work less well in the embedded WebView widget compared to the full web browser on the device. </p>
+
+<p>The solution is to use a C++ level syscall called <a href="http://www.mosync.com/files/imports/doxygen/latest/html/maapi_8h.html#a155b042c55d95404035d081c08d40ebf">maPlatformRequest</a>. This opens a URL in a new Activity on Android, in a fully featured web browser. And the back button works to return to your app. To invoke this syscall from JavaScript, you use the JavaScript to C++ bridge available in the MoSync Wormhole API. This API allows you to call any C++ code in your application.</p>
+
+<p>Of course, the situation would be simpler if the functionality of maPlatformRequest would already be available in the Wormhole JavaScript API, but as it goes, it is not in there yet.</p>
+
+<p>Note that if you are using MoSync Reload, calling custom C++ code won't work. You need to build your app with the MoSync SDK for the C++ code to be built and included with your app.</p>
+
+<p>If you have not used the MoSync SDK previously, <a href="http://www.mosync.com/documentation/manualpages/getting-started-html5-and-javascript">read this tutorial to get started quickly</a>.</p>
+
+<h2>Demo application</h2>
+
+<p>The app PlatformRequestDemo has a very simple user interface with buttons that open locations on Google Maps.</p>
+
+<p>Screenshots from the app running in the iOS Simulator and on Android Nexus 7:</p>
+
+<p><img src="https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_iOS_1.png" alt="PlatformRequestDemo iOS 1" title="" />
+<img src="https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_iOS_2.png" alt="PlatformRequestDemo iOS 2" title="" />
+<img src="https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_Android_1.png" alt="PlatformRequestDemo Android 1" title="" />
+<img src="https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_Android_2.png" alt="PlatformRequestDemo Android 2" title="" /></p>
+
+<p>When you try out the app on Android, notice that going back from Google Maps to the app screen requires multiple back button presses (Somehow Google Maps puts in an extra navigation step). On plain web pages, you can go back directly with one press, unless you have navigated any links, in which case you need to press back the corresponding number of times. You can always go to your app again via the Home button. On iOS, you just press the Home key and then go into the app again when you wish to return to it (iOS does not have a back button). </p>
+
+<p>The source code is available on GitHub. The JavaScript layer of the app is in file <a href="https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/LocalFiles/index.html">index.html</a>. The C++ layer is in file <a href="https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/main.cpp">main.cpp</a>.</p>
+
+<h2>What maPlatformRequest does</h2>
+
+<p>The syscall maPlatformRequest is in the MoSync C API. It opens a URL in an external application. Typically the URL is a HTTP request, pointing to a web page. But it cal also be a telephone number, used for dialing that number.</p>
+
+<p>Here is an example of opening a web page:</p>
+
+<pre><code>maPlatformRequest("http://maps.google.com/");
+</code></pre>
+
+<p>And here is an example of dialing a number:</p>
+
+<pre><code>maPlatformRequest("tel:046850510300");
+</code></pre>
+
+<p>Note that if you wish to use this functionality, you must set the "Phone Calls" permission in the MoSync SDK (in the Eclipse IDE). This setting is found by right-click the project and select Properties/MoSync Project/Application Permissions.</p>
+
+<h2>Into the code</h2>
+
+<p>Time to dive into the code. We will start with JavaScript and file <a href="https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/LocalFiles/index.html">index.html</a>. Here are the functions that compose a Google Maps URL and make the call to C++:</p>
+
+<pre><code>/**
+ * Calls C++ to invoke syscall maPlatformRequest.
+ */
+function openMapOnLocation(lat, lon)
+{
+ var url = "https://maps.google.com/maps?z=15&amp;t=m&amp;q=loc:"
+ + lat + "+" + lon;
+ makePlatformRequest(url);
+}
+
+/**
+ * Calls C++ to invoke syscall maPlatformRequest.
+ */
+function makePlatformRequest(url)
+{
+ // Send message with request to C++.
+ mosync.bridge.send(["Custom", "PlatformRequest", url]);
+}
+</code></pre>
+
+<p>You can call the above functions in your code to open an external browser. For example:</p>
+
+<pre><code>openMapOnLocation(59.339416,18.058755)
+
+makePlatformRequest('http://google,com')
+</code></pre>
+
+<p>What happens when mosync.bridge.send is called with the first element of the parameter array being "Custom", is that the C++ layer is invoked, and the name given in the second element in the array is looked up in a C++ function table. If the function is found, it is called.</p>
+
+<p>Now let's move to the C++ layer and the file <a href="https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/main.cpp">main.cpp</a>. Here is the part of the code that defines the Moblet class of the application (the Moblet is the central object in a MoSync application):</p>
+
+<pre><code>class MyMoblet : public HybridMoblet
+{
+public:
+ /**
+ * Constructor.
+ */
+ MyMoblet()
+ {
+ // Show the start page.
+ showPage("index.html");
+
+ // Register function to handle messages from JavaScript.
+ addMessageFun(
+ "PlatformRequest",
+ (FunTable::MessageHandlerFun)&amp;MyMoblet::handlePlatformRequest);
+ }
+
+ /**
+ * Function that opens the requested URL.
+ */
+ void handlePlatformRequest(Wormhole::MessageStream&amp; message)
+ {
+ // Obtain URL parameter sent from JavaScript.
+ const char* url = message.getNext();
+
+ // Make the request to open the URL.
+ maPlatformRequest(url);
+ }
+};
+</code></pre>
+
+<p>To get a more in-depth explanation of how the JavaScript to C++ bridge works, I suggest you read the tutorials <a href="http://www.mosync.com/documentation/manualpages/how-communicate-between-javascript-and-c-mosync">Extending HTML5 Mobile Apps with C++</a> and <a href="http://www.mosync.com/documentation/manualpages/using-sql-hybrid-apps">Using SQL in Hybrid Apps</a>. </p>
+
+<h2>Wrapping up</h2>
+
+<p>HTML5 and libraries like PhoneGap brings great power to mobile apps, but there can be times when you encounter functionality that is missing. By making a Hybrid App, which combines JavaScript with native code, the missing functionality can be made available. In the case of the MoSync SDK, functionality not available in JavaScript can be implemented in C/C++, as illustrated by the PlatformRequestDemo application. This is a powerful capability that can significantly improve your apps.</p>
@@ -1,5 +1,5 @@
# How To Extend JavaScript With Custom C++ Code - Opening Google Maps From A Hybrid App
-<!-- C:\md>perl Markdown.pl C:\MoSyncProjects\MoSyncApps\PlatformRequestDemo\Tutorial\PlatformRequestDemo.md > output.txt -->
+<!-- C:\md>perl Markdown.pl C:\MoSyncProjects\MoSyncApps\PlatformRequestDemo\Tutorial\PlatformRequestDemo.md > C:\MoSyncProjects\MoSyncApps\PlatformRequestDemo\Tutorial\PlatformRequestDemo.html -->
<!--
<style type="text/css">
@@ -21,7 +21,7 @@ The solution is to use a C++ level syscall called [maPlatformRequest](http://www
Of course, the situation would be simpler if the functionality of maPlatformRequest would already be available in the Wormhole JavaScript API, but as it goes, it is not in there yet.
-Note that if you are using MoSync Reload, cvalling custom C++ code won't work. You need to build your app with the MoSync SDK for the C++ code to be built and included with your app.
+Note that if you are using MoSync Reload, calling custom C++ code won't work. You need to build your app with the MoSync SDK for the C++ code to be built and included with your app.
If you have not used the MoSync SDK previously, [read this tutorial to get started quickly](http://www.mosync.com/documentation/manualpages/getting-started-html5-and-javascript).
@@ -36,7 +36,7 @@ Screenshots from the app running in the iOS Simulator and on Android Nexus 7:
![PlatformRequestDemo Android 1](https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_Android_1.png)
![PlatformRequestDemo Android 2](https://raw.github.com/divineprog/MoSyncApps/master/PlatformRequestDemo/Tutorial/PlatformRequestDemo_Android_2.png)
-When you try out the app on Android, notice that going back from Google Maps to the app screen requires multiple back button presses (Somehow Google Maps puts in an extra navigaton step). On play web pages, you can go back directly with oen press, unless you have navigated to additional pages, in which case you need to press back a corresponding number of times. You can always go to your app again via the Home button. On iOS, you just press home and then go into the app again when you wish to return to ot (iOS does not have a back button).
+When you try out the app on Android, notice that going back from Google Maps to the app screen requires multiple back button presses (Somehow Google Maps puts in an extra navigation step). On plain web pages, you can go back directly with one press, unless you have navigated any links, in which case you need to press back the corresponding number of times. You can always go to your app again via the Home button. On iOS, you just press the Home key and then go into the app again when you wish to return to it (iOS does not have a back button).
The source code is available on GitHub. The JavaScript layer of the app is in file [index.html](https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/LocalFiles/index.html). The C++ layer is in file [main.cpp](https://github.com/divineprog/MoSyncApps/blob/master/PlatformRequestDemo/main.cpp).
@@ -46,11 +46,11 @@ The syscall maPlatformRequest is in the MoSync C API. It opens a URL in an exter
Here is an example of opening a web page:
- maPlatformRquest("http://maps.google.com/");
+ maPlatformRequest("http://maps.google.com/");
And here is an example of dialing a number:
- maPlatformRquest("tel:046850510300");
+ maPlatformRequest("tel:046850510300");
Note that if you wish to use this functionality, you must set the "Phone Calls" permission in the MoSync SDK (in the Eclipse IDE). This setting is found by right-click the project and select Properties/MoSync Project/Application Permissions.
@@ -121,4 +121,4 @@ To get a more in-depth explanation of how the JavaScript to C++ bridge works, I
## Wrapping up
-HTML5 and libralies like PhoneGap brings great power to mobile apps, but there can be times when you encounter functionality that is missing. By making a Hybrid App, which combines JavaScript with native code, the missing functionality can be made available. In the case of the MoSync SDK, functionality not available in JavaScript can be implemented in C/C++, as illustrated by the PlatformRequestDemo application. This is a powerful capability that can significantly improve your apps.
+HTML5 and libraries like PhoneGap brings great power to mobile apps, but there can be times when you encounter functionality that is missing. By making a Hybrid App, which combines JavaScript with native code, the missing functionality can be made available. In the case of the MoSync SDK, functionality not available in JavaScript can be implemented in C/C++, as illustrated by the PlatformRequestDemo application. This is a powerful capability that can significantly improve your apps.
Oops, something went wrong.

0 comments on commit e69c072

Please sign in to comment.