Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v2][tutorial] Add importing graphql function #6092

Merged
merged 5 commits into from
Jun 28, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/tutorial/part-five/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,9 @@ Let's try this.
Create a new file at `src/pages/my-files.js` with the `allFile` query you just
created:

```jsx{5}
```jsx{6}
import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/layout"

export default ({ data }) => {
Expand Down Expand Up @@ -148,8 +149,9 @@ The shape of the data matches the shape of the query.

Let's add some code to your component to print out the File data.

```jsx{8-30}
```jsx{9-31}
import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/layout"

export default ({ data }) => {
Expand Down
36 changes: 13 additions & 23 deletions docs/tutorial/part-four/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,8 +248,9 @@ Then edit the two components:

`src/pages/about.js`

```jsx{4,6,13-22}
```jsx{5,7,14-23}
import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/layout"

export default ({ data }) => (
Expand Down Expand Up @@ -278,7 +279,7 @@ export const query = graphql`
```jsx{3,8-18,35}
import React from "react"
import { css } from "react-emotion"
import { StaticQuery, Link } from "gatsby"
import { StaticQuery, Link, graphql } from "gatsby"

import { rhythm } from "../utils/typography"

Expand Down Expand Up @@ -346,27 +347,16 @@ So almost everywhere, changes you make will immediately take effect.
Try editing the title in `siteMetadata`—change the title back to "Pandas Eating
Lots". The change should show up very quickly in your browser.

## Wait — where did the graphql tag come from?
Copy link
Contributor

@m-allanson m-allanson Jun 25, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've held off on merging this as I'm wondering what to do about this section. It's great that we don't have to explain how the graphql tag works without being imported. BUT this is still working in the same way behind the scenes. So I wonder if a simplified version of this question and answer should stay in the tutorial?

Maybe something like:

How does the graphql tag work?

You may have noticed that you used a tag function called graphql. Behind the scenes Gatsby handles these tags in a particular way - let's explore what actually happens when you use Gatsby's graphql tag:

The short answer is this: during the Gatsby build process, GraphQL queries are
pulled out of the original source for parsing.

The longer answer is a little more involved: Gatsby borrows a technique from
Relay that converts your source code into an abstract syntax tree (AST) during the build step. file-parser.js and query-compiler.js pick out your graphql-tagged templates and effectively remove them from the original source code.

This means that the graphql tag isn’t executed the way that you might expect.
For example, you cannot use expression interpolation with Gatsby's graphql tag.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @KyleAMathews for thoughts on this too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the sort of "optional" content that could fit well in a note or callout component (#5612)


You may have noticed that you used a
[tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals)
called `graphql`, but you never actually _import_ a `graphql` tag. So... how does
this not throw an error?

The short answer is this: during the Gatsby build process, GraphQL queries are
pulled out of the original source for parsing.

The longer answer is a little more involved: Gatsby borrows a technique from
[Relay](https://facebook.github.io/relay/) that converts your source code into an
[abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree)
during the build step. All `graphql`-tagged templates are found in
[`file-parser.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/file-parser.js)
and
[`query-compiler.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/query-compiler.js),
which effectively removes them from the original source code. This means that
the `graphql` tag isn’t executed the way that you might expect, which is why
there’s no error, despite the fact that you’re technically using an undefined tag
in your source.
## How does the graphql tag work?

You may have noticed that you used a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) called `graphql`. Behind the scenes Gatsby handles these tags in a particular way - let's explore what actually happens when you use Gatsby's `graphql` tag:

The short answer is this: during the Gatsby build process, GraphQL queries are pulled out of the original source for parsing.

The longer answer is a little more involved: Gatsby borrows a technique from
[Relay](https://facebook.github.io/relay/) that converts your source code into an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) during the build step. [`file-parser.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/file-parser.js) and [`query-compiler.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/query-compiler.js) pick out your `graphql`-tagged templates and effectively remove them from the original source code.

This means that the `graphql` tag isn’t executed the way that you might expect. For example, you cannot use [expression interpolation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Expression_interpolation) with Gatsby's `graphql` tag.

## What's coming next?

Expand Down
5 changes: 3 additions & 2 deletions docs/tutorial/part-seven/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -286,8 +286,9 @@ Visit one of them and you see:
Which is a bit boring and not what you want. Let's pull in data from your markdown post. Change
`src/templates/blog-post.js` to:

```jsx{4-5,8-11,14-25}
```jsx{5-6,9-12,15-26}
import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/layout"

export default ({ data }) => {
Expand Down Expand Up @@ -328,7 +329,7 @@ links.
```jsx{3,23-29,45,64-66}
import React from "react"
import { css } from "react-emotion"
import { Link } from "gatsby"
import { Link, graphql } from "gatsby"
import { rhythm } from "../utils/typography"
import Layout from "../components/layout"

Expand Down
1 change: 1 addition & 0 deletions docs/tutorial/part-six/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ the following to add a query with some initial HTML and styling.

```jsx
import React from "react"
import { graphql } from "gatsby"
import { css } from "react-emotion"
import { rhythm } from "../utils/typography"
import Layout from "../components/layout"
Expand Down