From 96401d291b47b254a91ddb1c83ef5ada9637c59c Mon Sep 17 00:00:00 2001 From: Jia Hao Date: Thu, 8 Feb 2018 17:18:40 +0800 Subject: [PATCH 1/4] Document how to create custom fragments --- docs/docs/querying-with-graphql.md | 34 ++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md index e762874baa6d4..c53dd5a2ee0f5 100644 --- a/docs/docs/querying-with-graphql.md +++ b/docs/docs/querying-with-graphql.md @@ -194,6 +194,40 @@ export const query = graphql` `; ``` +## Advanced + +### Fragments + +Notice that in the above example for [querying images](#images), we used `...GatsbyImageSharpResolutions`, which is a GraphQL Fragment, a reusable set of fields for query composition. You can read more about them [here](http://graphql.org/learn/queries/#fragments). + +If you wish to define your own fragments for use in your application, you can use named exports to export them in any Javascript file, and they will be automatically processed by Gatsby for use in your GraphQL queries. + +For example, I can put all of my helper fragments in `src/fragments/index.js`: + +```javascript +// src/fragments/index.js + +export const markdownFrontmatterFragment = graphql` + fragment MarkdownFrontmatterFragment on MarkdownRemark { + frontmatter { + path + title + date(formatString: "MMMM DD, YYYY") + } + } +`; +``` + +They can then be used in any GraphQL query after that! + +```graphql +query PostByPath($path: String!) { + markdownRemark(frontmatter: { path: { eq: $path } }) { + ...MarkdownMetadataFragment + } +} +``` + See also the following blog posts: * [Making Website Building Fun](/blog/2017-10-16-making-website-building-fun/) From 5977f06c43e7bdf0119641c4fd06dbaad19a4cbd Mon Sep 17 00:00:00 2001 From: Jia Hao Date: Thu, 8 Feb 2018 17:20:47 +0800 Subject: [PATCH 2/4] Fix ordering --- docs/docs/querying-with-graphql.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md index c53dd5a2ee0f5..683a4ac130e63 100644 --- a/docs/docs/querying-with-graphql.md +++ b/docs/docs/querying-with-graphql.md @@ -194,6 +194,11 @@ export const query = graphql` `; ``` +See also the following blog posts: + +* [Making Website Building Fun](/blog/2017-10-16-making-website-building-fun/) +* [Image Optimization Made Easy with Gatsby.js](https://medium.com/@kyle.robert.gill/ridiculously-easy-image-optimization-with-gatsby-js-59d48e15db6e) + ## Advanced ### Fragments @@ -228,11 +233,6 @@ query PostByPath($path: String!) { } ``` -See also the following blog posts: - -* [Making Website Building Fun](/blog/2017-10-16-making-website-building-fun/) -* [Image Optimization Made Easy with Gatsby.js](https://medium.com/@kyle.robert.gill/ridiculously-easy-image-optimization-with-gatsby-js-59d48e15db6e) - ## Further reading ### Getting started with GraphQL From ae6b958c0bf11c38f902e86f1e13fb015da6af45 Mon Sep 17 00:00:00 2001 From: Jia Hao Date: Fri, 9 Feb 2018 10:47:37 +0800 Subject: [PATCH 3/4] Add example component exporting a fragment --- docs/docs/querying-with-graphql.md | 114 ++++++++++++++++++++++++++++- 1 file changed, 111 insertions(+), 3 deletions(-) diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md index 683a4ac130e63..d590c4447c695 100644 --- a/docs/docs/querying-with-graphql.md +++ b/docs/docs/querying-with-graphql.md @@ -209,11 +209,11 @@ If you wish to define your own fragments for use in your application, you can us For example, I can put all of my helper fragments in `src/fragments/index.js`: -```javascript +```jsx // src/fragments/index.js export const markdownFrontmatterFragment = graphql` - fragment MarkdownFrontmatterFragment on MarkdownRemark { + fragment MarkdownFrontmatter on MarkdownRemark { frontmatter { path title @@ -228,11 +228,119 @@ They can then be used in any GraphQL query after that! ```graphql query PostByPath($path: String!) { markdownRemark(frontmatter: { path: { eq: $path } }) { - ...MarkdownMetadataFragment + ... MarkdownFrontmatter } } ``` +It’s good practice for your helper components to define and export a fragment for the data they need though. For example, on your index page might map over all of your posts to show them in a list. + +```jsx{14-17,31-34} +// src/pages/index.jsx + +import React from "react"; + +export default ({ data }) => { + return ( +
+

