search

tzellman / ember-cordova-example-app

Example application using ember-cordova, and more importantly instructions on how to create your own app using ember-cordova.
5 stars 2 forks source link
android cordova-application ember-cordova

readme

ember-cordova-example-app

The goal of this project is to build an example ember-cordova application, primarily to help other developers get past some of the gotchas of getting started. Additionally, this will serve as a way to expose some of the capabilities of ember-cordova, cordova and various plugins.

Clone this repository if you want to just get started. Note that you will still need to walk through some of the steps below in order to get your environment in order.

I will outline all of the steps I took in order to create this project, so you can also use this README as a guide to setting things up for yourself.

This repository

By default, if you checkout the master branch, this will give you the bare-bones essentials of a new ember/cordova application.

I will have various feature branches that highlight different capabilities/plugins, and will describe those here as they become available.

Additionally, the develop branch will have the latest/greatest state of the app, with all demos/plugins enabled.

Prerequisites

As with any Ember application, you will need the following things properly installed on your computer.

As of right now, I am going to target Android, so you'll also need the Android SDK installed. One of the easiest ways to do this is to download Android Studio.

Make sure to expose the base Android SDK path as the ANDROID_HOME environment variable.

export ANDROID_HOME=/data/AndroidStudio/Sdk/

Building this project

First, make sure you have setup Android and started an emulater (see below for more details).

git clone https://github.com/tzellman/ember-cordova-example-app.git
cd ember-cordova-example-app
npm install
bower install
ember cdv:build
ember cdv:s --reload-url=http://YOUR_IP_ADDRESS:4200

In another window/pane, run:

cd ember-cordova-example-app
ember cordova emulate

Creating your own ember-cordova application

Approach

When building a hybrid application using Ember and Cordova you'll need to understand how you should approach the setup.

The gist is:

Project Init / Setup

First off, create an Ember project.

ember new ember-cordova-example-app

Install cordova globally. (If you use nvm then you won't need sudo privileges)

npm install -g cordova

Install the ember-cordova addon in your project.

cd ember-cordova-example-app
ember install ember-cordova

You could have done this in the previous step, but to demonstrate that you can change this at any time, let's go ahead and set our application id. Note: You can also just edit the ember-cordova/cordova/config.xml file yourself.

rm -rf ember-cordova
ember g ember-cordova --name="Ember Cordova Example App" --cordovaid=net.forthought.cordova

Next, you need to change the locationType to hash in config/environment.js.

    rootURL: '/',
    locationType: 'hash',

You'll also need to update ember-cordova/cordova/config.xml to include the following line:

    <allow-navigation href="https://github.com/tzellman/ember-cordova-example-app/blob/develop/*" />

Finally, if you are using ember 2.7 or higher (which I am), you'll need to edit your app/index.html file to remove references of {{rootUrl}}.

Prepare Android

Let's add the android platform to our project.

Before we do that, make sure you have a version of Android installed. You can do that by running the Android SDK manager.

$ANDROID_HOME/tools/android

I made sure Android 6.0 (API 23) was installed and up-to-date.

SDK Manager

Additionally, you'll likely want to create a Virtual Device (emulator).

Click Tools->Manage AVDs.. from the Android SDK Manager.

Then, create a new virtual device. Here is an example:

Test AVD

Go ahead and start/launch it, so that we can install our app to it in a later step.

Note: I use Xubuntu and I got an error while launching that looked like:

Launch Error

I was able to resolve the issue by launching the emulator from the commandline like so:

LD_PRELOAD='/usr/lib/x86_64-linux-gnu/libstdc++.so.6' $ANDROID_HOME/tools/emulator -netdelay none -netspeed full -avd test2

You may need to find where libstdc++.so.6 exists on your system and adjust the command accordingly.

More information on this error is available here.

For additional debugging information, you can view the logcat:

$ANDROID_HOME/platform-tools/adb logcat

Add Android to the project

Now, let's add the platform to our project.

Again, make sure you have exposed the base Android SDK path as the ANDROID_HOME environment variable. For me this was:

export ANDROID_HOME=/data/AndroidStudio/Sdk/

Add the platform.

ember cdv platform add android

If you had errors here, it likely could be that your application ID was not formatted correctly. Make sure it is in the format some.package.name, with no camelCase or dashes. See my notes on Project Setup above.

Since we are going to use android throughout, let's go ahead and tell ember-cordova that this will be our default platform. To do that, just edit your .ember-cli file and add the following line.

    "platform": "android"

Build and Run the project

There are a few options. One option is to build then install the app on an emulator.

ember cdv:build
ember cordova emulate

The way I would suggest you build the project is in live-reload mode. To do this, we tell ember-cordova to serve the app for us.

Before we do this, you'll need to know the IP Address of your computer; localhost will not work, as the emulator needs to connect to the host IP.

ember cdv:s --reload-url=http://192.168.0.110:4200

After doing so, in another window/pane (I use tmux) let's install the app to the emulator:

ember cordova emulate

Now, look at your emulator and you should see the lovely ember welcome page!

Success

If you have an Android device and a good USB cable, just enable USB debugging on the device and you can run your app there instead.

You can monitor your devices with the Android Device Monitor.

$ANDROID_HOME/tools/monitor &

Once you're device is visible in the monitor, go ahead and run your app.

ember cordova run

Next Steps for Development

Now that you are running in live-reload mode, you can make changes to your app and it will automatically get reloaded in the emulator!

Concept 1: Adding a splash screen and app icon

Splashscreen

  1. Install the splashscreen plugin
ember cdv:plugin add cordova-plugin-splashscreen
  1. Add your splashscreen image to ember-cordova/cordova/res/splash.png

Note: the name of the image can be whatever you want, but you'll need to update the next step.

  1. Update ember-cordova/cordova/config.xml and add the following:
<splash src="https://github.com/tzellman/ember-cordova-example-app/raw/develop/res/splash.png" />

App icon

  1. Create your icon as an SVG file and copy to ember-cordova/icon.svg

  2. Generate the icons

ember cdv:make-icons --platform=android

Concept 2: Dialogs

  1. Install the plugin
ember cdv:plugin add cordova-plugin-dialogs

More info here.

  1. Interact with the API
    doAlert(){
        navigator.notification.alert("This is purely a test...", null, "Alert Test", "OK!");
    }

Also, worth noting is that I decided to install the ember-paper addon, so we can start styling our app using material design.

You can add this in your own app:

ember install ember-paper

How the app looks now:

Dialogs

Concept 3: StatusBar

  1. Install the plugin
ember cdv:plugin add cordova-plugin-statusbar

More info here.

Concept 4: Camera

  1. Install the plugin
ember cdv:plugin add cordova-plugin-camera

More info here.

The "meat" can be demonstrated here: camera-example/component.js.

How the camera demo view looks:

Camera

Concept 5: Toasts

  1. Install the plugin
ember cdv:plugin add cordova-plugin-x-toast

More info here.

The "meat" can be demonstrated here: toasts-example/component.js.

How the toasts demo view looks:

Toasts

TODO

I plan on adding more steps for the overall development and deployment process, so this will be a WIP.

Thanks, and I hope this helped you get started using Ember for your next mobile effort!