Merge branch 'master' of https://github.com/Microsoft/cordova-docs

Readme.md

@@ -16,6 +16,7 @@ This repository contains a set of documents and tutorials for the **Visual Studi
 	1. [Getting Started with Cordova & TFS 2013](./tutorial-team-build/TFS2013.md)
 	1. [Getting Started with Cordova & Jenkins CI](./tutorial-team-build/Jenkins.md)
 1. [Package & Publish your Cordova Applications](./tutorial-package-publish)
+1. [Using TypeScript with your Cordova projects](./getting-started/tutorial-typescript.md)
 1. [Build and Simulate iOS in the Cloud](http://go.microsoft.com/fwlink/?LinkID=618476) (MSDN)
 1. [Build a Cordova app for iOS using Parallels](http://go.microsoft.com/fwlink/?LinkID=618477) (MSDN)
 1. [Run the Android Emulator on OSX when using Windows in Parallels](http://go.microsoft.com/fwlink/?LinkID=618478) (MSDN)
@@ -26,6 +27,8 @@ This repository contains a set of documents and tutorials for the **Visual Studi
 1. [General](./tips-and-workarounds/general)
 1. [Android](./tips-and-workarounds/android)
 1. [iOS and OSX](./tips-and-workarounds/ios)
+1. [Performance](./tips-and-workarounds/performance)
+
 
 <a name="knownissues"></a>
 ## Known Issues

getting-started/tutorial-typescript.md

@@ -0,0 +1,93 @@
+#Using TypeScript in Cordova projects
+[TypeScript](http://www.typescriptlang.org) is a programming language that is a superset of JavaScript - offering classes, modules, and interfaces. You can use these features while developing your Cordova app and TypeScript will compile into simple JavaScript that will be deployed as part of your app.
+
+The Visual Studio Tools for Apache Cordova provide templates to help you get started with TypeScript and the TypeScript editor in Visual Studio. In this article, we'll answer the following questions:
+
+- [How do I start a TypeScript application?](#getStarted)
+- [Can I add TypeScript to my existing JavaScript application?](#addToExisting)
+- [How do I customize the TypeScript compiler settings?](#configTypeScript)
+- [I need to build my project outside of Visual Studio, how do I do that?](#buildOutsideVS)
+- [Where can I learn more about using TypeScript with Cordova?](#learnMore)
+
+**Note** You need to know that for the current version of the Tools for Apache Cordova, you can only work with TypeScript files in the /scripts folder of a project. Ideally, you're free to arrange files into any folder. This is a known issue being worked on for a later update.
+
+##<a name="getStarted"></a>How do I start a TypeScript application?
+Visual Studio provides a blank app template using TypeScript. To use it:
+
+1. In Visual Studio, use the File > New > Project... menu.
+2. Select the Templates > TypeScript > Apache Cordova Apps category and click on the Blank App (Apache Cordova) template.![New TypeScript project template](media/ts-project-template.PNG)
+3.  Enter a name and file location for your project, then click OK.
+
+Here's what the new project looks like:
+
+![Solution folder | Project Folder | Folders: merges, res, scripts, www](media/ts-file-structure.PNG)
+
+In the scripts folder you see typings, index.ts, and tsconfig.json files. These files are used by TypeScript:
+* typings - a collection of [typing definition files](http://www.typescriptlang.org/Handbook#writing-dts-files) that define the APIs for common Cordova plugins.
+* index.ts - a TypeScript file. In this project, index.ts is the default file.
+* tsconfig.json - a configuration file that you can use to customize the TypeScript build options. [Learn more about tsconfig.json](https://github.com/microsoft/typescript/wiki/tsconfig.json) on the TypeScript project site.
+
+If you open the index.ts file, you'll see the TypeScript source with the default behavior for this application.
+
+```TypeScript
+module BlankCordovaApp {
+    "use strict";
+
+    export module Application {
+        export function initialize() {
+            document.addEventListener('deviceready', onDeviceReady, false);
+        }
+
+        function onDeviceReady() {
+            // Handle the Cordova pause and resume events
+            document.addEventListener('pause', onPause, false);
+            document.addEventListener('resume', onResume, false);
+
+            // TODO: Cordova has been loaded. Perform any initialization that requires Cordova here.
+        }
+
+        function onPause() {
+            // TODO: This application has been suspended. Save application state here.
+        }
+
+        function onResume() {
+            // TODO: This application has been reactivated. Restore application state here.
+        }
+    }
+
+    window.onload = function () {
+        Application.initialize();
+    }
+}
+
+```
+This is the same source as the [JavaScript Blank App template](https://msdn.microsoft.com/en-us/library/dn757057(v=vs.140).aspx#Create), implemented in TypeScript. This code sets up Cordova event handlers for the application.
+
+When you build this project, the TypeScript source will be compiled into a JavaScript file named appBundle.js located in the www/scripts/ folder (this is configured in the tsconfig.json file mentioned earlier). By doing this, you reduce the size of your final packaged application, because the TypeScript files in the /scripts folder will not be included in the application package.
+
+**Note** For the current version of the Tools for Apache Cordova, you can only save TypeScript files in the /scripts folder. Ideally, you're free to arrange files into any folder. This is a known issue being worked on for a later update.
+
+##<a name="addToExisting"></a>Can I add TypeScript to my existing JavaScript application?
+TypeScript files can be added to any Cordova project using the TypeScript item template. You can find this template by right-clicking on your project and choosing the Add > New TypeScript File... menu.
+
+In the current release, if you want TypeScript files to compile by default you must place these files into a Scripts file at the top level of your project.
+
+##<a name="configTypeScript"></a>How do I customize the TypeScript compiler settings?
+To customize the compiler settings for TypeScript in your projects:
+
+1. Add a new tsconfig.json file to the /scripts folder at the top level of your project.
+2. Define your settings using the JSON schema documented on the [TypeScript project wiki](https://github.com/microsoft/typescript/wiki/tsconfig.json).
+
+As you write your tsconfig JSON, IntelliSense will offer suggestions to help make sure your file matches the expected schema.
+
+![Visual Studio IntelliSense with suggestions for the tsconfig schema](media/tsconfig-intellisense.png)
+
+##<a name="buildOutsideVS"></a>I need to build my project outside of Visual Studio, how do I do that?
+By default, Visual Studio is building TypeScript files for you using the MSBuild build system behind the scenes. If you want to build your project outside of Visual Studio (in a Terminal on Mac OS X, for example), then we recommend using a JavaScript task runner, such as [Gulp](http://www.gulpjs.com). To learn more, [see our Gulp tutorial](../tutorial-gulp/README.md).
+
+##<a name="learnMore"></a>Where can I learn more about using TypeScript with Cordova?
+Here are a few links to help you learn more about working with TypeScript:
+* [The TypeScript language website](http://www.typescriptlang.org)
+* [Configuring TypeScript compilation using tsconfig.json](https://github.com/microsoft/typescript/wiki/tsconfig.json)
+
+To learn more about using TypeScript with Cordova, see our [sample TODO app, using WinJS](https://github.com/Microsoft/cordova-samples/tree/master/todo-winjs).

tips-and-workarounds/performance/README.md

@@ -0,0 +1,77 @@
+# Cordova Performance Tips
+
+Cordova apps are web apps that run "inside" of native apps by using native "web view" UI components. There are therefore three major domains where performance can be affected in a Cordova app:
+
+- The web code, in JS, CSS, and HTML
+- The native code, in Objective-C/Swift, Java, or WinJS (Cordova plugin code)
+- The bridge between the native and web code (Cordova runtime code)
+
+Web App Domain
+==============
+
+There are *very many* things that can be optimized in a web app. The Internet contains a wealth of information on the topic. Optimizations highly relevant to Cordova apps are given below, but afterward we have a list of links for more in-depth reading.
+
+### Removing the 300ms Touch Delay
+
+There is a 300ms delay on some mobile browser platforms between a touch on the screen and its corresponding touch event being fired. For more responsive UI, this delay can be sidestepped. The `fastclick` library (available on [GitHub][fastclick]) conveniently implements this optimization.
+
+### Layout Updates: Fewer is Better
+
+HTML rendering engines recalculate a document layout when CSS rules or DOM element dimensions are changed. These recalculations are expensive, and minimising them improves performance. Editing HTML elements outside of the DOM (e.g. creating new `<div>`s using jQuery) does not cause layout recalculations. Therefore editing HTML in JavaScript and then inserting the edited HTML into the DOM results in fewer layout recalculations and leads to improved performance.
+
+### Images > CSS Gradients
+
+CSS Gradients take longer than static images to render on most HTML rendering engines. Using image gradient backgrounds in place of CSS gradients reduces frame render time.
+
+### Transitions > Setting Properties
+
+CSS3 transitions allow animation and transformation of HTML elements. They are implemented and optimized in most browsers, and usually perform better than "manual" animations (such as setting object `x` and `y` properties at defined intervals).
+
+The Mozilla Developer Network guide on CSS transitions can be found [here][mdn_transitions].
+
+### CSS Animation Loop > Custom Animation Loop
+
+Browser JavaScript APIs expose a function called `requestAnimationFrame`. This allows a callback to be attached to the *rendering engine's frame-rendering loop*, which is already optimized and timed appropriately for rendering. Using it (instead of a custom event loop) to perform any per-frame changes is more performant because the browser's internal rendering code is already heavily optimized.
+
+### External Links
+
+Below are some links for further reading on performance improvements in Cordova apps:
+
+- Christophe Coenraets' [PhoneGap Performance slides][coenraets]
+- Ryan Salva's [Cordova Performance presentation][salva]
+
+Native App Domain
+=================
+
+In a Cordova app, all code that will usually be written is in JS, CSS, and HTML. However, the source for native Cordova components (like the plugins and the runtime) is open, and it is within the power of an app developer to change it. Optimizing platform-specific code is outside the scope of this document, but many guides are available online for each platform supported by Cordova. They are as follows:
+
+- [Amazon FireOS] [perf_amazon_fireos]
+- [Android] [perf_android]
+- [BlackBerry 10] [perf_blackberry]
+- [iOS] [perf_ios]
+- [Tizen][perf_tizen]
+- [WinJS] [perf_winjs]
+- Browsers: [Chrome][perf_chrome], [Firefox][perf_firefox], [Safari][perf_safari], [Opera][perf_opera]
+
+Web-to-Native Bridge
+====================
+
+Between the web code and native code is the Cordova runtime JavaScript and native code, which is also freely available and can be modified by any developer through the same process as is used to modify plugins. All Cordova repositories are available on GitHub under the [Apache organization][cordova_repos], prefixed with the string `cordova-`.
+
+[perf_amazon_fireos]: https://developer.amazon.com/appsandservices/community/post/TxSKXI5UIOVFFU/Build-Higher-Performance-Cordova-Based-Fire-OS-Apps-by-Implementing-Amazon-Web-V
+[perf_android]:       http://developer.android.com/training/articles/perf-tips.html
+[perf_blackberry]:    https://developer.blackberry.com/native/documentation/best_practices/performance/performance.html
+[perf_tizen]:         https://developer.tizen.org/documentation/guides/web-application/w3chtml5supplementary-features/performance-and-optimization
+[perf_winjs]:         https://msdn.microsoft.com/en-us/magazine/dn574803.aspx
+[perf_ios]:           https://developer.apple.com/library/mac/documentation/Performance/Conceptual/PerformanceOverview/BasicTips/BasicTips.html
+
+[perf_chrome]:  http://addyosmani.com/blog/performance-optimisation-with-timeline-profiles/
+[perf_firefox]: https://developer.mozilla.org/en-US/docs/Mozilla/Performance
+[perf_opera]:   http://google.com
+[perf_safari]:  http://google.com
+
+[coenraets]:       http://coenraets.org/keypoint/phonegap-performance/#0
+[salva]:           https://channel9.msdn.com/Events/Build/2015/3-756
+[fastclick]:       https://github.com/ftlabs/fastclick
+[mdn_transitions]: https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Using_CSS_transitions
+[cordova_repos]:   https://github.com/apache/?utf8=%E2%9C%93&query=cordova-

tutorial-gulp/gulp-ci.md

@@ -1,7 +1,7 @@
 #<a name="ci"></a>Using Gulp to Build Cordova Projects
-**This tutorial is part of a series on [using Gulp with Tools for Apache Cordova projects](http://go.microsoft.com/fwlink/?LinkID=533767) in Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.**
+**This tutorial is part of a series on [using Gulp with Apache Cordova projects](http://go.microsoft.com/fwlink/?LinkID=533767) in Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.**
 
-[Gulp](http://go.microsoft.com/fwlink/?LinkID=533803) is an increasingly popular JavaScript based task runner with a large number of [useful plugins](http://go.microsoft.com/fwlink/?LinkID=533790) designed to automate common "tasks" for everything from compilation, to packaging, deployment, or simply copying files around. Both Gulp and the [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) are Node.js based which makes the two highly complementary technologies.
+[Gulp](http://go.microsoft.com/fwlink/?LinkID=533803) is an increasingly popular JavaScript based task runner with a large number of [useful plugins](http://go.microsoft.com/fwlink/?LinkID=533790) designed to automate common tasks for everything from compilation, to packaging, deployment, or simply copying files around. Both Gulp and the [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) are Node.js based which makes the two highly complementary technologies.
 
 Because it can run on Windows or OSX, Gulp can be extremely useful as a unified cross-platform build language for automating and testing your builds in a team / continuous integration (CI) environment such as Team Foundation Services 2015 or Visual Studio Online. You may also prefer to use a Gulp based workflow rather than using the Cordova CLI itself.
 
@@ -23,7 +23,7 @@ gulp.task("default", function (callback) {
 });
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Note that cordova-lib functions **are asynchronous** and so you need to include the Gulp callback function passed into your task as an argument to your last API call. 
+Note that cordova-lib functions **are asynchronous** and so you need to include the Gulp callback function passed into your task as an argument to your last API call.
 
 To see the example above in action you will need to install some additional npm packages. Create a simple [package.json](http://go.microsoft.com/fwlink/?LinkID=533781) file with a minimum of the following in it that is in the root of your Cordova project:
 
@@ -66,7 +66,7 @@ It is important to note that there are a number of additional considerations to
 ##The taco-team-build Node Module
 The [taco-team-build](http://go.microsoft.com/fwlink/?LinkID=533736) node module is designed to help alleviate [common problems](http://go.microsoft.com/fwlink/?LinkID=533743) when building Cordova projects from the command line particularly in a team or CI environment. It can be used with any number of build systems including Jake, Grunt, and Gulp or even a command line tool. Here we will focus on how to set it up and use it with Gulp. You can see documentation on the module's methods in [its Git repository](http://go.microsoft.com/fwlink/?LinkID=533736).
 
-The easiest way to get started is to simply place the contents of the **samples/gulp** folder in the repository in the root of your Cordova project. No other files in the repository are required. 
+The easiest way to get started is to simply place the contents of the **samples/gulp** folder in the repository in the root of your Cordova project. No other files in the repository are required.
 
 Otherwise you can follow these steps:
 
@@ -110,7 +110,7 @@ Underneath the covers, the script will do the following:
 
 1.  First, it check **taco.json** to see if a Cordova version is specified. If not, it assumes you want Cordova 5.1.1.
 
-2.  Next, it checks to see if this version of cordova-lib has already been installed at a location set in the **CORDOVA\_CACHE** environment variable. If no CORDOVA_CACHE environment variable is set, the cache location will default to %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX. You can also set this location programmatically using the module's configure method. 
+2.  Next, it checks to see if this version of cordova-lib has already been installed at a location set in the **CORDOVA\_CACHE** environment variable. If no CORDOVA_CACHE environment variable is set, the cache location will default to %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX. You can also set this location programmatically using the module's configure method.
 
 3.  If the correct version of cordova-lib is not present in the cache location, it download and installs it.
 
@@ -120,9 +120,9 @@ Underneath the covers, the script will do the following:
     3.  Builds the project
     4.  Packages the project
 
-Each method returns a promise so that you can chain the steps or run them concurrently. 
+Each method returns a promise so that you can chain the steps or run them concurrently.
 
-You may find it useful to create a script that will automatically build all of the platforms your project supports across OSX and Windows. This is extremely useful for team build scenarios where you want to be able to check in a single script that automates all of your build steps including TypeScript compilation. 
+You may find it useful to create a script that will automatically build all of the platforms your project supports across OSX and Windows. This is extremely useful for team build scenarios where you want to be able to check in a single script that automates all of your build steps including TypeScript compilation.
 
 Here is an enhanced script that provides you with this flexibility:
 
@@ -193,4 +193,4 @@ npm install --save-dev gulp-uglify
 * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova)
 * [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794)
 * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova)
-* [Email us your questions](mailto:/[email protected])
+* [Email us your questions](mailto:/[email protected])