Skip to content

Commit

Permalink
[v2][tutorial] Add importing graphql function (#6092)
Browse files Browse the repository at this point in the history
* tutorial-part-four import graphql

* tutorial-part-five import graphql

* tutorial-part-six import graphql

* tutorial-part-seven import graphql

* Add "How does the graphql tag work"
  • Loading branch information
Ryandi Tjia authored and pieh committed Jun 28, 2018
1 parent 261286a commit 1b457b6
Show file tree
Hide file tree
Showing 4 changed files with 21 additions and 27 deletions.
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?
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

0 comments on commit 1b457b6

Please sign in to comment.