Thank you for purchasing my theme. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!
Controlr also uses AngularJS for a lot of the core functionality of the framework. While you can still use Controlr with just the CSS portion, we recommend investing in Angular as it's one of the best ways to build browser-based applications today.
Controlr is focused on building native/hybrid mobile apps rather than mobile websites.
As such, our browser support tends to be whatever Web View API is available to native apps on a given platform. For Ionic 1.0.0-beta.13 "lanthanum-leopard", that means UIWebView for iOS 6+, and Android 4+ (with some support for 2.3).
First, we need to start with a note about minimum requirements for building your app with the current release of Contrlr. Controlr targets iPhone and Android devices (currently). We support iOS 6+, and Android 4.0+ (though 2.3 should work). However, since there are a lot of different Android devices, it's possible certain ones might not work.
You can develop Controlr on any operating system you prefer. In fact, Controlr 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.
To install Cordova, make sure you have Node.js installed, then run
Drop 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 If you are on Ubuntu 13.04 or greater, `ia32-libs` has been removed. You can use the following packages instead: $ sudo apt-get install lib32z1 lib32ncurses5 lib32bz2-1.0
NOTE: 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.
Install the most recent Java JDK (NOT just the JRE).
Next, create an environment variable for JAVA_HOME pointing to the root folder where the Java JDK was installed. 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 either %JAVA_HOME%\bin or the full path C:\Program Files\Java\jdk7\bin
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 include the binfolder in that folder. For example, if you moved the Ant folder to c:/, you'd want to add this to your PATH: C:\apache-ant-1.9.2\bin.
Installing the Android SDK is also necessary. The Android SDK provides you the API libraries and developer tools necessary to build, test, and debug apps for Android.
Cordova requires the ANDROID_HOME environment variable to be set. This should point to the [ANDROID_SDK_DIR]\android-sdk directory (for example c:\android\android-sdk).
Next, update your PATH to include the tools/ and platform-tools/ folder in that folder. So, using ANDROID_HOME, you would add both %ANDROID_HOME%\tools and %ANDROID_HOME%\platform-tools.
Control based on Ionic front-end framework and comes with a convenient command line utility to start, build, and package Ionic apps.
To install it, simply run:
Now, we need to create a new Cordova project somewhere on the computer for the code for our app:
That will create a folder called todo in the directory the command was run. Next, we will go into that directory and list the contents. Here is what the outer structure of your Ionic project will look like:
If you are planning on using any version control system, you can go ahead and set it up in this new folder.
Now, we need to tell ionic that we want to enable the iOS and Android platforms. Note: unless you are on MacOS, leave out the iOS platform:
If you see errors here, make sure to follow the platform guides above to install necessary platform tools.
Just to make sure the default project worked, try building and running the project (substitute ios for android to build for Android instead):
Now that we've got everything installed and a new Cordova project created, let's jump in and start building a real app!
Since every Cordova app is basically a web page, we need to have an index.html file in our app which defines the first page that loads in the app. You will find the index.html in the root folder of the Appster template. This file has a common structure:
In the shell above, we are including the Ionic CSS and both the core Ionic JS and the Ionic AngularJS extensions in the ionic.bundle.js file. Ionic comes with ngAnimate and ngSanitize bundled in, but to use other Angular modules you'll need to include them from thelib/js/angular directory.
Also note that the cordova.js or phonegap.js file must be the last script, and that this file will not be found in your development files, but rather automatically included when running or emulating your app.
The main js file is located in the /js/app.js file. This file contains the AngularJS modules and tell Angular to initialize:
This is the Angular way of creating an application, and we are telling angular to include the ionic module which includes all of the Ionic code which will process the tags above and make our app come to life. Put your custom AngularJS scripts in this file.
Now, since we actually have something to look at, we need to talk about the testing and development process for our app. There are four ways to test your app as you develop: in a desktop WebKit browser, in the iOS or Android simulator, in a mobile browser on your phone, or as a native app on the phone.
Testing your app in a browser is as simple as running the serve command in your project's root folder.
You can also test right in the simulator using the cordova commands. For example, to test in the iOS simulator, run:
Substitute ios with android for Android testing. If you want to get advanced, you can also open up the project file for a specific platform by opening the required XCode or Android Eclipse project in platforms/PLATFORM inside the root of your project. Then, you can build and test from inside the platform-specific IDE. Note: if you go this route, we recommend still working inside of the root www folder, and when you've made changes to this folder, run the command:
Which will update the ios specific project with the code from the www folder. Note: this will overwrite any changes you've made to theplatforms/ios/www and other platform-specific folders.
You can also test the app directly in a mobile browser. For OS X users, Safari on OS X can directly debug websites and simulator applications. First you have to enable the remote web inspector on both the device and Safari on desktop. To do this with iOS 7 and OS X Mavericks, enable the Web Inspector option in the iOS Settings -> Safari -> Advanced section, and also enable the Developer Menu in the Advanced section of the Safari OS X settings.
Android apps supporting Android 4.4 or above can also use Chrome for remote debugging. Check out the Android docs for more info.
If you are using the local server method from the Desktop testing section and you are on the same network as the desktop computer, you can connect to the ip address of the desktop computer to test. So, if our desktop is running a test server at 192.168.1.123:8000, we can just load that address into our mobile Chrome or Safari to test it.
One problem with testing in a mobile browser is that it's probably the furthest of the three options from the actual app experience. This is largely because the browser app is meant for browsing websites, so it often adds functionality that conflicts with your app. For example, Chrome and Safari both listen for drag events on the sides of the app which let you switch between open tabs. They also have issues with the URL bars getting in the way, and some scrolling behavior is not the same as it is in the web view running in Cordova. It is fine for small tests, but not recommended for more complex apps.
Since we are building a native (or "hybrid") app, we can (and should!) test it as one. There are serveral ways to do this. If you are building for iOS, you'll need to sign up for an Apple Developer account to test as a native app on an iPhone or iPad. Unfortunately, this costs $99 per year (don't blame us!). Once you have an account and you have set up XCode with your certificates to enable device testing, you'll want to open the XCode project from platforms/ios/ and do your testing from XCode.
Testing on Android is much easier and faster. To test on the device, simply plug it in, and run
If this doesn't work, make sure you have USB debugging enabled on your device, as described on the Android developer site.
Ionic follows the View Controller pattern popularized in such frameworks as Cocoa Touch. In the View Controller pattern, we treat different sections of the interface as child Views or even child View Controllers that contain other views. View Controllers then "power" the Views inside of them to provide interaction and UI functionality. A great example is the Tab Bar View Controller which processes taps on a Tab Bar to switch between a set of viewable panes.
Here are list of available CSS components:
Firstly, we need to generate a release build of our app, targeted at each platform we wish to deploy on. Before we deploy, we should take care to adjust plugins needed during development that should not be in production mode. For example, we probably don't want the debug console plugin enabled, so we should remove it before generating the release builds:
To generate a release build for Android, we first need to make a small change to the AndroidManifest.xml file found in platforms/android. Edit the file and change the line:
and change android:debuggable to "false":
Now we can tell cordova to generate our release build:
Then, we can find our unsigned APK file in platforms/android/bin. In our example, the file wasplatforms/android/bin/HelloWorld-release-unsigned.apk. Now, we need to sign the unsigned APK and run an alignment utility on it to optimize it and prepare it for the app store. If you already have a signing key, skip these steps and use that one instead.
Let's generate our private key using the keytool command that comes with the JDK. If this tool isn't found, refer to the installation guide:
You'll first be prompted to create a password for the keystore. Then, answer the rest of the nice tools's questions and when it's all done, you should have a file called my-release-key.keystore created in the current directory.
Note: Make sure to save this file somewhere safe, if you lose it you won't be able to submit updates to your app!
To sign the unsigned APK, run the jarsigner tool which is also included in the JDK:
This signs the apk in place. Finally, we need to run the zip align tool to optimize the APK:
Now we have our final release binary called HelloWorld.apk and we can release this on the Google Play Store for all the world to enjoy!
(There are a few other ways to sign APKs. Refer to the official Android App Signing documentation for more information.)
Now that we have our release APK ready for the Google Play Store, we can create a Play Store listing and upload our APK.
To start, you'll need to visit the Google Play Store Developer Console and create a new developer account. Unfortunately, this is not free. However, the cost is only $25 compared to Apple's $99.
Once you have a developer account, you can go ahead and click "Publish an Android App on Google Play" as in the screenshot below:
Then, you can go ahead and click the button to edit the store listing (We will upload an APK later). You'll want to fill out the description for the app.
As you develop your app, you'll want to update it periodically.
In order for the Google Play Store to accept updated APKs, you'll need to edit the platforms/android/AndroidManifest.xml file to increment theandroid:versionCode value.