Merge branch 'stage' into stockpile-docs

phonegap · Nov 24, 2017 · 96edf0d · 96edf0d
2 parents 153667c + 93a58ea
commit 96edf0d
Show file tree

Hide file tree

Showing 29 changed files with 4,299 additions and 0 deletions.
diff --git a/docs/2-tutorials/2-develop/stockpile-app/0-index.html.md b/docs/2-tutorials/2-develop/stockpile-app/0-index.html.md
@@ -0,0 +1,38 @@
+---
+title: Adobe Stockpile Sample App
+url: references/stockpile-app
+layout: subpage
+---
+
+The Stockpile App is a sample mobile app written by the Adobe PhoneGap team to help teach developers how to use PhoneGap to build highly performant, fully-featured mobile apps. The Stockpile app allows you to search for images from the [Adobe Stock Photo Library](https://stock.adobe.com/), view details, download, add favorites and more. It was built using the latest web standards and is being provided to developers to use as a reference when creating their own mobile apps.
+
+<img class="mobile-image" src="/images/stockpile/vids/stockpile-run2.gif" alt="Stockpile App"/>
+
+This guide will walk through how to build Stockpile step by step with a series of lessons aimed to teach mobile app development with PhoneGap using a proven technology stack. Before moving on, take a moment to try out the [hosted version of the app here](https://phonegap-stockpile-app.firebaseapp.com/) to see what the end result should look like.
+
+## Technology Stack
+
+The Stockpile app was built using [Framework7 with Vue.js bindings](http://framework7.io/vue/) and the [Adobe Stock API](https://www.adobe.io/apis/creativecloud/stock/) with the [PhoneGap Split View Panel app template](https://github.com/phonegap/phonegap-template-vue-f7-split-panel) base.
+
+<div class="alert--info">**NOTE:** The goal of this guide is to take you through the process of building a full blown mobile app using PhoneGap with some popular tools and frameworks currently available. As such, it is more of an intermediate guide and will assume some knowledge by the developer. We highly recommend keeping the documentation for the other frameworks and tools used open while going through each lesson so you gain the most out of the learning process. There's a list of resources included at the bottom of the page you will find useful throughout this guide.</div>
+
+## Requirements
+
+- A code editor, Chrome browser, and connection to the Internet
+- Node.js 6.x+
+- PhoneGap CLI (npm install -g phonegap@latest)
+
+<div class="alert--tip">**TIP:** Install the [VueJS Devtools Chrome Extension](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd) to help debug your app in the Chrome browser.
+</div>
+
+## Helpful Resources
+
+- [Framework7](https://framework7.io/)
+- [Framework7+Vue Docs](https://framework7.io/vue/)
+- [VueJS Guide](https://vuejs.org/v2/guide/)
+- [Vue PWA Template](https://github.com/vuejs-templates/pwa)
+- [Vue Webpack Template Docs](https://github.com/vuejs-templates/webpack/tree/develop/docs)
+- [Webpack Docs](https://webpack.github.io/docs/)
+- [Demystifying Vue Webpack](https://alligator.io/vuejs/demistifying-vue-webpack/)
+- [Official Apache Cordova Docs](http://cordova.apache.org/docs)
+- [Adobe Stock API](https://www.adobe.io/apis/creativecloud/stock/docs/api/search.html).
diff --git a/docs/2-tutorials/2-develop/stockpile-app/01-project-overview.html.md b/docs/2-tutorials/2-develop/stockpile-app/01-project-overview.html.md
@@ -0,0 +1,98 @@
+---
+title: Project Overview
+url: references/stockpile-app/01-project-overview
+layout: subpage
+---
+
+This app is based on a PhoneGap Framework7 Vue template. The PhoneGap Framework7 Vue templates provide a boilerplate app to help developers get started building mobile apps quickly. There are currently three template layouts to choose from:
+
+1. [Blank](https://www.npmjs.com/package/phonegap-template-vue-f7-blank)
+
+  ![](/images/stockpile/example-blank.png)
+
+1. [Tabs](https://www.npmjs.com/package/phonegap-template-vue-f7-tabs)
+
+  ![](/images/stockpile/example-tabs.png)
+
+1. [Split Panel](https://www.npmjs.com/package/phonegap-template-vue-f7-split-panel)
+
+  ![ios](/images/stockpile/example-split-iOS.png) iOS
+  ![android](/images/stockpile/example-split-android.png) Android
+
+The templates each have a similar project structure, based off the [vue-pwa-webpack template](https://github.com/vuejs-templates/pwa) and are configured with Cordova/PhoneGap, Vue.js, Framework7, Webpack, Babel, ESLint and Hot Reloading as well as Progressive Web App support. They also have unit tests and CSS extraction built-in.
+
+The Adobe Stockpile App uses the Split Panel template and you will learn how to specifically use it to get started in lesson 1.
+
+## Project Structure
+
+Before moving on, below is a quick overview of the project structure you should see. This will be similar for each of the PhoneGap templats, and is a combination of the [vue-pwa-webpack template](https://github.com/vuejs-templates/pwa) and a PhoneGap CLI created project.
+
+A quick note about the contents of each asset is noted in the comments, but you can also refer to the [Vue Webpack template project docs](https://github.com/vuejs-templates/webpack/blob/develop/docs/structure.md) for specific details.
+
+```text
+.
+├── build/                      # webpack config files
+│   └── ...
+├── config/
+│   ├── index.js                # main project config
+│   └── ...
+├── src/
+│   ├── main.js                 # app entry file
+│   ├── routes.js               # defines simple routing between paths and components
+│   ├── App.vue                 # main app component
+│   ├── components/             # ui components
+│   │   └── ...
+│   └── assets/                 # module assets (processed by webpack)
+│       └── ...
+├── static/                     # pure static assets (directly copied)
+├── test/
+│   └── unit/                   # unit tests
+│   │   ├── specs/              # test spec files
+│   │   ├── index.js            # test build entry file
+│   │   └── karma.conf.js       # test runner config file
+│   └── e2e/                    # e2e tests
+│   │   ├── specs/              # test spec files
+│   │   ├── custom-assertions/  # custom assertions for e2e tests
+│   │   ├── runner.js           # test runner script
+│   │   └── nightwatch.conf.js  # test runner config file
+├── .babelrc                    # babel config
+├── .postcssrc.js               # postcss config
+├── .eslintrc.js                # eslint config
+├── .editorconfig               # editor config
+├── config.xml                  # PHONEGAP config file
+├── hooks                       # PHONEGAP hooks folder
+├── platforms                   # PHONEGAP platforms folder
+├── plugins                     # PHONEGAP plugins folder
+├── www                         # PHONEGAP default project folder (build output goes here)
+└── package.json                # build scripts and dependencies
+```
+
+## www
+
+When the project is initially created, the `www` folder will include a sample PhoneGap Hello World application by default. Once you run the build commands however, the `www` will get ovewritten each time. Once built, the `www/index.html` file specifically represents the final template `index.html` for the single page application. During development and builds, Webpack will generate assets, and the URLs for those generated assets will be automatically injected into this index.html template to render the final HTML. DO NOT MODIFY the contents of the `www` folder or `www/index.html` file. All of your updates will be done in the `src` folder instead.
+
+## src/main.js
+
+The main entry point to the app. Contains the overall dependency imports, platform detection code and globals for the app as well as the [Vue initialization](https://vuejs.org/v2/guide/instance.html) code.
+
+## src/index.html
+
+Contains the meta tags for things like Content Security Policy, Progressive Web App elements (meta tags for cross browser PWA support, manifest.json and service-worker.js references and `<noscript>...</noscript>` block etc), the `cordova.js` include and the main `app` div where the app is finally rendered.
+
+## src/App.vue
+
+Defines the overall app UI structure, platform detection code, `backButton` handler and `deviceready` handler.
+
+## src/routes.js
+
+Sets up basic routing for each of the templates. A **route** is what a single page app uses to determine what page to display based on a mapping between a path (URL) and a *.vue component. The `src/components/*` folders contain [single file Vue components](https://vuejs.org/v2/guide/single-file-components.html) which encapsulate the functionality needed to display a view when a route is matched. This includes the UI elements, JavaScript and CSS all in one file.
+
+## About this Guide
+
+The Split Panel template provides a good app structure to get started with since it already includes a navigation bar, some basic views, a side menu and page routing wired up. Since the Stockpile app needs this as well, it's easier to re-use existing pages and content where possible. For each of the views you may notice a similar high-level pattern of changes that need to occur:
+
+1. Update the view routing
+1. Update the UI for the view
+1. Implement the JavaScript for the view updates
+
+<div class="alert--tip">The split panel template automatically expands the left panel into a split view when the app is run on a device larger than a phone. </div>
diff --git a/docs/2-tutorials/2-develop/stockpile-app/1-project-creation.html.md b/docs/2-tutorials/2-develop/stockpile-app/1-project-creation.html.md
@@ -0,0 +1,94 @@
+---
+title: Lesson 1 - Project Creation & Setup
+url: references/stockpile-app/1-project-creation
+layout: subpage
+---
+This lesson provides the steps to create a new PhoneGap project based on a starter app template and contains details about the resulting project structure. Before moving on you will add an icon library and test out the new app to ensure your environment is set up properly.
+
+## Project Creation
+
+1. Open a terminal window and run the `phonegap create` command below, specifying your desired folder location,  package, name and the [phonegap-template-vue-f7-split-panel](https://github.com/phonegap/phonegap-template-vue-f7-split-panel) for the `--template` parameter as shown below:
+
+        phonegap create Stockpile com.phonegap.stockpile Stockpile --template phonegap-template-vue-f7-split-panel
+
+  <div class="alert--tip">PhoneGap provides starter templates and layouts to help you get started building your apps quickly. The templates vary in the types of frameworks and configurations used, some more basic and some fully configured with a build process like Webpack. To create a new PhoneGap project with a template, you specify the `--template` parameter upon project creation. To locate the various templates available, go to [npmjs.org](https://www.npmjs.com/search?q=phonegap:template) and use the search term `phonegap:template`. See the [project overview](/references/stockpile-app/01-project-overview/) for more details about the templates and project structure.
+  </div>
+
+1. Next, navigate into the new Stockpile folder and run the `npm install` command to install the project dependencies:
+
+        cd Stockpile
+        npm install
+
+  <div class="alert--info">**IMPORTANT:** You will be updating the files and folders within the **`src`** folder specifically when going through the lessons in this guide. Do not confuse it with the `www` folder. That folder will be regenerated when the `npm run build` command is used. Refer to the [project overview](/references/stockpile-app/01-project-overview/) for more details.</div>
+
+## Rename the App
+
+1. You're now ready to start editing the project to transform it into your own Stockpile app. Open the root `Stockpile` project folder in your favorite code editor.
+
+1. Begin by providing your app a new name. Open `~src/index.html` and change the `<title>` tag value of **MyApp** to **Stockpile.**
+
+        <title>Stockpile</title>
+
+    <div class="alert--tip">**TIP:** If you're looking for a good code editor check out [Visual Studio Code](https://code.visualstudio.com/).</div>
+
+## Add the Framework7 Icons Library
+
+Framework7 provides just a couple commonly used icons in their default package (back arrow and menu bars), but they also offer a free icon font library to provide additional icons (and iOS specific icons) as you develop your apps. Follow the steps below to install the [Framework7 Icons Font](https://framework7.io/icons/) library.
+
+1. Install the `framework7-icons` package from npm:
+
+        npm install framework7-icons --save
+
+1. Then open `~src/main.js` and add an import for the new icons as shown below just above the routes import:
+
+        // Import the Framework7 Icons
+        import Framework7Icons from 'framework7-icons/css/framework7-icons.css';
+
+        // Import Routes
+        import Routes from './routes';
+
+<div class="alert--info">**Note:** This app only uses a couple of icons, but since this is a guide to building a mobile app, it's important to know there are icon font libraries available to you. There's also a free [Material Icons](https://material.io/icons/) library you can check out if you're interested in using material design specific icons. You could even include both icon font libraries with a conditional icon that used either the iOS or the Material design version. For more information about how to do this, and using icons with Framework7 in general, see the [Framework7 docs](http://framework7.io/vue/icon.html). This app did not need that extensive of a solution, and in the interest of performance, just the Framework7 Icons library was included. </div>
+
+## Run it!
+
+Since this app was built based on webpack, it can be run in **development mode** or **production mode**. While building the app, it's easiest to run it in development mode and test it in the browser as long as possible to develop the majority of the functionality until device-specific testing is needed.
+
+### Development mode
+
+Open your terminal and start the development server with the following `npm` command:
+
+        npm run dev
+
+The app will open up in your browser at `localhost:8080` (or you can manually open it there).  When the app is run in development mode in the browser, it should appear like the screenshots below, which is essentially the [PhoneGap Default Split Panel](https://github.com/phonegap/phonegap-template-vue-f7-split-panel/) app renamed at this point.
+
+![](/images/stockpile/run-browser-lesson1.png)
+
+You can take advantage of the real-time compiling and hot reloading while running in `dev` mode to speed up your development time as you work through the lessons.
+
+### Production mode
+
+Build in "production mode" when you're ready to start actually testing your app on a device or simulator. To build it for production mode, use the `build` run target:
+
+         npm run build
+
+<div class="alert--tip">Specific details about the differences between the `dev` and `build` mode can also be found [here](https://github.com/vuejs-templates/webpack/blob/develop/docs/commands.md).</div>
+
+Once the build is complete, you can then run the normal `phonegap` and `cordova` commands to actually deploy the package to an ios or android target using:
+
+         phonegap run ios
+         phonegap run android
+
+After the `build` command, you could also use the [`phonegap serve`](http://docs.phonegap.com/getting-started/4-preview-your-app/cli/) command to serve the app for use by the [PhoneGap Developer App](http://docs.phonegap.com/getting-started/2-install-mobile-app/) running on a device.
+
+         phonegap serve
+
+<div class="alert--tip">The last option with `phonegap serve` is particularly useful for debugging [Progressive Web Apps](/references/stockpile-app/911-pwa-features). </div>
+
+Open the Chrome devtools and use the mobile emulation button to try out different device simulations. You'll need to reload the page when switching between iOS and Android to see the stylesheets applied.
+
+![](/images/stockpile/run-browser-ios.png)
+![](/images/stockpile/run-browser-android.png)
+
+## ESLint tips
+
+The Vue template this app is based on automatically defaults to the [`semistandard` ESLint option,](https://github.com/vuejs-templates/webpack/blob/develop/docs/linter.md) which is the [JavaScript `standard` style](https://standardjs.com/) extended to include semicolons. Take a few minutes to familiarize yourself with [the rules](https://standardjs.com/) if you're not familiar already, to help avoid compiler errors and speed up your development time while working through this guide.