Step 1: Install PhoneGap
The PhoneGap Desktop application provides a drag and drop interface for creating PhoneGap applications. It's an alternative to using the PhoneGap CLI built for those who prefer a visual user interface over a command line interface approach.
NOTE: The getting started steps vary based on the initial PhoneGap tool you install here in step 1. For the rest of the steps be sure to choose either the Desktop or CLI tab at the top accordingly.
Select your operating system to continue:
Mac OS X Installation
- Download the latest Mac OS X Installer.
- Double-click the downloaded file to run the installer. You will initially be prompted with a license agreement to accept:
- Drag and drop the application into the Applications folder on your Mac as prompted:
- Next simply open the application and proceed to Step 2 where you will install the PhoneGap Developer App to your mobile device for previewing the apps you build.
Windows Installation
- Download the latest Windows Installer.
NOTE: If you're unable to run the Windows Installer for some reason, there's also a zip file available that can be used to install PhoneGap Desktop manually. Download the zip file for the latest releaseand follow the instructions in the README and INSTALL files within the downloaded zip.
- Double click the downloaded file to run the installer. You will be prompted with the PhoneGap Desktop Setup Wizard:
- Accept the license agreement:
- Select the desired destination for the application and click Next:
- Select the desired location for the shortcut and click Next:
- Click Install to begin the installation:
- Click Finish to close the Setup Wizard:
- Next simply open the application and proceed to next step below where you will install the PhoneGap Developer App to your mobile device for previewing the apps you build.
Step 2: Install Mobile App
The PhoneGap Developer App is a mobile app that runs on devices and allows you to preview and test the PhoneGap mobile apps you build across platforms without additional platform SDK setup. It automatically provides access to the PhoneGap core APIs providing instant access to the native device features without having to install any plugins or compile anything locally. It's meant to provide an easy way for developers to get started creating and testing their PhoneGap applications quickly with minimal setup.
Install PhoneGap Developer
- Locate the free PhoneGap Developer app from one of the following supported app marketplaces and install it to your mobile device:
- Once installed, tap the PhoneGap Developer app icon from your home screen to open it:
- Once installed, move on to the next step where you will create your first PhoneGap app using the tool you selected in step 1.NOTE: The platform SDKs mentioned above refer to the software development kits Apple, Google and Microsoft provide to build applications for their platforms (iOS, Android and Windows respectively). When you're ready to take your mobile application development further or decide you want to build for each platform locally yourself, you can find the specific instructions for each platform in the PhoneGap Platform Installation Guides.
Step 3: Create Your App
Now that you've installed PhoneGap Desktop and/or the PhoneGap CLI to your computer and the PhoneGap Developer App to your mobile devices, you're ready to create your first PhoneGap project. This project will be a PhoneGap mobile app with the ability to run on multiple devices and across operating systems in just a few simple steps.
Create a PhoneGap Project
- Click the plus sign and select Create new PhoneGap project as shown below:
- You will be prompted with the template list dialog as shown below, where you can choose to create an app based on a sample project.
Each template has a brief description below the name indicating what type of project will be created. To select a template, click on the radio button next to it. In the image below, the Hello World template is selected.
The first template option in the list is the default Hello World project. It's proven to be the quickest and easiest way to understand the basics of building a mobile PhoneGap app so let's start there.
- Ensure the radio button next to the Hello World template is selected.
- Click on the green Next button.
- You will be presented with a screen to enter information about your project. Choose the path on your local hard drive where you want to create the project, a designated name and an optional identifier. Once the information has been entered, click the green Create project button.Be aware that the ID field is also known as the package identifier for Android and the bundle identifier for iOS.
- You should now see a view like below, with your new project shown and marked with a left green border, a green play button next to it and a green bar at the bottom. You should also see a server address indicating it's running and the active project. Only one project will be active and running at any time.TIP: The server address shown for your project at the bottom in the green bar will be used in the next step so make note of it or keep it open.
Step 4: Preview Your App
You can use the PhoneGap Developer App paired with PhoneGap Desktop to immediately preview your app on a device without installing platform SDKs, registering devices, or compiling code.
PhoneGap Desktop starts a small web server to host your project and returns a server address you can then enter into the PhoneGap Developer app running on your mobile device or in your desktop browser. The project is served automatically upon project creation, but you can also manually start any project that's inactive by clicking the green play ( > ) button next to it.
Preview in a Desktop Browser
You can leverage your desktop browser to preview and test yours apps first to speed up your initial development process. For instance, if you're using a framework like Angular or React, there are tools available for specifically debugging those frameworks in the browser that can be quite helpful before moving over to a device. Recently PhoneGap began supporting the browser platform as a target automatically to help you test with the
deviceready event and Apache Cordova core plugins more easily in an environment you're already familiar with.
Refer to the PhoneGap Browser Support Reference guide for specific details.
Preview on a Device
Double check to ensure you're running your device and computer on the same network before continuing.
- In the previous step we created a project and ensured it was running by looking for the green play button to be highlighted and a green bar showing the server address it's running on at the bottom of the PhoneGap Desktop.
The screenshot is shown again below for reference. Locate the specific server address for your project before moving to the next step. - Go to your mobile device where the PhoneGap Developer App is running, enter the server address on the main screen and tap Connect.NOTE: Tap directly on the server address displayed in the terminal screen of the PhoneGap Developer app to change it to match yours. The value filled in by default is only a sample.You should see the connection occur followed by a success message as shown below. If you receive an error of any kind, ensure once again that you are connected to the same network on both your device and computer. You could also check the issue tracker and PhoneGap Google Groups list for further help.Once the PhoneGap Developer app connects, it will load and display your application as shown below:TIP: Gestures can be used while you're previewing your app. A 3 finger tap will return you to the main screen, a 4 finger tap will cause a refresh.
VIDEO EXAMPLE
Making Updates
- Now let's make an update to some code to see how easy it is to test a change. Using your favorite text editor, open up the index.html file located within the www folder of your project; for instance ~/appSample/www/index.htmlTIP: Some popular lightweight but powerful editors include Brackets, Sublime Text and Atom. If you're looking for more of an IDE with extensive features and plugins including code hinting and type-ahead, check out WebStorm by JetBrains
- Choose an update to make. Let's start by changing the PHONEGAP text that's displayed in the app from
<h1>PhoneGap</h1>to<h1>Hello PhoneGap</h1>. (This text has a CSS uppercase transform applied to it in the default project). Save it when you're finished and move on to the next step. - Now check your mobile device where the PhoneGap Developer app is running and you will see your application reload and automatically display the new text:
- Continue making updates to your project to get familiar with this workflow.At this point you should check out this guide explaining important details about the default Hello PhoneGap application and mobile application development tips with PhoneGap in general.
