Previous: What is Ionic?
Chapter 2: Getting Everything Installed
In this chapter, we are going to walk through the process of downloading Ionic and installing all necessary dependencies for development.
First, we need to start with a note about minimum requirements for building your app with the current release of Ionic. For the first releases, Ionic only works on recent iPhone and Android devices. We support iOS 6+, and Android 4.2+. However, since there are a lot of different Android devices, it's possible certain ones might not work. As always, we are looking for help testing and improving our device compatibility and would love help from the community on our GitHub project.
You can develop Ionic apps on any operating system you prefer. In fact, Ionic has been developed at various times on Mac OS X, Linux, and Windows. However, right now you'll need to use the command line in order to follow this guide and you must have OS X in order to develop and deploy iPhone apps, so OS X is recommended if possible.
First, we will go and install the most recent version of Apache Cordova, which will take our app and bundle it into a native wrapper to turn it into a traditional native app. There are other possible tools you could use instead of Cordova, including PhoneGap proper (the Adobe version of Cordova that has some additional Adobe service bundled in), Trigger.io, or a custom solution.
To install Cordova, make sure you have Node.js installed, then run
$ sudo npm install -g cordova
sudo from the above command if running on Windows. Depending on the platforms you wish to develop for, you'll need to install platform-specific tools. Follow the Cordova platform guides for Android and iOS to make sure you have everything needed for development on those platforms. Luckily, you'll only need to do this once.
If you are running a 64-bit version of Ubuntu, you'll need to install the 32-bit libraries since Android is only 32-bit at the moment.
$ sudo apt-get install ia32-libs
Windows users developing for Android: You'll want to make sure you have the most recent [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html) (NOT just the JRE) installed and that you have installed ant. To install ant, download a zip from here, extract it, move the first folder in the zip to a safe place, and update your PATH to the
bin/ folder in that folder. For example, if you moved the ant folder to
c:/, you'd want to add this to your PATH:
Next, set a path entry for JAVA_HOME pointing to the root of the JDK folder that was created when you installed the Java JDK above. So, if you installed the JDK into
C:\Program Files\Java\jdk7, set JAVA_HOME to be this path. After that add the JDK's bin directory to the PATH variable as well, following the previous assumption, this should be
Cordova also requires the ANDROID_HOME entry to be set, this should point to the
Whenever you make changes to the PATH, or any other environment variable, you'll need to restart or open a new tab in your shell program for the PATH change to take effect.
Then, we can go download the most recent release of Ionic. It is not recommended to clone the repo for production apps unless you want to live on the bleeding edge.
Once you have the most recent release of Ionic, extract it anywhere you like on your computer. We are only going to be needing some of the files for our app, specifically the ones in the
release/ folder, and possibly the ones in the
scss/ folder for more advanced usage (more on that later). For the sake of getting started, we will start with the most basic usage of Ionic.
Create the project
Now, we need to create a new Cordova project somewhere on the computer for the code for our app:
$ cordova create hello com.ionic.todo Todo
That will create a folder called
hello in the directory the command was run. Next, we will change into that directory:
$ cd hello
If you are planning on using any version control system, you can go ahead and set it up using this new folder. For new apps, follow this folder structure to get up and running quickly:
Go ahead and copy the
release/ files from the Ionic code (in
IONIC_PATH below) we extracted above into the various
www/* folders inside of the hello folder:
$ cp -R IONIC_PATH/release/* www/
Now, we need to tell Cordova that we want to enable the iOS and Android platforms:
$ cordova platform add ios $ cordova platform add android
If you see errors here, make sure to follow the platform guides above to install necessary platform tools.
If you get this error:
[Error: ERROR : Make sure JAVA_HOME is set, as well as paths to your JDK and JRE for java.] Then try running this command first before adding the android platform:
$ export JAVA_HOME=$(/usr/libexec/java_home)
We need to install at least one required plugin, the Device API, which lets us query device information:
$ cordova plugin add org.apache.cordova.device
To make our lives easier, let's also install the console plugin so we can see our
console.log calls in XCode and the Android IDE:
$ cordova plugin add org.apache.cordova.console
Just to make sure the default Cordova project worked, try building and running the project:
$ cordova build android $ cordova emulate android
Be patient, this takes serveral minutes as the Android emulator is booted up. If you don't see anything happen for a few minutes, make sure you've created an Android Virtual Device (AVD), and that it is using the Android SDK version 17 or above. You might have to reduce the amount of memory the AVD is using if you don't see the emulator boot up in a minute. The platform guide above has more information. You may also want to double check that you have the sdk and platform tools in your PATH as noted in the platform guide.
The emulator takes a LONG time to boot. After about 5 or 10 minutes, you should see the default Cordova app running in the emulator:
Clearing the defaults
Before we start building our app, we should remove all the Cordova default code. Go ahead and run the following commands:
$ rm www/index.html $ rm www/js/index.js $ rm www/css/index.css $ rm www/img/logo.png
We need to make some quick configuration changes to Cordova defaults to make sure our app behaves normally. Specifically, we need to turn off Web View bouncing that is on by default for iOS apps. Open up
config.xml and add these preferences to the bottom:
<preference name="webviewbounce" value="false" /> <preference name="UIWebViewBounce" value="false" /> <preference name="DisallowOverscroll" value="true" />
AngularJS and other dependencies
The first versions of Ionic utilize AngularJS heavily. We think it's the best way to build applications in the browser today, and we've built a lot of great mobile functionality around it. In the future, we hope the community will create extensions for other frameworks like Ember.js and Knockout, to name a few.
For our example apps, we will be using the 1.2.x version of Angular, and older versions are not supported. Ionic-Angular needs Angular 1.2.x along with ngAnimate, ngTouch, ngSanitize, and ngResource at least.
Now we are ready to start building our app, so continue on to the next chapter: