Merge pull request #378 from apollographql/docs

Docs

.gitignore

@@ -50,3 +50,13 @@ jspm_packages
 # Packages lock
 package-lock.json
 yarn.lock
+
+.DS_Store
+Thumbs.db
+db.json
+*.log
+
+docs/public/*
+!docs/public/_redirects
+
+.idea/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "themes/meteor"]
+	path = themes/meteor
+	url = https://github.com/meteor/hexo-theme-meteor.git
+[submodule "docs/themes/meteor"]
+	path = docs/themes/meteor
+	url = https://github.com/meteor/hexo-theme-meteor.git

docs/README.md

@@ -0,0 +1,10 @@
+# docs
+
+To run:
+
+```
+git submodule init
+git submodule update
+npm install
+npm start
+```

docs/_config.yml

@@ -0,0 +1,108 @@
+# Hexo Configuration
+## Docs: http://hexo.io/docs/configuration.html
+## Source: https://github.com/hexojs/hexo/
+
+# Site
+title: Use GraphQL with Angular
+propertytitle: Apollo Angular Docs
+subtitle: A guide to using the Apollo GraphQL Client with Angular.
+description:
+author:
+language:
+timezone:
+versions:
+  - '1'
+sidebar_categories:
+  null:
+    - index
+    - initialization
+    - example-schema
+  Usage:
+    - queries
+    - mutations
+    - receiving-updates
+    - cache-updates
+    - multiple-clients
+  Recipes:
+    - auth
+    - pagination
+    - optimistic-ui
+    - fragments
+    - prefetching
+    - redux
+    - server-side-rendering
+    - angular-cli
+    - ahead-of-time
+    - webpack
+    - typescript
+github_repo: apollographql/apollo-angular
+content_root: docs/source
+
+social_links:
+  github: 'https://github.com/apollographql'
+  twitter: '@apollographql'
+
+# API keys
+apis:
+  segment: wgrIo8Bul0Ujl8USETG3DB6hONdy4kTg
+  gtm: GTM-PNFDVBB
+
+# URL
+## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
+url: https://www.apollographql.com/docs/angular
+root: /docs/angular/
+permalink: :year/:month/:day/:title/
+permalink_defaults:
+
+# Directory
+source_dir: source
+public_dir: public/docs/angular
+tag_dir: tags
+archive_dir: archives
+category_dir: categories
+code_dir: downloads/code
+i18n_dir: :lang
+skip_render:
+
+# Writing
+new_post_name: :title.md # File name of new posts
+default_layout: post
+titlecase: false # Transform title into titlecase
+external_link: true # Open external links in new tab
+filename_case: 0
+render_drafts: false
+post_asset_folder: false
+relative_link: false
+future: true
+highlight:
+  enable: true
+  line_number: true
+  auto_detect: true
+  tab_replace:
+
+# Category & Tag
+default_category: uncategorized
+category_map:
+tag_map:
+
+# Date / Time format
+## Hexo uses Moment.js to parse and display date
+## You can customize the date format as defined in
+## http://momentjs.com/docs/#/displaying/format/
+date_format: YYYY-MM-DD
+time_format: HH:mm:ss
+
+# Pagination
+## Set per_page to 0 to disable pagination
+per_page: 10
+pagination_dir: page
+
+# Extensions
+## Plugins: http://hexo.io/plugins/
+## Themes: http://hexo.io/themes/
+theme: meteor
+
+# Deployment
+## Docs: http://hexo.io/docs/deployment.html
+deploy:
+  type:

docs/assets/theme-colors.less

@@ -0,0 +1 @@
+@color-primary: #22A699;

docs/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "hexo-site",
+  "version": "0.0.0",
+  "private": true,
+  "hexo": {
+    "version": "3.3.8"
+  },
+  "dependencies": {
+    "handlebars": "^4.0.5",
+    "hexo": "3.3.8",
+    "hexo-generator-archive": "^0.1.2",
+    "hexo-generator-category": "^0.1.2",
+    "hexo-generator-index": "^0.1.2",
+    "hexo-generator-tag": "^0.1.1",
+    "hexo-renderer-ejs": "^0.1.0",
+    "hexo-renderer-less": "^0.2.0",
+    "hexo-renderer-marked": "^0.2.4",
+    "hexo-server": "^0.1.2",
+    "lodash": "^4.13.1",
+    "showdown": "^1.4.2"
+  },
+  "scripts": {
+    "start": "hexo serve",
+    "build": "hexo generate"
+  }
+}

docs/public/_redirects

@@ -0,0 +1 @@
+/ /docs/angular

docs/source/ahead-of-time.md

@@ -0,0 +1,39 @@
+---
+title: Ahead-of-Time Compilation
+---
+
+<h2 id="overview">Overview</h2>
+
+Before the browser can render the application, the components and templates must be converted to executable JavaScript by the *Angular compiler*.
+
+There are two ways to compile the Application: *Just-in-Time (JiT)* and *Ahead-of-time (AoT)*.
+
+<h3 id="overview-jit">Just-in-Time (JiT)</h3>
+
+With JiT, you compile the app in the browser, at runtime, as the application loads.
+
+As follows in [Angular Documentation](https://angular.io/docs/ts/latest/cookbook/aot-compiler.html):
+
+> JiT compilation incurs a runtime performance penalty. Views take longer to render because of the in-browser compilation step. The application is bigger because it includes the Angular compiler and a lot of library code that the application won't actually need. Bigger apps take longer to transmit and are slower to load.
+
+
+<h3 id="overview-aot">Ahead-of-Time (AoT)</h3>
+
+With AoT, the browser loads code of the application that has been pre-compiled at build time. It means the application can render immediately.
+
+Other benefits:
+
+- Faster rendering
+- Fewer asynchronous requests
+- Smaller Angular framework download size
+- Detect template errors earlier
+- Better security
+
+
+<h2 id="compile-aot">Compile with AoT</h2>
+
+To learn more about Ahead-of-Time compilation, please take a look at [the chapter "Ahead-of-Time Compilation"](https://angular.io/docs/ts/latest/cookbook/aot-compiler.html) on *angular.io* that explain all about AoT.
+
+<h2 id="example">An Example</h2>
+
+We prepared [an example](https://github.com/apollographql/apollo-angular/tree/master/examples/hello-world) that shows how to use *Ahead-of-Time* compilation with *Apollo*.

docs/source/angular-cli.md

@@ -0,0 +1,41 @@
+---
+title: Angular CLI
+---
+
+<h2 id="installation">Installation</h2>
+
+To get started with Apollo and Angular install few needed packages. Take a look at [Installation](initialization.html#installation) section.
+
+<h2 id="initialization">Initialization</h2>
+
+Take a look at [Initialization](initialization.html) section.
+
+
+<h2 id="proxy">Proxy</h2>
+
+If your GraphQL endpoint lives under different host with Angular CLI you can easily define proxy configuration.
+
+Take for example `api.example.com/graphql`:
+
+```json
+{
+  "/graphql": {
+    "target": "http://api.example.com"
+  }
+}
+```
+
+Create a json file (`proxy.config.json` for example) with that configuration.
+
+To run server use `--proxy-config` option:
+
+```bash
+ng serve --proxy-config <path to file>
+```
+
+An example:
+
+```bash
+ng serve --proxy-config proxy.config.json
+```
+

docs/source/auth.md

@@ -0,0 +1,51 @@
+---
+title: Authentication
+order: 20
+---
+
+Some applications don't deal with sensitive data and have no need to authenticate users, but most applications have some sort of users, accounts and permissions systems. If different users have different permissions in your application, then you need a way to tell the server which user is associated with each request. Over HTTP, the most common way is to send along an authorization header.
+
+Apollo Client has a pluggable [network interface](/core/network.html) that lets you modify requests before they are sent to the server.
+That makes it easy to add a network interface middleware that adds the `authorization` header to every HTTP request:
+
+```ts
+import { ApolloClient, createNetworkInterface } from 'apollo-client';
+
+const networkInterface = createNetworkInterface('/graphql');
+
+networkInterface.use([{
+  applyMiddleware(req, next) {
+    if (!req.options.headers) {
+      req.options.headers = {};  // Create the header object if needed.
+    }
+    // get the authentication token from local storage if it exists
+    req.options.headers.authorization = localStorage.getItem('token') || null;
+    next();
+  }
+}]);
+
+const client = new ApolloClient({
+  networkInterface,
+});
+```
+
+The example above shows how to send an authorization header along with every request made. The server can use that header to authenticate the user and attach it to the GraphQL execution context, so resolvers can modify their behavior based on a user's role and permissions.
+
+Another common way of adding credentials for authentication to a request is to use cookies. GitHunt uses GitHub's OAuth authentication, and stores the token in a cookie. Cookies can be added to every request with the `credentials` option (the network interface simply passes that option on to the [fetch](https://github.com/github/fetch) call):
+
+```ts
+const client = new ApolloClient({
+  networkInterface: createNetworkInterface({
+    uri: '/graphql',
+    opts: {
+      credentials: 'same-origin'
+    },
+  })
+});
+```
+
+<h3 id="login-logout">Login and logout</h3>
+
+In order for the examples in the previous section to work properly, your application has to obtain authentication credentials (for example a JWT) when the user logs in, store it somehow (for example in LocalStorage) and reload the parts of the UI that are different for logged-in users. It is also equally important to clear the token from local storage when the user logs out and clear ApolloClient's store if it contains sensitive information.
+
+The easiest way to ensure that the UI and store state reflects the current user's permissions is to call `Apollo.getClient().resetStore();` after the login or logout actions have completed. This will cause the store to be cleared and all queries to be refetched. Another option is to reload the page, which will have a similar effect.