From 9ea5c363d6d6118fadd1e9ba661f411fdf22dd3f Mon Sep 17 00:00:00 2001 From: Amberley Date: Mon, 13 Aug 2018 15:38:48 -0700 Subject: [PATCH] [v2] docs - update page query docs (#7285) * (#7278): Update graphql and static query doc organization to pattern consistently * (#7278): move graphql tag explanation from tutorial to page query docs * (#7278): remove intro paragraph, no longer necessary after restructuring * (#7278): add language to StaticQuery intro * (#7278): add link to page-query doc in tutorial part four * (#7278): distinct heading levels for sections * (#7278): consistent intro style on page-query, alter graphql explanation for different context close #7278 --- ...ge-with-graphql-query.md => page-query.md} | 33 ++++++++++++++----- docs/docs/static-query.md | 10 ++++-- docs/tutorial/part-four/index.md | 18 +--------- www/src/data/sidebars/doc-links.yaml | 8 ++--- 4 files changed, 37 insertions(+), 32 deletions(-) rename docs/docs/{build-a-page-with-graphql-query.md => page-query.md} (55%) diff --git a/docs/docs/build-a-page-with-graphql-query.md b/docs/docs/page-query.md similarity index 55% rename from docs/docs/build-a-page-with-graphql-query.md rename to docs/docs/page-query.md index 75ad8d6eb3720..7948b4fa6b360 100644 --- a/docs/docs/build-a-page-with-graphql-query.md +++ b/docs/docs/page-query.md @@ -1,12 +1,14 @@ --- -title: Build a page with a GraphQL query +title: Querying data in pages with graphql --- -Gatsby creates pages from components located within `src/pages`. It watches the folder and will create and remove pages as you add and remove components. The pathname for each page is derived from the name of the component. For example, `src/pages/about.js` would be located at `/about/` when published. +Gatsby's `graphql` tag enables page components to retrieve data via GraphQL query. -In this guide, you will learn how to perform a query of your site's metadata for the description to display on your homepage. +In this guide, you will learn [how to use the `graphql` tag](/page-query#adding-the-graphql-query) in your pages, as well as go a little deeper into [how the `graphql` tag works](/page-query#how-does-the-graphql-tag-work). -## Adding `description` to `siteMetadata` +## How to use the `graphql` tag in pages + +### Add `description` to `siteMetadata` The first step in displaying the description will be ensuring you have one to begin with. @@ -21,7 +23,7 @@ module.exports = { } ``` -## Basic Index Page Markup +### Mark up basic index page A simple index page (`src/pages/index.js`) can be marked up like so: @@ -35,9 +37,9 @@ const HomePage = () => { export default HomePage ``` -## Adding the GraphQL Query +### Add the `graphql` query -The first thing to do is import GraphQL from Gatsby. At the top of `index.js` add: +The first thing to do is import `graphql` from Gatsby. At the top of `index.js` add: ```diff import React from 'react' @@ -87,7 +89,7 @@ export const query = graphql` ` ``` -## Get Data into the `` Component +### Provide data to the `` component To start, update the `HomePage` component to destructure `data` from props. @@ -121,3 +123,18 @@ export default HomePage ``` After restarting `gatsby develop`, your home page will now display "This is where I write my thoughts." from the description set in `gatsby-config.js`! + +## How does the graphql tag work? + +`graphql` is a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals). Behind the scenes Gatsby handles these tags in a particular way: + +### The short answer + +During the Gatsby build process, GraphQL queries are pulled out of the original source for parsing. + +### The longer answer + +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. diff --git a/docs/docs/static-query.md b/docs/docs/static-query.md index 82fa585240f5c..9fd216f99dc9b 100644 --- a/docs/docs/static-query.md +++ b/docs/docs/static-query.md @@ -1,10 +1,14 @@ --- -title: "Querying data in components using StaticQuery" +title: Querying data in components using StaticQuery --- Gatsby v2 introduces `StaticQuery`, a new API that allows components to retrieve data via GraphQL query. -## Basic example +In this guide, we'll walk through an example using `StaticQuery`, and discuss [the difference between a StaticQuery and a page query](/static-query/#how-staticquery-differs-from-page-query). + +## How to use `StaticQuery` in components + +### Basic example We'll create a new `Header` component located at `src/components/header.js`: @@ -36,7 +40,7 @@ export default Header Using `StaticQuery`, you can colocate a component with its data. No longer is it required to, say, pass data down from `Layout` to `Header`. -## Typechecking +### Typechecking With the above pattern, you lose the ability to typecheck with PropTypes. To regain typechecking while achieving the same result, you can change the component to: diff --git a/docs/tutorial/part-four/index.md b/docs/tutorial/part-four/index.md index 0b6b3c1512e8b..c32973da074c7 100644 --- a/docs/tutorial/part-four/index.md +++ b/docs/tutorial/part-four/index.md @@ -229,7 +229,7 @@ Restart the development server. ### Use a page query -Now the site title is available to be queried; Let's add it to the `about.js` file using a page query: +Now the site title is available to be queried; Let's add it to the `about.js` file using a [page query](/docs/page-query): ```jsx{2,5,7,14-23} import React from "react" @@ -348,22 +348,6 @@ So almost everywhere, changes you make will immediately take effect. Edit the `g ![Both titles say Pandas Eating Lots](/pandas-eating-lots-titles.png) -## 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 take a deeper look at what actually happens when you use Gatsby's `graphql` tag: - -### The short answer - -During the Gatsby build process, GraphQL queries are pulled out of the original source for parsing. - -### The longer answer - -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? Next, you'll be learning about how to pull data into your Gatsby site using diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index b31462d736d42..d8f8251f28036 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -93,10 +93,12 @@ items: - title: Introducing GraphiQL* link: /docs/introducing-graphiql/ - - title: Build a page with a GraphQL query - link: /docs/build-a-page-with-graphql-query/ - title: Creating and modifying pages link: /docs/creating-and-modifying-pages/ + - title: Querying data in pages with graphql + link: /docs/page-query/ + - title: Querying data in components with StaticQuery + link: /docs/static-query/ - title: Adding Markdown pages link: /docs/adding-markdown-pages/ - title: Adding a list of Markdown blog posts @@ -105,8 +107,6 @@ link: /docs/creating-slugs-for-pages/ - title: Programmatically create pages from data* link: /docs/programmatically-create-pages-from-data/ - - title: Querying data with StaticQuery - link: /docs/static-query/ - title: Plugins link: /docs/plugins/ items: