Ionic Cookbook

You need to install Ionic and its dependencies to get started. Ionic itself is just a collection of CSS styles and AngularJS Directives and Services. It also has a command-line tool to help manage all of the technologies such as Cordova and Bower. The installation process will give you a command line to generate initial code and build the app.

Ionic uses npm as the installer, which is included when installing Node.js. Please install the latest version of Node.js from http://nodejs.org/download/.

You will need Cordova, ios-sim (iOS Simulator), and Ionic:

$ npm install -g cordova ionic ios-sim

This single command line will install all three components instead of issuing three command lines separately. The -g parameter is to install the package globally (not just in the current directory).

For Linux and Mac, you may need to use the sudo command to allow system access:

$ sudo npm install -g cordova ionic ios-sim

There are a few common options for an integrated development environment:

All of those have a free license. Sublime Text is free for non-commercial use only but you have to purchase a license if you are a commercial developer. Most frontend developers would prefer to use Sublime Text for coding HTML and JavaScript because it's very lightweight and comes with a well-supported developer community. You could code directly in Xcode, Eclipse, or Visual Studio Express, but those are somewhat heavy duty for web apps, especially when you have a lot of windows open and just need something simple to code.

If you decide to use Sublime Text, you will need Package Control (https://packagecontrol.io/installation), which is similar to a Plugin Manager. Since Ionic uses Sass, it's optional to install the Sass Syntax Highlighting package:

There are tons of packages that you may want to use, such as Haml, JSHint, JSLint, Tag, ColorPicker, and so on. You can browse around this website: https://sublime.wbond.net/browse/popular, for more information.

To set up the app with a blank template from Ionic, use this command:

$ ionic start HelloWorld_Blank blank

If you replace blank with tabs, it will create a tab template:

$ ionic start HelloWorld_Tabs tabs

Similarly, this command will create an app with a sidemenu:

$ ionic start HelloWorld_Sidemenu sidemenu

The sidemenu template is the most common template as it provides a very nice routing example with different pages in the templates folder under /www.

Additional guidance for the Ionic CLI is available on the GitHub page:

https://github.com/driftyco/ionic-cli

This chapter will show you how to quickly start your codebase and visually see the result. More detail about AngularJS and its template structure will be discussed across various chapters in this book. However, the following are the core concepts:

The project folder structure will look like the following:

You will spend most of your time in the /www folder, because that's where your application logic and views will be placed.

By default from the Ionic template, the AngularJS module name is called starter. You will see something like this in app.js, which is the bootstrap file for the entire app:

angular.module('starter', ['ionic', 'ngCordova', 'starter.controllers', 'starter.services', 'starter.directives', 'starter.filters'])

This basically declares starter to be included in ng-app="starter" of index.html. We would always have ionic and ngCordova (as in other examples from this book, although ngCordova is not essential). The other modules are required and listed in the array of string [...] as well. They can be defined in separate files.

Note that if you double click on the index.html file to open in the browser, it will show a blank page. This doesn't mean the app isn't working. The reason is that the AngularJS component of Ionic dynamically loads all the .js files and this behavior requires server access via an HTTP protocol (http://). If you open a file locally, the browser automatically treats it as a file protocol (file://) and therefore AngularJS will not have the ability to load additional .js modules to run the app properly. There are several methods of running the app that will be discussed.

Ionic Creator requires registration for a free account at https://creator.ionic.io/ to get started.

Create a new project called myApp:

You will see this simple screen:

The center area is your app interface. The left side gives you a list of pages. Each page is a single route. You also have access to a number of UI components that you would normally have to code by hand in an HTML file. The right panel shows the properties of any selected component.

You're free to do whatever you need to do here by dropping components to the center screen. If you need to create a new page, you have to click the plus sign in the Pages panel. Each page is represented as a link, which is basically a route in AngularJS UI Router's definition. To navigate to another page (for example, after clicking a button), you can just change the Link property and point to that page.

There is an Edit button on top where you can toggle back and forth between Edit Mode and Preview Mode. It's very useful to see how your app will look and behave.

Once completed, click on the Export button on the top navigation. You have three options:

The best way to learn Ionic Creator is to play with it. You can add a new page and pick out any existing templates. This example shows a Login page template:

Here is how it should look out of the box:

To switch to Preview Mode where you can see the UI in a device simulator, click the switch button on the top right to enable Test:

In this mode, you should be able to interact with the components in the web browser as if it's actually deployed on the device.

If you break something, it's very simple to start a new project. It's a great tool to use for "prototyping" and to get initial template or project scaffolding. You should continue to code in your regular IDE for the rest of the app. Ionic Creator doesn't do everything for you, yet. For example, if you want to access specific Cordova plugin features, you have to write that code separately.

Also, if you want to tweak the interface outside of what is allowed within Ionic Creator, it will also require specific modifications to the .html and .css files.

There are several tags of interest to browse through if you want specific UI component examples:

You don't need a Codepen account to view. However, if there is a need to save a custom pen and share with others, free registration will be required.

The Ionic Codepen Demos site has more collections of demos comparing to the CLI. Some are based on a nightly build of the platform so they could be unstable to use.

You can find the same side menu example on this site:

The recommended method is to use the ionic serve command line. It basically launches an HTTP server so you can open your app in a desktop browser.

That's it! There is no need to go into the /www folder or figure out which port to use. The command line will provide these options while the web server is running:

The most common option to use here is r to restart or q to quit when you are done.

There is an additional step to view the app with the correct device resolution:

Most developers would prefer to use this method to code as you can debug the app using Chrome Developer Tools. It works exactly like any web application. You can create breakpoints or output variables to the console.

Note that ionic serve is actually watching everything under the /www folder except the JavaScript modules in the /lib folder. This makes sense because there is no need for the system to scan through every single file when the probability for it to change is very small. People don't code directly in the /lib folder but only update when there is a new version of Ionic. However, there is some flexibility to change this.

You can specify a watchPatterns property in the ionic.project file located in your project root to watch (or not watch) for specific changes:

{
  "name": "myApp",
  "app_id": "",
  "watchPatterns": [
    "www/**/*",
    "!www/css/**/*",
    "your_folder_here/**/*"  
  ]
}

While the web server is running, you can go back to the IDE and continue coding. For example, let's open the playlists.html file under /www/templates and change the first line to this:

<ion-view view-title="Updated Playlists">

Go back to the web browser where Ionic opened the new page; the app interface will change the title bar right away without requiring you to refresh the browser. This is a very nice feature when there is a lot of back and between code changes and allows checking on how it works or looks in the app instantly.

You can connect a physical device via a USB port and it will show up in the iOS Device list for you to pick. Then you can deploy the app directly on your device. Note that iOS Developer Membership is required for this. This method is more complex than just viewing the app via a web browser.

However, it's a must when you want to test your code related to device features such as camera or maps. If you change code in the /www folder and want to run it again in Xcode, you have to do ionic build ios first, because the running code is in the Staging folder of your Xcode project:

For debugging, the Xcode Console can output JavaScript logs as well. However, you could use the more advanced features of Safari's Web Inspector (which is similar to Google Chrome's Developer Tools) to debug your app. Note that only Safari can debug a web app running on a connected physical iOS device because Chrome does not support this on a Mac.

It's simple to enable this capability:

Note: If you don't see the Develop menu in Safari, you need to navigate to menu Preferences | Advanced and check on Show Develop menu in menu bar.

Safari will open a new console just for that specific device just as it's running within the computer's Safari.

Although there are many steps to get this working, it's a lot less likely that you will have to go through the same process again. Once your environment is set up, all you need to do is to leave Genymotion running while writing code. If there is a need to test the app in different Android devices, it's simple just to add another virtual device in Genymotion and connect to it.

There are two ways to use Ionic View. You can either upload your own app or load someone else's App ID. If you test your own app, follow these steps:

If there is no code update, the process is the same except that you need to select Sync to latest at the menu.

In summary, there are several benefits of using Ionic View:

All application logic customization should be done in the /www folder as index.html is the bootstrap template. If you add in more JavaScript modules, you can put them in the /www/js/lib folder.

There is no need to modify the /platforms or /plugins folders manually unless troubleshooting needs to be done. Otherwise, the ionic or cordova CLI will automate the content inside those folders.