This guide steps you through how to create a Landmark Connect app. There's also a generator.
Landmark Connect is a powerful HTML5 native-feeling mobile app built using all with web technologies like HTML, CSS, and Javascript.
Under the hood, Landmark Connect was built using the Ionic Framework, which is then compiled into a platform-centric native app wrapper.
Landmark is designed to make complicated things simple, so that you can build your app easily.
This guide will show you how to build a Landmark Connect app using the default project structure and options.
To learn more about how things work under the hood, and how you can extend or replace features, we strongly recommend reading the source code.
The easiest way to get started with Landmark Connect is to use our new Yeoman Generator.
We're still updating our getting started guide to reflect this; in the meantime head over to the Landmark Connect Yeoman Generator page and follow the instructions there.
Running yo landmark-connect will generate a complete project for you.
With your package and web scripts in place, it's time to scaffold out containers for the rest of your app. Create the following directory structure:
|--res | Artwork used for icons and splashscreens |--scss | Source code for the stylesheets used in your app. | |--landmark.app.scss | | This file will be compiled into www/css/style.css |--www | |--assets | | Icons and images used in the app's user interface | |--css | | Your app's compiled stylesheet using the SCSS files in the project's root SCSS folder | |--js | | |--app.js | | The main view router for Angular | | |--controllers.js | | Custom functions for your routes | | |--directives.js | | Custom behaviors that modify HTML | | |--filters.js | | Custom formatting filters for display | | |--services.js | | Connecting your app up to your API |--config.xml | Controls many aspects of an app's behavior when compiled with Cordova
This guide assumes you follow the recommendations above, however if you make modifications and change these, you might break the app.
Usually, the easiest and clearest way to configure the logic for different routes (or views) in your application is to set up all the bindings single file, then put any common logic (or middleware) in another file.
Then, the controller for each route you bind goes in its own file, organised similarly to the template that renders the view.
First, have a look in the www/js/app.js file. This is where we bind your application's URL patterns to the controllers that load and process data, and render the appropriate template.
For more information about Angular's router, please check out the AngularJS documentation for the $routeProvider.
Now, for the template our route will render. All templates for the app are found in the www/templates folder. Please see the Ionic Framework documentation for more resources.
You might want to customize the look and feel of your app by changing some of the default icons or images used in the app. In the examples above, we're including /www/css/style.css.
Feel free to have a look around at the code to see how you can customize this.
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.
ionic serve
This will start a live-reload server for your project. When changes are made to any HTML, CSS, or JavaScript files, the browser will automatically reload when the files are saved.
You can also test right in the simulator using the cordova commands from the previous section. For example, to test in the iOS simulator, run:
ionic build ios ionic emulate ios
Please note that if you are using a simulator, you need to make sure the Cordova plugins described in the Publishing section below have been installed. Otherwise, you will recieve errors or things may not function properly.
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, I recommend still working inside of the root www folder, and when you've made changes to this folder, run the command:
cordova prepare ios
Which will update the ios specific project with the code from the www folder. Note: this will overwrite any changes you've made to the platforms/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.
Please note that before building your app, you need to make sure the Cordova plugins described in the Publishing section below have been installed. Otherwise, you will recieve errors or things may not function properly.
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
ionic run android
If this doesn't work, make sure you have USB debugging enabled on your device, as described on the Android developer site.
Now that we have a working app, we are ready to push it live to the world! Since Maven, the creators of Landmark Connect, already submitted the Landmark Connect app from this guide to the app store, chances are you'll want to follow this with a new app that you make on your own.
So first, we need make sure we have the plugins needed for the app. For more information about Cordova plugins, please read the documentation.
cordova plugin add org.apache.cordova.device cordova plugin add org.apache.cordova.file cordova plugin add org.apache.cordova.geolocation cordova plugin add org.apache.cordova.inappbrowser cordova plugin add https://github.com/driftyco/ionic-plugins-keyboard.git cordova plugin add org.apache.cordova.media cordova plugin add org.apache.cordova.splashscreen cordova plugin add org.apache.cordova.statusbar
Please see the Cordova platform guides for platform-specific notes on building your app.