From f8f52ba8d5eb1b74fb29b7126ed07c1c72ffd658 Mon Sep 17 00:00:00 2001
From: Jia Hao <jiahaog@users.noreply.github.com>
Date: Sat, 10 Feb 2018 07:50:36 +0800
Subject: [PATCH] Document how to create custom fragments (#3914)

* Document how to create custom fragments

* Fix ordering

* Add example component exporting a fragment

* Tweak language
---
 docs/docs/querying-with-graphql.md | 141 +++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)

diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md
index e762874baa6d4..416ea8b2e7f52 100644
--- a/docs/docs/querying-with-graphql.md
+++ b/docs/docs/querying-with-graphql.md
@@ -199,6 +199,147 @@ 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
+
+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 if I put a fragment in a helper component, I can use that fragment in any other query:
+
+```jsx
+// src/components/PostItem.js
+
+export const markdownFrontmatterFragment = graphql`
+  fragment MarkdownFrontmatter 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 } }) {
+    ...MarkdownFrontmatter
+  }
+}
+```
+
+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
+// src/pages/index.jsx
+
+import React from "react";
+
+export default ({ data }) => {
+  return (
+    <div>
+		<h1>
+        Index page
+		</h1>
+      <h4>{data.allMarkdownRemark.totalCount} Posts</h4>
+      {data.allMarkdownRemark.edges.map(({ node }) => (
+        <div key={node.id}>
+          <h3>
+            {node.frontmatter.title}{" "}
+            <span>— {node.frontmatter.date}</span>
+          </h3>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+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 } }) => (
+  <div>
+    <h3>
+      {title} <span>— {date}</span>
+    </h3>
+  </div>
+);
+
+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{28}
+// src/pages/index.jsx
+
+import React from "react";
+import IndexPost from "../components/IndexPost";
+
+export default ({ data }) => {
+  return (
+    <div>
+		<h1>
+        Index page
+		</h1>
+      <h4>{data.allMarkdownRemark.totalCount} Posts</h4>
+      {data.allMarkdownRemark.edges.map(({ node }) => (
+        <div key={node.id}>
+          <IndexPost frontmatter={node.frontmatter} />
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const query = graphql`
+  query IndexQuery {
+    allMarkdownRemark {
+      totalCount
+      edges {
+        node {
+          ...IndexPostFragment
+        }
+      }
+    }
+  }
+`;
+```
+
 ## Further reading
 
 ### Getting started with GraphQL