Idea Transcript
Build Mobile Apps with Ionic 1 and Firebase A starter’s guide with real examples Fu Cheng This book is for sale at http://leanpub.com/build-mobile-apps-with-ionic-and-firebase This version was published on 2016-10-09
This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. © 2015 - 2016 Fu Cheng
Also By Fu Cheng Lodash Cookbook A Practical Guide for Java 8 Lambdas and Streams
To my wife Andrea and daughter Olivia
Contents 1. Introduction . . . . . . . . 1.1 Hybrid mobile apps 1.2 Apache Cordova . . 1.3 Ionic framework . . 1.3.1 Ionic 2 . . . . . 1.4 Firebase . . . . . . 1.5 About this book . . 1.6 Source code . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
1 1 3 4 4 4 5 5
2. Get started . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Prepare local environment . . . . . . . . . . . . 2.1.1 iOS . . . . . . . . . . . . . . . . . . . . . . 2.1.2 Android . . . . . . . . . . . . . . . . . . . . 2.2 Create app skeleton . . . . . . . . . . . . . . . . 2.2.1 Blank app . . . . . . . . . . . . . . . . . . . 2.2.2 Tabbed app . . . . . . . . . . . . . . . . . . 2.2.3 Sidemenu . . . . . . . . . . . . . . . . . . . 2.2.4 Maps . . . . . . . . . . . . . . . . . . . . . 2.3 Development . . . . . . . . . . . . . . . . . . . . 2.3.1 Start local server . . . . . . . . . . . . . . . 2.3.2 Use Chrome for development . . . . . . . . 2.3.3 Use Chrome DevTools for remote debugging 2.4 Test and run . . . . . . . . . . . . . . . . . . . . 2.4.1 iOS . . . . . . . . . . . . . . . . . . . . . . 2.4.2 Android . . . . . . . . . . . . . . . . . . . . 2.5 Ionic Lab . . . . . . . . . . . . . . . . . . . . . . 2.6 Ionic Creator . . . . . . . . . . . . . . . . . . . . 2.7 Upgrade Ionic version . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
6 6 6 7 8 8 8 11 13 15 15 15 16 17 17 19 21 23 24
3. Hacker News app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Why Hacker News app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 User stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26 26 26
4. App skeleton code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
CONTENTS
4.1
. . . . . . . . . . . . . . . . . . .
28 28 29 30 30 30 30 31 31 31 31 31 31 31 31 31 32 32 32
5. Share stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
6. Publish . . . . . . . . . . . . . . . . . . 6.1 Icons & splash screens . . . . . . 6.2 Deploy to device . . . . . . . . . 6.3 View and share with Ionic View
. . . .
35 35 36 37
7. Thank you . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
4.2 4.3 4.4 4.5 4.6 4.7 4.8
Root directory . . . . . . . . . 4.1.1 package.json . . . . . . . 4.1.2 bower.json and .bowerrc 4.1.3 config.xml . . . . . . . . 4.1.4 gulpfile.js . . . . . . . 4.1.5 ionic.project . . . . . . hooks . . . . . . . . . . . . . . node_modules . . . . . . . . . platforms . . . . . . . . . . . plugins . . . . . . . . . . . . resources . . . . . . . . . . . scss . . . . . . . . . . . . . . www . . . . . . . . . . . . . . . 4.8.1 index.html . . . . . . . . 4.8.2 lib . . . . . . . . . . . . 4.8.3 img . . . . . . . . . . . . 4.8.4 css . . . . . . . . . . . . 4.8.5 templates . . . . . . . . 4.8.6 js . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . .
. . . .
1. Introduction A mobile app¹ is a computer program designed to run on mobile devices such as smartphones and tablet computers. With the prevalence of mobile devices, more and more mobile apps have been created to satisfy all kinds of requirements. Table 1.1 shows statistics of major app stores². Table 1.1. Statistics of major app stores
App store
Number of available apps
Downloads to date
App Store (iOS) Google Play Windows Store BlackBerry World Amazon Appstore
1.5 million 1.7 million 340,000+ 240,000+ 334,000+
100 billion 50 billion 4 billion
Prevalence of mobile apps also creates a great opportunity for application developers and software companies. According to a report³ on March 2005, Apple has said that its App Store generated $10 billion in revenue to developers last year, while Google has said it has paid out $7 billion to app developers over the past 12 months. The revenue of app stores is seen doubling by 2018. A lot of individuals and companies make big money on the mobile apps market. A classic example is the popular mobile game Flappy Bird⁴. Flappy Bird was developed by Vietnam-based developer Dong Nguyen. The developer claimed that Flappy Bird was earning $50,000 a day from in-app advertisements as well as sales. This encourages developers to create more mobile apps.
1.1 Hybrid mobile apps Developing mobile apps is not an easy task. To build apps which can be distributed on various app store markets, developers need to use specific programming languages, SDKs, and tools, e.g. Objective-C/Swift for iOS and Java for Android. The high learning curve for those SDKs creates a burden for developers. Comparing to Objective-C/Swift or Java, web development skills, e.g. HTML, ¹https://en.wikipedia.org/wiki/Mobile_app ²App store statistics is gathered from various sources: 1, 2, 3, 4, 5, 6 and may not be up to date. ³http://recode.net/2015/03/30/sales-from-apple-and-google-app-stores-seen-doubling-by-2018-in-app-advertising-to-triple/ ⁴https://en.wikipedia.org/wiki/Flappy_Bird
Introduction
2
JavaScript and CSS are easier to learn. Building mobile apps with web development skills is made possible by HTML5⁵. This new type of mobile apps is called hybrid mobile apps. In hybrid mobile apps, HTML, JavaScript and CSS code runs in an internal browser (WebView) that it’s wrapped in native apps. JavaScript code can access native APIs through the wrapper. Apache Cordova⁶ is the most popular open-source library to develop hybrid mobile apps. Comparing to native apps, hybrid apps have their benefits and drawbacks. The major benefit is that developers can use existing web development skills and use only one code base for different platforms. By leveraging responsive web design techniques, hybrid apps can easily adapt to different screen resolutions. The major drawback is the performance issues with hybrid apps. As the hybrid app is actually running in an internal browser, the performance of hybrid apps cannot compete with native apps. Certain types of apps, such as games or apps that rely on complex native functionalities, cannot be built as hybrid apps. Before making the decision of whether to go with a native app or hybrid app, the development team needs to understand the nature of the app. Hybrid apps are suitable for content-centric apps, such as news readers, online forums or products showcasing. Another important factor to consider is development team’s skill sets. Following diagram shows the dilemma when choosing between hybrid and native mobile apps. ⁵https://en.wikipedia.org/wiki/HTML5 ⁶https://cordova.apache.org/
3
Introduction
Native vs. Hybrid mobile apps
1.2 Apache Cordova Apache Cordova is a popular open-source framework to develop hybrid mobile apps. It originates from PhoneGap⁷ created by Nitobi. Adobe acquired Nitobi in 2011 and provides commercial service upon it. The PhoneGap source code was contributed to Apache Software Foundation and new project Apache Cordova was started based on that. ⁷http://phonegap.com/
Introduction
4
An Apache Cordova application is implemented as a web page. This web page can reference JavaScript, CSS, images and other resources. WebView loads and runs this web page. A powerful feature of Cordova is its plugin interface which allows JavaScript code running in a web page to communicate with native components. With the help of plugins, Cordova apps can access device’s accelerometer, camera, compass, contacts and more. There are 680 plugins currently available in Cordova’s plugin registry⁸. Apache Cordova is just a runtime for web apps. It can support any kinds of web pages. To create mobile apps look like native apps, we need other UI frameworks to develop hybrid mobile apps.
1.3 Ionic framework Ionic framework⁹ is a powerful tool to build hybrid mobile apps. It’s open source¹⁰ and has nearly 20,000 stars on GitHub. Ionic is popular for following reasons: • • • •
Use Angular¹¹ as the JavaScript framework. Provide beautifully designed out-of-box UI components, e.g. lists, cards, modals, and popups. Leverage Apache Cordova as the runtime to communicate with native platform. Perform great on mobile devices.
Ionic can help to build hybrid mobile apps with a similar look and feel as native apps. The Ionic framework is the main topic of this book.
1.3.1 Ionic 2 Ionic 2¹² is a completely rewritten version of Ionic framework based on Angular 2¹³. It dramatically improves performance and reduces the complexity of the code. Ionic 2 is currently in beta. It’s worth to check out this new beta version to understand the future of Ionic framework. However, this book focuses on Ionic 1.
1.4 Firebase Mobile apps usually need back-end service to work with front-end UI. This means that there should be back-end code and servers to work with mobile apps. Firebase is a cloud service to power apps’ ⁸http://cordova.apache.org/plugins/ ⁹http://ionicframework.com/ ¹⁰https://github.com/driftyco/ionic ¹¹http://angularjs.org/ ¹²http://ionic.io/2 ¹³https://angular.io/
Introduction
5
back-end. Firebase can provide data storage and user authentication. After integrating mobile apps with Firebase, we don’t need to write our own back-end code or manage servers. Firebase works very well with Ionic to eliminate the pain of maintaining our own back-end. This is especially helpful for hybrid mobile apps developers with only front-end development skills. Frontend developers can use familiar JavaScript code to interact with Firebase.
1.5 About this book This book is a complete guide about how to use Ionic framework and Firebase to build hybrid mobile apps. The sample app we build in this book is a client of Hacker News. Features of this app include: • • • •
View top stories. View comments on stories. Add stories to favorites. Share stories.
This book covers the whole cycle of hybrid mobile apps development. It’s organized around implementing above user stories. For each story, this book not only talks about how to implement it but also explain related Ionic and Firebase concepts in detail. This book is for front-end developers with basic HTML, CSS, and JavaScript skills. Basic understanding of Angular is also required as Angular is the JavaScript framework used in Ionic.
1.6 Source code The source code is available on GitHub¹⁴. The example app can also be viewed using Ionic View with ID 131c3395. ¹⁴https://github.com/alexcheng1982/hacker-news-ionic
2. Get started Before we can build Ionic apps, we need to set up local development environment first.
2.1 Prepare local environment Install Node.js¹ on local machine first. Then use npm to install Ionic command-line tools and Apache Cordova. Listing 1.1. Install Ionic and Apache Cordova
1
$ npm install -g cordova ionic
You may need to have system administrator privilege to install. For Linux and Mac OS X, use sudo. For Windows, start a command-line window as the administrator.
After installation of Ionic and Cordova, we can use Ionic CLI ionic to start developing Ionic apps.
2.1.1 iOS Developing iOS apps with Ionic requires Mac OS X and Xcode. Install Xcode² and Xcode command line tools on Mac OS X. Open a terminal window and type command in Listing 1.2. Listing 1.2. Check installation status of Xcode command line tools
1
$ xcode-select -p
If you see output like Listing 1.3, then command line tools have already been installed. Listing 1.3 Output of installed Xcode command line tools
1
/Applications/Xcode.app/Contents/Developer
Otherwise, type command in Listing 1.4 to install. ¹http://nodejs.org/ ²https://developer.apple.com/xcode/
7
Get started
Listing 1.4. Install Xcode command line tools
1
$ xcode-select --install
After installation finished, use xcode-select -p to verify. To run iOS simulator using Ionic CLI, npm package ios-sim is required. Install ios-sim using the command in Listing 1.5. Listing 1.5. Install ios-sim package
1
$ npm -g install ios-sim
2.1.2 Android To develop Ionic apps for Android, Android SDK must be installed. It’s recommended to install Android Studio³ which provides a nice IDE and Android SDK tools. If you don’t want to use Android Studio, you can install stand-alone SDK tools⁴. Android API level 22⁵ is required to run Ionic apps. Make sure required SDK platform is installed.
Stand-alone SDK tools is just a ZIP file, unpack this file into a directory and it’s ready to use. The downloaded SDK only contains basic SDK tools without any Android platform or third-party libraries. You need to install the platform tools and at least one version of the Android platform. Run android in tools directory to start Android SDK Manager to install platform tools and other required libraries. After installing Android SDK, add SDK’s tools and platform-tools directories in your PATH environment, so SDK’s commands can be found by Ionic. Suppose that SDK tools is unpacked into /Development/android-sdk, then add /Development/android-sdk/tools and /Development/androidsdk/platform-tools to PATH environment. For Android Studio, the Android SDK is installed into directory /Users//Library/Android/sdk. To modify PATH environment on Linux and Mac OS X, edit ∼/.bash_profile file to update PATH.
³http://developer.android.com/sdk/installing/index.html?pkg=studio ⁴http://developer.android.com/sdk/installing/index.html?pkg=tools ⁵https://developer.android.com/about/versions/android-5.1.html
8
Get started
Listing 1.6. Add Android SDK tools to PATH
1 2
export PATH=${PATH}:/Development/android-sdk/platform-tools \ :/Development/android-sdk/tools
To modify PATH environment on Windows, 1. 2. 3. 4.
Click Start menu, then right-click Computer and select Properties. Click Advanced System Settings to open a dialog. Click Environment Variables in the dialog and find PATH variable in the list then click Edit. Append the path of tools and platform-tools directories to the end of PATH variable. It’s highly recommended to use Android Studio instead of stand-alone SDK tools. Standalone SDK tools is more likely to have configuration issues.
2.1.2.1 Genymotion Genymotion⁶ is a fast Android emulator. It’s recommended to use Genymotion for Android emulation instead of the standard emulator.
2.2 Create app skeleton After local development environment is set up successfully, it’s time to create new Ionic apps. Ionic provides four different types of application templates. We can choose one of these templates to create the skeleton code of the app. Use ionic start to create apps. The first argument is the name of the new app, the second argument is the template name.
2.2.1 Blank app This template blank only generates basic code for the app. List 1.7. Use blank app template
1
$ ionic start blankApp blank
2.2.2 Tabbed app This template tabs generates apps with a header at the top and tabs at the bottom, see Figure 2.1. ⁶https://www.genymotion.com/
Get started
List 1.8. Use tabs app template
1
$ ionic start tabsApp tabs
9
10
Get started
Figure 2.1. App created using tabs template
Get started
11
2.2.3 Sidemenu This template sidemenu generates apps with a side menu which open itself when sliding, see Figure 2.2. List 1.9. Use sidemenu app template
1
$ ionic start sidemenuApp sidemenu
12
Get started
Figure 2.2. App created using sidemenu template
Get started
13
2.2.4 Maps This template maps generates apps with a map in the center. It’s useful for geo-location related apps, see Figure 2.3. List 1.10. Use maps app template
1
$ ionic start mapsApp maps
14
Get started
Figure 2.3. App created using maps template
15
Get started
2.3 Development If you want to use Sass⁷, use the following command to add Sass support. Listing 1.11. Add Sass support
1
$ ionic setup sass
2.3.1 Start local server To develop and test Ionic apps in your browser, use ionic serve to start a local test server. The default port is 8100. Open your browser to http://localhost:8100/ and you should see the UI of Ionic app. Ionic sets up livereload by default, so when any HTML, JavaScript or CSS code is changed, it automatically refreshes the page. There is no need to refresh the page manually. If you see permission denied errors when running ionic command, try to add sudo before the command. If you don’t want to use sudo command, modify file permission of npm directory to make sure current user has write permission.
2.3.2 Use Chrome for development Using iOS or Android emulators to develop and test Ionic apps is not quite convenient as emulators consume more system resources and take a longer time to start. A better alternative is to use Chrome browser for basic testing. Open Chrome system menu then select More tools -> JavaScript Console. Click the mobile phone icon on the top menu bar to enable device mode, see Figure 2.4. Then you can select different devices as rendering targets, e.g. Apple iPhone 4. ⁷http://sass-lang.com/
16
Get started
Figure 2.4. Use Chrome device mode to test Ionic apps
2.3.3 Use Chrome DevTools for remote debugging For Android platform, when Ionic app is running in the emulator or real device, we can use Chrome DevTools⁸ to debug the running app. Go to chrome://inspect/#devices in Chrome and you should ⁸https://developers.google.com/web/tools/chrome-devtools/
Get started
17
a list of running apps. Click inspect to launch DevTools to inspect the running app. If you cannot see the app, make sure you can see the device listed in the result of adb devices command.
2.4 Test and run After the app is tested using browsers, it’s time to test on device simulators and real devices. First, you need to configure platforms support for your app.
2.4.1 iOS Listing 1.12. Add iOS platform
1
$ ionic platform add ios
Then build the app for iOS platform. Listing 1.13. Build for iOS
1
$ ionic build ios
Then start the emulator and test your app, see Figure 2.5 for a screen-shot of iOS emulator running Ionic app. Listing 1.14. Start iOS emulator to test the app
1
$ ionic emulate ios
18
Get started
Figure 2.5. Running Ionic blank app in iOS emulator
Get started
19
2.4.2 Android Listing 1.15. Add Android platform
1
$ ionic platform add android
Then build the app for Android platform. Listing 1.16. Build for Android
1
$ ionic build android
Then start the emulator and test your app, see Figure 2.6 for a screen-shot of Android emulator running Ionic app. Listing 1.17. Start Android emulator to test the app
1
$ ionic emulate android
20
Get started
Figure 2.6. Running Ionic blank app in Android emulator
21
Get started
2.5 Ionic Lab If you prefer a GUI tool instead of the command line, Ionic Lab⁹ is your best choice. Ionic Lab is a desktop app to create, preview, build, run and upload Ionic apps.
Figure 2.7. Create app in Ionic Lab
After an app is created, click Serve to start the test server and preview the app in the right panel. ⁹http://lab.ionic.io/
22
Get started
Figure 2.8. Serve and preview app
Then use your favorite editor to open project files created by Ionic Lab and start building the app. Ionic Lab watches changes in project files and refreshes app preview automatically. You can also manage Cordova plugins used in the app using Ionic Lab. As in Figure 2.9, select the plugin name to install a plugin.
23
Get started
Figure 2.9. Manage Cordova plugins
2.6 Ionic Creator Ionic Creator¹⁰ is a new tool to build mobile apps using Ionic. It can quickly build prototypes by drag-and-drop. After the basic app skeleton is created, we can export the app code as a ZIP file or use it by Ionic CLI as app template. ¹⁰http://ionic.io/products/creator
24
Get started
Figure 2.10. Ionic Creator
Ionic Creator supports sharing app prototypes using URL, emails and TXTs, which is very good for customers, designers and developers to collaborate. Developers can create prototypes quickly and communicate with customers to get feedback. Once customers are satisfied with the prototypes, developers can use Ionic CLI to export the prototypes and start building the apps, see Listing 1.18. creator:ff7342de3f63 is the unique ID of the app created by Ionic Creator. Listing 1.18. Use Ionic CLI to export Ionic Creator apps
1
$ ionic start [appName] creator:ff7342de3f63
2.7 Upgrade Ionic version After a new version of Ionic framework is released, we can upgrade to the new version easily. We just need to update the version number in bower.json and run bower install to install the new version. For example, to upgrade Ionic to version 1.2.4, we just need to update ionic in devDependencies to driftyco/ionic-bower#1.2.4, see Listing 1.19.
Get started
Listing 1.19. Upgrade Ionic version
1 2 3
"devDependencies": { "ionic": "driftyco/ionic-bower#1.2.4" }
25
3. Hacker News app After we have prepared local Ionic development environment and learned the basic of developing Ionic apps, it’s time to dive into the details of Ionic framework. To better explain Ionic framework, we need to build a good sample app. In this book, we are going to create a mobile app for the popular Hacker News¹ using Ionic.
3.1 Why Hacker News app Hacker News app is a good example for following reasons: • Hacker News is popular so it’s easy for developers to understand what this app is for. • This app represents a large number of content-centric mobile apps suitable for Ionic. • Hacker News has a Firebase-based API² to retrieve its data, so it’s a good example of both Ionic and Firebase.
3.2 User stories To describe the app’s requirements, we list main user stories as below. View top stories Users can view a list of top stories on Hacker News and view page of each story. View comments For each story, users can view its comments. For each comment, users can also view replies to that comment. Add stories to favorites Users can add a story to favorites and see a list of all favorite stories. Share stories Users can share stories to the social network. This book describes concepts and techniques of Ionic by implementing these user stories. ¹https://news.ycombinator.com/ ²https://github.com/HackerNews/API
4. App skeleton code Based on the sample app’s user stories, Ionic’s sidemenu template is a good start point for this app. Use ionic start hacker_news_app sidemenu to create the basic code structure of this app. Then add Sass support and platforms to this app. Listing 4.1. Set up Sass and platforms
1 2 3
$ ionic setup sass $ ionic platform add ios $ ionic platform add android
When using Ionic Lab, all the setup in Listing 4.1 can be done in its GUI.
Open the project directory with your favorite text editors or IDEs, the directory structure looks like Figure 4.1.
28
App skeleton code
Figure 4.1 Directory structure of app skeleton code
Let’s walk-through this code structure and explain each component.
4.1 Root directory 4.1.1 package.json package.json file at the root directory is a JSON file describes this Node.js project. This file contains
various metadata of this project, including name, description, version, license and other information.
App skeleton code
29
This file is also used by npm¹ to manage project’s dependencies. npm npm is the package management tool for Node.js. Dependencies are described in dependencies of package.json file. Once dependencies are declared, use npm install to install files of dependent libraries into node_modules directory.
https://docs.npmjs.com/files/package.json
4.1.2 bower.json and .bowerrc bower.json and .bowerrc at the root directory are both used by Bower². Bower is the package
manager for the web, including frameworks, libraries, assets and utilities. For example, if you want to add jQuery³ to your app, just use bower install jquery to install it. You can also add dependencies to bower.json, then use bower install to install all dependencies. .bowerrc is the configuration file⁴ for Bower. Listing 4.2 shows Ionic’s default .bowerrc file. It only configures the path to install components. The path is www/lib by default. 4.2. Ionic default .bowerrc file
1 2 3
{ "directory": "www/lib" }
Bower There are hundreds of packages available to install using Bower. Go to Search packages of Bower website and search the package you want to install and find the package name. Then add package name and version to bower.json. Once all dependencies are added, using bower install to install them. Bower also supports installing packages from Git. You can also use bower install --save to install a package and save the package dependency to bower.json at the same time. http://bower.io/search/
¹https://www.npmjs.com/ ²http://bower.io/ ³https://jquery.com/ ⁴http://bower.io/docs/config/
App skeleton code
30
4.1.3 config.xml config.xml is the configuration file for Apache Cordova. More information about this file⁵ can be
found at Apache Cordova website.
4.1.4 gulpfile.js gulpfile.js is the config file for gulp⁶. Some gulp tasks have already been defined. You can also
add your own tasks.
4.1.5 ionic.project ionic.project is the project configuration file for Ionic. As in Listing 4.3, it’s a simple JSON file. gulpStartupTasks is the list of gulp tasks to run before running local test server. By default two tasks sass and watch are run. watchPatterns is the globbing pattern⁷ of LiveReload to watch for file changes. By default, LiveReload watches for www directory without www/lib sub-directory, because www/lib contains third-party packages installed by Bower. Listing 4.3. ionic.project file
1 2 3 4 5 6 7 8 9 10 11 12
{ "name": "hacker_news_app", "app_id": "", "gulpStartupTasks": [ "sass", "watch" ], "watchPatterns": [ "www/**/*", "!www/lib/**/*" ] }
If you want to add more gulp tasks to run on startup or modify LiveReload’s watch patterns, feel free to edit ionic.project file.
4.2 hooks hooks directory contains Cordova Hooks⁸ which are special scripts to customize Cordova commands. ⁵http://cordova.apache.org/docs/en/edge/config_ref_index.md.html#The%20config.xml%20File ⁶http://gulpjs.com/ ⁷http://gruntjs.com/configuring-tasks#globbing-patterns ⁸http://cordova.apache.org/docs/en/edge/guide_appdev_hooks_index.md.html#Hooks%20Guide
App skeleton code
31
4.3 node_modules node_modules directory contains installed Node.js packages. This directory should not be managed
by code repository and it’s ignored by Git by default.
4.4 platforms For each supported platform, there is a sub-directory in platforms to contain built files for this platform. This app has ios and android sub-directories for iOS and Android platforms.
4.5 plugins This directory contains various Cordova plugins used in this app.
4.6 resources This directory contains icons and splash screen images.
4.7 scss This directory contains Scss files.
4.8 www This directory contains the source code of your app.
4.8.1 index.html index.html is the entry point of the app.
4.8.2 lib lib directory contains files of dependent packages installed by Bower.
4.8.3 img img directory contains images used in the app.
App skeleton code
32
4.8.4 css css directory contains the app’s CSS files. As this app uses Sass, we don’t want to modify files in this directory directly. After modifying Scss files in scss directory, Scss files will be compiled to CSS files and put into css directory.
4.8.5 templates templates directory contains HTML templates for the app’s states.
4.8.6 js js directory contains the app’s JavaScript files.
5. Share stories When users see good stories in the app, they may want to share those stories with others. Sharing can be done via messages, emails, Facebook or Twitter. It’s easy to add sharing feature to the app. Cordova plugin socialSharing¹ can share images, text, messages via Facebook, Twitter, Email, SMS and WhatsApp. Listing 13.1 shows how to install this plugin. Listing 13.1. Install socialSharing plugin
1 2
$ cordova plugin add https://github.com/EddyVerbruggen/SocialSharing-PhoneGap-Plugin.git
After the plugin is installed, Listing 13.2 shows how to share a story. Listing 13.2. Share a story
1 2 3
$scope.shareStory = function(story) { $cordovaSocialSharing.share(story.title, null, null, story.url); };
share(message, subject, image, link) method of $cordovaSocialSharing service has follow-
ing arguments: • • • •
message - Message of this sharing. subject - Subject of this sharing. image - Image contained in this sharing. link - Link of the shared item.
Figure 13.1 shows the sharing window created by socialSharing plugin. ¹http://ngcordova.com/docs/plugins/socialSharing/
34
Share stories
Figure 13.1. Share a story
6. Publish After the app has been developed and tested, it’s time to publish it. This chapter covers some topics regarding app publishing.
6.1 Icons & splash screens Before the app can be published, we need to replace the default icons and splash screens. Ionic can generate icons and splash screens from source images to create images of various size for each platform. We only need to provide an image for icon and another image for splash screen, then Ionic can generate all necessary images. Source images can be png file, psd file from PhotoShop or ai file from Adobe Illustrator. For icons, the source image should be icon.png, icon.psd or icon.ai file in resources directory of the Ionic project. The icon image should have a size of at least 192x192 px. For splash screens, the source image should be splash.png, splash.psd or splash.ai file in resources directory. The splash screen should have a size of at least 2208x2208 px. Listing 14.1. Generate icons and splash screens
1 2 3 4 5
$ ionic resources --icon $ ionic resources --splash $ ionic resources
Generated icons and splash screens are saved to ios and android sub-directory of resources directory.
36
Publish
Figure 14.1. Generated icons and splash screens
6.2 Deploy to device We can also deploy the app to a device for testing. For iOS, open generated project in platforms/ios directory with Xcode and use Xcode to deploy to device. For Android, open generated project in platforms/android directory with Eclipse or Android Studio to deploy to device.
Publish
37
Ionic CLI command ionic run ios --device and ionic run android --device can also be used to deploy apps to the device. For iOS, ios-deploy¹ needs to be installed using npm.
6.3 View and share with Ionic View We can easily view and share the app with Ionic View. Ionic View is an app created by Ionic which allows users to view Ionic apps without installing them. 1. 2. 3. 4.
Create an account in Ionic.io². Use CLI command ionic upload to upload the app. Install Ionic View from the app store. Log into Ionic View and view the uploaded app.
See Figure 14.2 for the screen-shot of Ionic View. ¹https://github.com/phonegap/ios-deploy ²https://apps.ionic.io
38
Publish
Figure 14.2. Ionic View
You can also share the app using CLI command ionic share . An email will be
Publish
39
sent to the invited user to view the shared app. Invited user can also view the shared app in Ionic View.
7. Thank you Thank you for reading sample chapters of this book. You can purchase the complete book at Leanpub¹.
¹https://leanpub.com/build-mobile-apps-with-ionic-and-firebase