Add unstructured data example (#9408)

* add @jlengstorf unstructured data in official examples

* clarify other branch in README

* add local plugin example (from comparison branch of unstructured data example

* update local plugin example README to reference unstructured data example

* update unstructured data README, and rename local plugins example dir

* link out to blog post and doc page

examples/using-local-plugins/.gitignore

@@ -0,0 +1,62 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+.cache/
+public
+yarn-error.log

examples/using-local-plugins/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 gatsbyjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/using-local-plugins/README.md

@@ -0,0 +1,19 @@
+# Using a local plugin
+
+This example demonstrates usage of a local plugin -- in this case a source plugin.
+
+You might also be interested in the docs section on [local plugins](/docs/plugin-authoring/#local-plugins), or the [source plugin tutorial](/docs/source-plugin-tutorial/).
+
+## Using Gatsby's GraphQL integration layer
+
+This example site is also intended as a direct comparison to the [using-unstructured-data example](../using-unstructured-data), which illustrates how to use an "unstructured data" approach (or, without making use of the GraphQL integration layer).
+
+## Sourcing data using a local plugin
+
+This example uses a [local plugin](https://www.gatsbyjs.org/docs/plugins/#loading-plugins-from-your-local-plugins-folder) to:
+
+1. Load data from the PokéAPI’s REST endpoints
+2. Process that data into Gatsby's node format
+3. Use the [`createNode` action](https://www.gatsbyjs.org/docs/actions/#createNode) to add the data to Gatsby’s GraphQL layer
+
+The [`gatsby-node.js` file](https://github.com/jlengstorf/gatsby-with-unstructured-data/blob/using-gatsby-data-layer/plugins/gatsby-source-pokeapi/gatsby-node.js) of the local plugin includes detailed comments on the process.

examples/using-local-plugins/gatsby-config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  plugins: ["gatsby-source-pokeapi"],
+}

examples/using-local-plugins/gatsby-node.js

@@ -0,0 +1,56 @@
+exports.createPages = async ({ graphql, actions: { createPage } }) => {
+  const result = await graphql(`
+    query {
+      allPokeapiPokemon {
+        edges {
+          node {
+            name
+            id
+            abilities {
+              id
+              name
+            }
+          }
+        }
+      }
+    }
+  `)
+
+  const {
+    data: {
+      allPokeapiPokemon: { edges: allPokemon },
+    },
+  } = result
+
+  // Create a page that lists all Pokémon.
+  createPage({
+    path: `/`,
+    component: require.resolve("./src/templates/all-pokemon.js"),
+    context: {
+      slug: `/`,
+    },
+  })
+
+  // Create a page for each Pokémon.
+  allPokemon.forEach(pokemon => {
+    createPage({
+      path: `/pokemon/${pokemon.node.name}/`,
+      component: require.resolve("./src/templates/pokemon.js"),
+      context: {
+        name: pokemon.node.name,
+      },
+    })
+
+    // Create a page for each ability of the current Pokémon.
+    pokemon.node.abilities.forEach(ability => {
+      createPage({
+        path: `/pokemon/${pokemon.node.name}/ability/${ability.name}/`,
+        component: require.resolve("./src/templates/ability.js"),
+        context: {
+          pokemonId: pokemon.node.id,
+          abilityId: ability.id,
+        },
+      })
+    })
+  })
+}

examples/using-local-plugins/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "gatsby-source-plugin-workshop",
+  "description": "Workshop source for a source plugin workshop",
+  "license": "MIT",
+  "scripts": {
+    "develop": "gatsby develop",
+    "build": "gatsby build",
+    "serve": "gatsby serve"
+  },
+  "dependencies": {
+    "axios": "^0.18.0",
+    "gatsby": "^2.0.0",
+    "react": "^16.5.1",
+    "react-dom": "^16.5.1"
+  },
+  "version": "1.0.0",
+  "main": "index.js",
+  "author": "Jason Lengstorf <jason@gatsbyjs.com>"
+}

examples/using-local-plugins/plugins/gatsby-source-pokeapi/gatsby-node.js

@@ -0,0 +1,56 @@
+const axios = require("axios")
+const createNodeHelpers = require("gatsby-node-helpers").default
+
+const get = endpoint => axios.get(`https://pokeapi.co/api/v2${endpoint}`)
+
+const getPokemonData = names =>
+  Promise.all(
+    names.map(async name => {
+      const { data: pokemon } = await get(`/pokemon/${name}`)
+      const abilities = await Promise.all(
+        pokemon.abilities.map(async ({ ability: { name: abilityName } }) => {
+          const { data: ability } = await get(`/ability/${abilityName}`)
+
+          return ability
+        })
+      )
+
+      return { ...pokemon, abilities }
+    })
+  )
+
+exports.sourceNodes = async ({ actions }) => {
+  const { createNode } = actions
+  const { createNodeFactory } = createNodeHelpers({
+    typePrefix: "Pokeapi",
+  })
+  const prepareAbilityNode = createNodeFactory("Ability")
+  const preparePokemonNode = createNodeFactory("Pokemon")
+
+  // Get all our pokemon data
+  const allPokemon = await getPokemonData(["pikachu", "charizard", "squirtle"])
+
+  // Process data for each pokemon into Gatsby node format
+  const processPokemon = pokemon => {
+    // Set up each ability as a node
+    const abilityNodes = pokemon.abilities.map(abilityData =>
+      prepareAbilityNode(abilityData)
+    )
+
+    // Actually create the "Ability" nodes for given pokemon
+    abilityNodes.forEach(node => {
+      createNode(node)
+    })
+
+    // Create the "Pokemon" node for given pokemon
+    const pokemonNode = preparePokemonNode(pokemon)
+
+    // Attach an array of "Ability" node ids to `abilities___NODE` in the Pokémon
+    pokemonNode.abilities___NODE = abilityNodes.map(node => node.id)
+
+    return pokemonNode
+  }
+
+  // Process data into nodes using our helper.
+  allPokemon.forEach(pokemon => createNode(processPokemon(pokemon)))
+}

examples/using-local-plugins/plugins/gatsby-source-pokeapi/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "gatsby-source-pokeapi",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "gatsby-node-helpers": "^0.3.0"
+  }
+}

examples/using-local-plugins/src/templates/ability.js

@@ -0,0 +1,40 @@
+import React from "react"
+import { Link, graphql } from "gatsby"
+
+const getName = ability =>
+  ability.names.find(({ language }) => language.name === "en").name
+
+export default ({ data: { pokemon, ability } }) => (
+  <div style={{ width: 960, margin: "4rem auto" }}>
+    <h1>
+      {pokemon.name}
+      ’s {getName(ability)} ability
+    </h1>
+    <img src={pokemon.sprites.front_default} alt={pokemon.name} />
+    <p>{ability.effect_entries[0].effect}</p>
+    <Link to={`/pokemon/${pokemon.name}`}>Back to {pokemon.name}</Link>
+  </div>
+)
+
+export const pageQuery = graphql`
+  query($pokemonId: String!, $abilityId: String!) {
+    pokemon: pokeapiPokemon(id: { eq: $pokemonId }) {
+      name
+      sprites {
+        front_default
+      }
+    }
+    ability: pokeapiAbility(id: { eq: $abilityId }) {
+      names {
+        name
+        language {
+          name
+          url
+        }
+      }
+      effect_entries {
+        effect
+      }
+    }
+  }
+`

examples/using-local-plugins/src/templates/all-pokemon.js

@@ -0,0 +1,47 @@
+import React from "react"
+import { Link, graphql, StaticQuery } from "gatsby"
+
+export default () => (
+  <StaticQuery
+    query={graphql`
+      query {
+        allPokemon: allPokeapiPokemon {
+          edges {
+            node {
+              id
+              name
+              sprites {
+                front_default
+              }
+            }
+          }
+        }
+      }
+    `}
+    render={data => (
+      <div style={{ width: 960, margin: "4rem auto" }}>
+        <h1>Choose a Pokémon!</h1>
+        <ul style={{ padding: 0 }}>
+          {data.allPokemon.edges.map(pokemon => (
+            <li
+              key={pokemon.node.id}
+              style={{
+                textAlign: "center",
+                listStyle: "none",
+                display: "inline-block",
+              }}
+            >
+              <Link to={`/pokemon/${pokemon.node.name}`}>
+                <img
+                  src={pokemon.node.sprites.front_default}
+                  alt={pokemon.node.name}
+                />
+                <p>{pokemon.node.name}</p>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )}
+  />
+)

examples/using-local-plugins/src/templates/pokemon.js

@@ -0,0 +1,34 @@
+import React from "react"
+import { Link, graphql } from "gatsby"
+
+export default ({ data: { pokemon } }) => (
+  <div style={{ width: 960, margin: "4rem auto" }}>
+    <h1>{pokemon.name}</h1>
+    <img src={pokemon.sprites.front_default} alt={pokemon.name} />
+    <h2>Abilities</h2>
+    <ul>
+      {pokemon.abilities.map(ability => (
+        <li key={ability.name}>
+          <Link to={`./pokemon/${pokemon.name}/ability/${ability.name}`}>
+            {ability.name}
+          </Link>
+        </li>
+      ))}
+    </ul>
+    <Link to="/">Back to all Pokémon</Link>
+  </div>
+)
+
+export const pageQuery = graphql`
+  query($name: String!) {
+    pokemon: pokeapiPokemon(name: { eq: $name }) {
+      name
+      sprites {
+        front_default
+      }
+      abilities {
+        name
+      }
+    }
+  }
+`