+ Index page +

+

{data.allMarkdownRemark.totalCount} Posts

+ {data.allMarkdownRemark.edges.map(({ node }) => ( +
+

+ {node.frontmatter.title}{" "} + — {node.frontmatter.date} +

+
+ ))} +
+ ); +}; + +export const query = graphql` + query IndexQuery { + allMarkdownRemark { + totalCount + edges { + node { + id + frontmatter { + title + date(formatString: "DD MMMM, YYYY") + } + } + } + } + } +`; +``` + +If the index component becomes too large, you might want to refactor it into smaller components. + +```jsx +// src/components/IndexPost.jsx + +import React from "react"; + +export default ({ frontmatter: { title, date }}) => ( +
+

+ {title}{" "} + — {date} +

+
+) + +export const query = graphql` + fragment IndexPostFragment on MarkdownRemark { + frontmatter { + title + date(formatString: "MMMM DD, YYYY") + } + } +`; +``` + +Now, we can use the component together with the exported fragment in our index page. + +```jsx{15} +// src/pages/index.jsx + +import React from "react"; +import IndexPost from "../components/IndexPost"; + +export default ({ data }) => { + return ( +
+

+ Index page +

+

{data.allMarkdownRemark.totalCount} Posts

+ {data.allMarkdownRemark.edges.map(({ node }) => ( +
+ +
+ ))} +
+ ); +}; + +export const query = graphql` + query IndexQuery { + allMarkdownRemark { + totalCount + edges { + node { + ...IndexPostFragment + } + } + } + } +`; +``` + ## Further reading ### Getting started with GraphQL From 2541e9a63c29e7435c430faf3697a9d635f1230e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 9 Feb 2018 15:50:13 -0800 Subject: [PATCH 4/4] Tweak language --- docs/docs/querying-with-graphql.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md index d590c4447c695..416ea8b2e7f52 100644 --- a/docs/docs/querying-with-graphql.md +++ b/docs/docs/querying-with-graphql.md @@ -207,10 +207,10 @@ Notice that in the above example for [querying images](#images), we used `...Gat If you wish to define your own fragments for use in your application, you can use named exports to export them in any Javascript file, and they will be automatically processed by Gatsby for use in your GraphQL queries. -For example, I can put all of my helper fragments in `src/fragments/index.js`: +For example if I put a fragment in a helper component, I can use that fragment in any other query: ```jsx -// src/fragments/index.js +// src/components/PostItem.js export const markdownFrontmatterFragment = graphql` fragment MarkdownFrontmatter on MarkdownRemark { @@ -228,14 +228,14 @@ They can then be used in any GraphQL query after that! ```graphql query PostByPath($path: String!) { markdownRemark(frontmatter: { path: { eq: $path } }) { - ... MarkdownFrontmatter + ...MarkdownFrontmatter } } ``` -It’s good practice for your helper components to define and export a fragment for the data they need though. For example, on your index page might map over all of your posts to show them in a list. +It’s good practice for your helper components to define and export a fragment for the data they need. For example, on your index page might map over all of your posts to show them in a list. -```jsx{14-17,31-34} +```jsx // src/pages/index.jsx import React from "react"; @@ -284,14 +284,13 @@ If the index component becomes too large, you might want to refactor it into sma import React from "react"; -export default ({ frontmatter: { title, date }}) => ( +export default ({ frontmatter: { title, date } }) => (

- {title}{" "} - — {date} + {title} — {date}

-) +); export const query = graphql` fragment IndexPostFragment on MarkdownRemark { @@ -305,7 +304,7 @@ export const query = graphql` Now, we can use the component together with the exported fragment in our index page. -```jsx{15} +```jsx{28} // src/pages/index.jsx import React from "react";