Skip to content

Commit

Permalink
[WIP] 2.0 docs (#2324)
Browse files Browse the repository at this point in the history
* More edits

* Create migration.md

* Update _config.yml

Add migration guide

* Update migration.md

* Fix 'response' typo & add hyphen to refer to possible response types

* Update simple-example.md

fixed spelling

* Update simple-example.md

* Document `.graphql` file imports in Meteor

* docs(fragments): Document import syntax

Add `import` syntax mention in the `fragments` section
Link to `webpack` page where further usage / details are provided

Closes 185

* Sanitize JSON.stringify output to prevent XSS

See these docs for rationale:
http://redux.js.org/docs/recipes/ServerRendering.html#security-considerations|

* Update fragments.md

* Update subscriptions.md

Subscription client should accept a websocket address, not an http

* docs(webpack): update webpack config to Webpack 2

* Change sketch to snack

* add docs for variables argument in docs of data.refetch

* Fix a typo

* Fix typo

immeadiately => immediately

* Fix links to server side rendering recipe

These had an extra hash in front of them

* Just Angular

* Adds a minimal mention of Direct Cache Access

And links to the relevant bit in the Vanilla JS section.

* Adds a simple example

* Update index.md

* Fix SSR link

* Use fetchPolicy for legacy forceFetch

* Changed link to point at the more relevant docs

* Fleshed out the example a bit more

* documented code for subscriptions in Meteor

* Update submodule to 1.0.3

* chore(package): update dependencies

https://greenkeeper.io/

* Revert "Update all dependencies 🌴"

* Force fetch

* Fix broken SubscriptionsServer link

* fix(package): update hexo to version 3.3.5

https://greenkeeper.io/

* Add docsearch

* Add instructions for fragment matcher

* Go back to Apollo theme

* Revert "Update hexo to the latest version 🚀"

* Upgrade hexo, fix lines

* Replace `createMeteorNetworkInterface` in `meteor.md`

`createMeteorNetworkInterface` --> `createNetworkInterface` to match function name in source code

* Revert "Replace `createMeteorNetworkInterface` with `createNetworkInterface` in `meteor.md`"

* Update api-queries.md

* Update initialization.md

* Add docs for the exposure of 'dataIdFromObject' and 'dataId'

* Add docs for the exposure of 'dataIdFromObject' and 'dataId'

* Only document dataIdFromObject

* Update fetchMore docs

Check for `fetchMoreResult`, not `fetchMoreResult.data`.

* Update subscriptions.md

* Update docs about update

* Update network.md

* Fix Example

* update mutations.md formatting

Just a quick change to the "multiple mutations" code snippet, to match the formatting style of other code snippets.

* chore(package): update typedoc to version 0.7.0

https://greenkeeper.io/

* Fixed two misspellings

* chore(submodule): update to latest

* docs(subscriptions): updated subscriptions docs

* fix typo

* Clarify createApolloServer

* Fix missing word

* Update auth.md

I think it will be really helpful to mention that `withApollo` HOC is needed to access `client`.

* add missing ApolloClient import

* Fix typos

availble -> available, respositories -> repositories

* Update read-and-write.md

* minor typo

* changes per @rdickert comments on #274

* add ts typings

* Use correct property name in how-it-works.md 

The documentation states that the property is called dataIdFromObject, but the example uses dataFromObjectId instead.
When trying it out, it did work with dataIdFromObject, but not with dataFromObjectId.

* docs cleanup + additions for parsed afterware response

* Update network.md

* Make language a bit clearer

* Printer is no longer in graphql-tag

apollographql/graphql-tag#54

* GTM

* Update theme

* Add GTM

* Updated incorrect link to Mutations: Update

* Document the expected updateQuery return value

By specifying that it should have the same shape as the original query data.

* Update subscriptions.md

* subscribeToMore returns unsubscribe handler

* subscribeToMore returns unsubscribe handler

>@deep-c It's not defined because you're not actually getting an observable back. Apollo Client subscribes to it for you, so all you get back is actually the unsubscribe handle. So if you call this.subscription() it will unsubscribe. Maybe the variable name I chose in GitHunt-React isn't great 😄 . Would be better to call it unsubscribeHandle or something.

#1145 (comment)

* Fix missing variables in docs for refetchQueries

* Fix typo

* Add an example of a custom network interface

* Update network.md

* Syntax highlighting

Sorry, just realized I left off the js syntax highlighting

* - Adds intro text

* - Adds intro text

* - Adds queries
- Adds resolverCode

* - Adds queries
- Adds resolverCode

* Update partial-data.md

- Adds code example
- Fixes query
- Fixes wordings

* - Changes some wordings

* - Changes some wordings
- Adds paragraph about query batching

* - Changes wording scene to view

* - Adds link to custom resolvers

* - Changes title of the page
- Changes some wordings
- Adds link to BatchedNetworkInterface API docs

* - Applies suggested changes
- Adds destructuring for better readability

* Change the endpoint URI to the less misleading one

People don't usually use `http://localhost:3000/` as their endpoint for graphql,
I think it might be more understandable what it is if we use `http://localhost:3000/graphql` as example.

* Only send request cookie rather than full headers (See #228)

* Fix syntax error in fetchMore example

* Added batchMax to the Query batching explanation.

* tell typedoc to ignore compiler errors

* Fix broken `config.options` links for Queries and Mutations

* Fix broken generic `config.options` link

* Add documentation for the new connection directive

* Bump Node version to try to make CircleCI tests pass

* Update api-server.md

Added some corrections.

* Fix unexpected token error in example code

* Remove inaccurate part about parsed results in afterware

* Update network.md

Removing not necessary else on example code.

* Fixed link to angular page

Link pointed to /angular, which returns a 403

* Fix broken link in simple-example

* fixed typo in api-mutations.md

Changed "excepted" to "accepted".

* Update for new filter argument

* Update cache-updates.md

* Typo for Hello World link

* fix(package): update hexo to version 3.3.8

* fix(package): update hexo to version 3.3.8

* added docs for static typing (#258)

* added docs for static typing

* update from feedback

* spelling

* update class for flow since it can infer

* Improve customResolvers documentation

Add note about having to be the same data, add note about where to get `__typename`, improve overall documentation

* mention that options.context can be a function

* Minor typo fix

* Add unit of time for batchInterval in query batching description

* Remove wording about "just like above"

The previous example is actually only implementing `optimisticResponse` but then the next example implements `update` as well as `optimisticResponse`, and I found the wording to be a bit confusing around this. Do we need to implement `update` as well as `optimisticResponse` as the example shows for adding to a list? If so, the wording was incorrect. If not, then it'd be ideal to give an example where only `optimisticResponse` is required for adding to a list.

I'm currently assuming that the wording was actually slightly off, and that `update` was in fact necessary, in which case we can just remove the bit about `update` not being required.

* fix example; cursor is not available on root

* Update pagination.md

* Change "Expo Sketch" to "Expo Snack"

* Update SSR for React docs to reflect newest version of React Router

* Add relevant comment on routes file

* Add link to FuseBox plugin

* Fix createMeteorNetworkInterface in SSR section

* Fix typo in optimistic-ui.md

* Add gql to the list of imports

gql is used to create the graphql query for the Profile component so it has to be imported to work.

* fixed typo, sentence rewording in query-splitting

* update docs: PropTypes is now a separate package

* Query docs: PropTypes is now a separate package

* Updated simple-example.md

Move to the updated link on howtographql.com as learnapollo.com is deprecated. Please let me know if I need to change the label as well or if this is not relevant.

* Update SSR doc based on feedback.

* StaticRouter now wrapped in ApolloProvider, and made routes example more specific

* Update simple-example.md

Change 2nd tutorial title from "Learn Apollo" to "How to GraphQL" as the prior is deprecated.

* Fixed small typo in example

* Update index.md

Move to the updated link on howtographql.com as learnapollo.com is deprecated.

* adding a super simple client/server example

This repo is just a simple playground for GraphQL n00bs like me. It's only `client.js` and `server.js` both under 50 lines.

Having a minimalist sandbox like this helped me wrap my mind around Apollo, before I started adding all the ceremony that comes along with a UI and database.

Thanks!

* Small typo in refetchQueries example

Small typo in refetchQueries example. The variable name is incorrect in the mutation of refetchQueries example.

* Add slack button

* try edit

* Try changing versions

* Fix outdated queryDeduplication docs

* doc/link formatting

* forceFetch -> fetchPolicy

change `forceFetch: true` to `fetchPolicy: 'network-only'`

* Sync the SSR doc with the newest update added to the GitHunt app, which now uses React Router v4

* Add package lock

* Fix internal link

* move to core-docs

* adjust config and fix jsdoc

* track public

* Add docs for graphql-tag precompilation with babel (#292)

* Add rootEl const to redux.md example code (#293)

In your DOM rendering, you threw in rootEl, but rootEl was never defined. Assuming the ID is "root", I added a const that pointed to that div/element.

`const rootEl = document.querySelector("#root");`

* Update index.md (#295)

* Update auth.md (#296)

* fragment -> fragments (#297)

The component field is named `fragments`, not `fragment`.

* Add React native case (#299)

* docs(fragment matcher): added build script, revised docs for 2.0 (#302)

* Update using-with-types.md (#298)

* add note about refetch variables (#300)

add brief note to clear any variables that were set before for any query. This is helpful when you want to omit a variable from the query that was set before. e.g in case of filters you might want to clear previous filter variable but by not passing that variable will result in picking the old value.

* Docs reorg (#2339)

* start reorg

* reorg of docs for test deploy [NOT READY]

* remove built docs

* update gitignore

* Fix submodule path

* Fix submodule issues
  • Loading branch information
James Baxley committed Oct 19, 2017
1 parent d1be76a commit 816a61d
Show file tree
Hide file tree
Showing 56 changed files with 6,167 additions and 0 deletions.
7 changes: 7 additions & 0 deletions .gitignore
Expand Up @@ -45,3 +45,10 @@ yarn.lock

# npm
package-lock.json

# docs
db.json
*.log
docs/public/*
!docs/public/_redirects
.idea/
3 changes: 3 additions & 0 deletions .gitmodules
@@ -0,0 +1,3 @@
[submodule "docs/themes/meteor"]
path = docs/themes/meteor
url = https://github.com/meteor/hexo-theme-meteor.git
14 changes: 14 additions & 0 deletions docs/README.md
@@ -0,0 +1,14 @@
# docs

[![Greenkeeper badge](https://badges.greenkeeper.io/apollographql/core-docs.svg)](https://greenkeeper.io/)

To run:

```
git submodule init
git submodule update
cd code && npm install
cd ..
npm install
npm start
```
125 changes: 125 additions & 0 deletions docs/_config.yml
@@ -0,0 +1,125 @@
# Hexo Configuration
## Docs: http://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Apollo Client Guide
propertytitle: Using GraphQL with Apollo Client
subtitle: React Guide
description: A guide to using the Apollo GraphQL Client with React.
author:
language:
timezone:
versions:
- '1'

# This setting also defines the page order used to generate the Previous/Next links at the bottom of each page
sidebar_categories:
# Basics
null:
- index
- basics/integrations
- basics/setup
- basics/queries
- basics/mutations
- basics/network-layer
- basics/error-handling
- basics/fragments
- basics/subscriptions
Features:
- features/changelog
- features/caching
- features/developer-tooling
- features/network-customization
- features/optimistic-ui
- features/react-native
- features/static-typing
Recipes:
- recipes/authentication
- recipes/babel
- recipes/meteor
- recipes/pagination
- recipes/prefetching
- recipes/query-splitting
- recipes/server-side-rendering
- recipes/simple-example
- recipes/webpack
# - recipes/client-side-data
# - recipes/using-with-rest
# - recipes/offline
# - recipes/custom-fetching
Reference:
- reference/index


github_repo: apollographql/apollo-client
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/react
root: /docs/react/
permalink: :year/:month/:day/:title/
permalink_defaults:

# Directory
source_dir: source
public_dir: public/docs/react
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:
1 change: 1 addition & 0 deletions docs/assets/theme-colors.less
@@ -0,0 +1 @@
@color-primary: #22A699;
23 changes: 23 additions & 0 deletions docs/package.json
@@ -0,0 +1,23 @@
{
"name": "hexo-site",
"version": "0.0.0",
"private": true,
"hexo": {
"version": "3.3.8"
},
"dependencies": {
"hexo": "3.3.8",
"hexo-generator-archive": "^0.1.2",
"hexo-generator-category": "^0.1.2",
"hexo-generator-index": "^0.2.0",
"hexo-generator-tag": "^0.2.0",
"hexo-renderer-ejs": "^0.2.0",
"hexo-renderer-less": "^0.2.0",
"hexo-renderer-marked": "^0.2.4",
"hexo-server": "^0.2.0"
},
"scripts": {
"build": "hexo generate",
"start": "hexo serve"
}
}
1 change: 1 addition & 0 deletions docs/public/_redirects
@@ -0,0 +1 @@
/ /docs/react/
Binary file added docs/source/assets/client-diagrams/1-overview.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/client-diagrams/2-map.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/client-diagrams/3-minimize.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/devtools.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/mutation-init.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/mutation-result.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/query-init-data.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/query-init.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/assets/devtools/query-result.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions docs/source/basics/error-handling.md
@@ -0,0 +1,17 @@
---
title: Error Handling
subtitle: Subtitle
description: Description
---

<h2 title="topic">Topic</h2>

<h3 title="subtopic">Sub Topic</h3>

```js
// code block
```

<h2 title="best-practices">Best Practices</h2>

<h2 title="API">API Documentation</h2>
170 changes: 170 additions & 0 deletions docs/source/basics/fragments.md
@@ -0,0 +1,170 @@
---
title: Using Fragments
---

A [GraphQL fragment](http://graphql.org/learn/queries/#fragments) is a shared piece of query logic.

```graphql
fragment NameParts on Person {
firstName
lastName
}

query getPerson {
people(id: "7") {
...NameParts
avatar(size: LARGE)
}
}
```

There are two principal uses for fragments in Apollo:

- Sharing fields between multiple queries, mutations or subscriptions.
- Breaking your queries up to allow you to co-locate field access with the places they are used.

In this document we'll outline patterns to do both; we'll also make use of utilities in the [`graphql-anywhere`](https://github.com/apollographql/apollo-client) and [`graphql-tag`](https://github.com/apollographql/graphql-tag) packages which aim to help us, especially with the second problem.

<h2 id="reusing-fragments">Reusing Fragments</h2>

The most straightforward use of fragments is to reuse parts of queries (or mutations or subscriptions) in various parts of your application. For instance, in GitHunt on the comments page, we want to fetch the same fields after posting a comment as we originally query. This way we can be sure that we render consistent comment objects as the data changes.

To do so, we can simply share a fragment describing the fields we need for a comment:

```js
import gql from 'graphql-tag';

CommentsPage.fragments = {
comment: gql`
fragment CommentsPageComment on Comment {
id
postedBy {
login
html_url
}
createdAt
content
}
`,
};
```

We put the fragment on `CommentsPage.fragments.comment` by convention, and use the familiar `gql` helper to create it.

When it's time to embed the fragment in a query, we simply use the `...Name` syntax in our GraphQL, and embed the fragment inside our query GraphQL document:

```
const SUBMIT_COMMENT_MUTATION = gql`
mutation submitComment($repoFullName: String!, $commentContent: String!) {
submitComment(repoFullName: $repoFullName, commentContent: $commentContent) {
...CommentsPageComment
}
}
${CommentsPage.fragments.comment}
`;
export const COMMENT_QUERY = gql`
query Comment($repoName: String!) {
# ...
entry(repoFullName: $repoName) {
# ...
comments {
...CommentsPageComment
}
# ...
}
}
${CommentsPage.fragments.comment}
`;
```

You can see the full source code to the `CommentsPage` in GitHunt [here](https://github.com/apollographql/GitHunt-React/blob/master/ui/routes/CommentsPage.js).

<h2 id="colocating-fragments">Colocating Fragments</h2>

A key advantage of GraphQL is the tree-like nature of the response data, which in many cases mirrors your rendered component hierarchy. This, combined with GraphQL's support for fragments, allows you to split your queries up in such a way that the various fields fetched by the queries are located right alongside the code that uses the field.

Although this technique doesn't always make sense (for instance it's not always the case that the GraphQL schema is driven by the UI requirements), when it does, it's possible to use some patterns in Apollo client to take full advantage of it.

In GitHunt, we show an example of this on the [`FeedPage`](https://github.com/apollographql/GitHunt-React/blob/master/ui/routes/FeedPage.js), which constructs the follow view hierarchy:

```
FeedPage
└── Feed
└── FeedEntry
├── RepoInfo
└── VoteButtons
```

The `FeedPage` conducts a query to fetch a list of `Entry`s, and each of the subcomponents requires different subfields of each `Entry`.

The `graphql-anywhere` package gives us tools to easily construct a single query that provides all the fields that each subcomponent needs, and allows to easily pass the exact field that a component needs to it.

<h3 id="creating-fragments">Creating Fragments</h3>

To create the fragments, we again use the `gql` helper and attach to subfields of `ComponentClass.fragments`, for example:

```js
VoteButtons.fragments = {
entry: gql`
fragment VoteButtons on Entry {
score
vote {
vote_value
}
}
`,
};
```

If our fragments include sub-fragments then we can pass them into the `gql` helper:

```js
FeedEntry.fragments = {
entry: gql`
fragment FeedEntry on Entry {
commentCount
repository {
full_name
html_url
owner {
avatar_url
}
}
...VoteButtons
...RepoInfo
}
${VoteButtons.fragments.entry}
${RepoInfo.fragments.entry}
`,
};
```

<h3 id="filtering-with-fragments">Filtering With Fragments</h3>

We can also use the `graphql-anywhere` package to filter the exact fields from the `entry` before passing them to the subcomponent. So when we render a `VoteButtons`, we can simply do:

```jsx
import { filter } from 'graphql-anywhere';

<VoteButtons
entry={filter(VoteButtons.fragments.entry, entry)}
canVote={loggedIn}
onVote={type => onVote({
repoFullName: full_name,
type,
})}
/>
```

The `filter()` function will grab exactly the fields from the `entry` that the fragment defines.

<h3 id="webpack-importing-fragments" title="Fragments with Webpack">Importing fragments when using Webpack</h3>

When loading `.graphql` files with [graphql-tag/loader](https://github.com/apollographql/graphql-tag/blob/master/loader.js), we can include fragments using `import` statements. For example:

```graphql
#import "./someFragment.graphql"
```

Will make the contents of `someFragment.graphql` available to the current file. See the [Webpack Fragments](webpack.html#Fragments) section for additional details.

0 comments on commit 816a61d

Please sign in to comment.