Merge pull request #692 from mlabieniec/docs/angular-updates

update angular docs

.github/CODEOWNERS

@@ -1,2 +1,11 @@
 /docs/ @mbahar
-/packages/aws-amplify-angular/ @haverchuck
+/packages/aws-amplify-angular/ @haverchuck @richardzcode
+/packages/aws-amplify/src/Auth/ @richardzcode @powerful23
+/packages/aws-amplify/src/Analytics/ @powerful23 @richardzcode
+/packages/aws-amplify-react/ @powerful23
+/packages/aws-amplify/src/API/ @elorzafe
+/packages/aws-amplify/src/Cache/ @elorzafe @nidsharm
+/packages/aws-amplify/src/Storage/ @nidsharm
+/packages/aws-amplify/src/PubSub/ @manueliglesias @elorzafe
+/packages/amazon-cognito-identity-js/ @yuntuowang
+/.github/ @mlabieniec

README.md

@@ -36,7 +36,7 @@ Our default implementation works with Amazon Web Services (AWS), but AWS Amplify
   - [React Native Development](#react-native-development)
 * [Documentation](https://aws.github.io/aws-amplify)
 * [Examples](#example)
-  - [1. Collect user session metrics.](#1-collect-user-session-metrics)
+  - [1. Collect user session metrics](#1-collect-user-session-metrics)
   - [2. Add Authentication](#2-add-authentication-to-your-app)
   - [3. Sign HTTP requests](#3-sign-http-requests)
   - [4. Upload and Download public or private content](#4-upload-and-download-public-or-private-content)
@@ -48,15 +48,24 @@ Our default implementation works with Amazon Web Services (AWS), but AWS Amplify
 
 For creating cloud powered Web apps with JavaScript, AWS Amplify is available as `aws-amplify` package on [npm](https://www.npmjs.com/)
 
-```
+```bash
 $ npm install aws-amplify --save
 ```
 
 If you are developing a [React](https://github.com/facebook/react/) app, you can install an additional package `aws-amplify-react` containing [Higher Order Components](https://reactjs.org/docs/higher-order-components.html):
 
-```
+```bash
+$ npm install aws-amplify --save
 $ npm install aws-amplify-react --save
 ```
+
+If you are developing an [Angular](https://github.com/angular/angular) app, you can install an additional package `aws-amplify-angular`. This package contains an [Angular module](https://docs.angularjs.org/api/ng/function/angular.module) with a [provider and components](https://aws.github.io/aws-amplify/media/angular_guide):
+
+```bash
+$ npm install aws-amplify --save
+$ npm install aws-amplify-angular --save
+```
+
 #### Visit our [Installation Guide for Web](https://aws.github.io/aws-amplify/media/install_n_config?platform=javascript) to start building your web app.  
 
 ### React Native Development
@@ -96,7 +105,7 @@ Analytics.record('myCustomEvent');
 
 ### 2. Add Authentication to your App
 
-Adding authentication to your React Native app is as easy as wrapping your app's main component with our `withAuthenticator` higher order component. AWS Amplify will provide you customizable UI for common use cases such as user registration and login.
+Adding authentication to your React or React Native app is as easy as wrapping your app's main component with our `withAuthenticator` higher order component. AWS Amplify will provide you customizable UI for common use cases such as user registration and login.
 
 ```jsx
 ...
@@ -110,6 +119,39 @@ Amplify.configure(aws_exports);
 export default withAuthenticator(App);
 ```
 
+To add authentication to your Angular app you can also use the built-in service provider and components:
+
+```js
+// main.ts
+import Amplify from 'aws-amplify';
+import awsmobile from './aws-exports';
+Amplify.configure(awsmobile); // or manual configuration, see the docs
+...
+// app.component.ts
+import { AmplifyService }  from 'aws-amplify-angular';
+
+...
+
+constructor( public amplify:AmplifyService ) {
+  // handle auth state changes
+  this.amplify.authStateChange$
+      .subscribe(authState => {
+        this.authenticated = authState.state === 'signedIn';
+        if (!authState.user) {
+          this.user = null;
+        } else {
+          this.user = authState.user;
+        }
+    });
+}
+
+// app.component.html
+<amplify-authenticator></amplify-authenticator>
+
+```
+
+#### See our [Angular Guide](https://aws.github.io/aws-amplify/media/angular_guide) for more details on Angular setup and usage.
+
 #### See our [Authentication Developer Guide](https://aws.github.io/aws-amplify/media/authentication_guide) for detailed information. 
 
 ### 3. Sign HTTP requests

docs/media/angular_guide.md

@@ -10,8 +10,8 @@ AWS Amplify provides Angular Components with `aws-amplify-angular` npm package.
 Install `aws-amplify` and `aws-amplify-angular` npm packages into your Angular app.
 
 ```bash
-$ yarn add aws-amplify
-$ yarn add aws-amplify-angular
+$ npm install --save aws-amplify # or yarn add aws-amplify
+$ npm install --save aws-amplify-angular # or yarn add aws-amplify-angular
 ```
 
 ### Setup
@@ -24,10 +24,11 @@ Following commands will enable Auth category and will create `aws-exports.js` co
 $ npm install -g awsmobile-cli
 $ awsmobile init
 $ awsmobile user-signin enable
-$ awsmobile push #Update your backend
+$ awsmobile user-files enable
+$ awsmobile push # Update your backend
 ```
 
-After creating your backend, the configuration file is copied to `/awsmobilejs/#current-backend-info/aws-exports.js`, and optionally to your source folder if you have identified a source folder location in `awmobile init` command.
+After creating your backend, the configuration file is copied to `/awsmobilejs/#current-backend-info/aws-exports.js`, and the source folder you have identified in the `awmobile init` command.
 
 To import the configuration file to your Angular app, you will need to rename `aws_exports.js` to `aws_exports.ts`. Alternatively, you can create a `yarn start` command in your `package.json`.
 ```js
@@ -37,7 +38,7 @@ To import the configuration file to your Angular app, you will need to rename `a
 }
 ```
 
-Import configuration file and load it in your `main.ts`, which is the entry point of your Angular application. 
+Import the configuration file and load it in your `main.ts`, which is the entry point of your Angular application. 
 
 ```js
 import Amplify from 'aws-amplify';
@@ -52,7 +53,7 @@ When working with underlying `aws-js-sdk`, the "node" package should be included
 }
 ```
 
-If you are developing locally using a `yarn link`, you will need to modify `.angular-cli.json` :
+NOTE: If you are developing locally (not with npm packages, using a `yarn link`), you will need to modify `.angular-cli.json` :
 
 ```js
 "defaults": {
@@ -86,9 +87,11 @@ import { AmplifyAngularModule, AmplifyService } from 'aws-amplify-angular';
 });
 ```
 
+NOTE: the service provider is optional. You can import the core categories normally i.e. `import { Analytic } from 'aws-amplify'` or create your own provider. The service provider does some work for you and exposes the categories as methods. The provider also manages and dispatches authentication state changes using observables which you can subscribe to within your components (see below).
+
 ## Using Amplify Service
 
-AmplifyService is a provider in your Angular app, and it provides AWS Amplify core functions through dependency injection.
+AmplifyService is a provider in your Angular app, and it provides AWS Amplify core categories through dependency injection.
 
 ### Using Dependency Injection
 
@@ -130,11 +133,11 @@ export class AppComponent {
 
       /** now you can access category APIs:
        * this.amplifyService.auth();          // AWS Amplify Auth
-      * this.amplifyService.analytics();     // AWS Amplify Analytics
-      * this.amplifyService.storage();       // AWS Amplify Storage
-     * this.amplifyService.api();           // AWS Amplify API
-     * this.amplifyService.cache();         // AWS Amplify Cache
-     * this.amplifyService.pubsub();        // AWS Amplify PubSub
+       * this.amplifyService.analytics();     // AWS Amplify Analytics
+       * this.amplifyService.storage();       // AWS Amplify Storage
+       * this.amplifyService.api();           // AWS Amplify API
+       * this.amplifyService.cache();         // AWS Amplify Cache
+       * this.amplifyService.pubsub();        // AWS Amplify PubSub
      **/
   }
 

docs/media/authentication_guide.md

@@ -418,7 +418,7 @@ const oauth = {
         // Indicates if the data collection is enabled to support Cognito advanced security features. By default, this flag is set to true.
         AdvancedSecurityDataCollectionFlag : true
     }
-}
+}
 
 Amplify.configure({
     Auth: {

docs/media/install_n_config.md

@@ -14,6 +14,7 @@ Installing AWS Amplify involves installing our client libraries from `npm`, and
     <li class="tab-link javascript current" data-tab="javascript">JavaScript</li>
     <li class="tab-link react" data-tab="react">React</li>
     <li class="tab-link react-native" data-tab="react-native">React Native</li>
+    <li class="tab-link angular" data-tab="angular">Angular</li>
 </ul>
 <div id="javascript" class="tab-content current">
 For JavaScript web development, regardless of the frontend framework used, `aws-amplify` package provides core APIs
@@ -39,6 +40,17 @@ npm install aws-amplify
 npm install aws-amplify-react-native
 ```
 </div>
+<div id="angular" class="tab-content">
+For Angular, in addition to `aws-amplify`, we provide an Angular module with a service provider and components in the `aws-amplify-angular` package
+```bash
+npm install aws-amplify
+```
+```bash
+npm install aws-amplify-angular
+```
+
+See the [Angular Guide](https://aws.github.io/aws-amplify/media/angular_guide).
+</div>
 </div>
 
 ## Set up your Backend

docs/media/quick_start.md

@@ -15,6 +15,7 @@ AWS Amplify can be used with any JavaScript front-end library. In addition, for
 <ul class="tabs">
     <li class="tab-link current react" data-tab="react">React</li>
     <li class="tab-link react-native" data-tab="react-native">React Native</li>
+    <li class="tab-link angular" data-tab="angular">Angular</li>
 </ul>
 <div id="react" class="tab-content current">
 If you have an existing React application you can skip this section. Otherwise, please use  [Create React App](https://github.com/facebookincubator/create-react-app) to boostrap your application.
@@ -48,6 +49,15 @@ Then run your app:
 $ react-native run-ios  # or run-android
 ```
 </div>
+<div id="angular" class="tab-content">
+If you have an existing Angular application you can skip this section. Otherwise, you can use the [angular-cli](https://github.com/angular/angular-cli) to bootstrap a new angular app:
+
+```bash
+$ npm install -g @angular/cli
+$ ng new myAmplifyProject
+$ cd myAmplifyProject
+```
+</div>
 </div>
 
 ## Install AWS Amplify 
@@ -57,27 +67,28 @@ AWS Amplify is available as an npm package. Run the following commands at the ro
 <ul class="tabs">
     <li class="tab-link react current" data-tab="react">React</li>
     <li class="tab-link react-native" data-tab="react-native">React Native</li>
+    <li class="tab-link angular" data-tab="angular">Angular</li>
 </ul>
 <div id="react" class="tab-content current">
 
 ```bash
-npm install aws-amplify
+$ npm install --save aws-amplify
 ```
 
 On a React app, in addition to `aws-amplify`, we provide helpers and higher order components that are packaged in `aws-amplify-react`.
 
 ```bash
-npm install aws-amplify-react #optional
+$ npm install --save aws-amplify-react # optional HOCs
 ```
 </div>
 <div id="react-native" class="tab-content">
 ```bash
-npm install aws-amplify
+$ npm install --save aws-amplify
 ```
 For React Native, in addition to `aws-amplify`, we provide React Native specific components in `aws-amplify-react-native` package.
 
 ```bash
-npm install aws-amplify-react-native
+$ npm install --save aws-amplify-react-native
 ```
 
 ### Linking native libraries for React Native
@@ -99,6 +110,19 @@ $ react-native link amazon-cognito-identity-js
 ```
 
 
+</div>
+<div id="angular" class="tab-content">
+```bash
+$ npm install --save aws-amplify
+```
+
+In addition to `aws-amplify` core, you can install our angular module which provides a service provider, helpers and components:
+
+```bash
+$ npm install --save aws-amplify-angular
+``` 
+
+See the [angular guide](https://aws.github.io/aws-amplify/media/angular_guide) for details and usage.
 </div>
 </div>