Added GraphQL Sections into Client-side Data Best Practices

Gemfile

@@ -4,4 +4,5 @@ require 'json'
 require 'open-uri'
 versions = JSON.parse(open('https://pages.github.com/versions.json').read)
 
-gem 'github-pages', versions['github-pages']
+gem 'github-pages', group: :jekyll_plugins
+

Gemfile.lock

@@ -15,7 +15,7 @@ GEM
     colorator (1.1.0)
     commonmarker (0.17.13)
       ruby-enum (~> 0.5)
-    concurrent-ruby (1.0.5)
+    concurrent-ruby (1.1.3)
     dnsruby (1.61.2)
       addressable (~> 2.5)
     em-websocket (0.5.1)
@@ -25,20 +25,20 @@ GEM
       ffi (>= 1.3.0)
     eventmachine (1.2.7)
     execjs (2.7.0)
-    faraday (0.15.3)
+    faraday (0.15.4)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.25)
     forwardable-extended (2.6.0)
     gemoji (3.0.0)
-    github-pages (192)
+    github-pages (193)
       activesupport (= 4.2.10)
       github-pages-health-check (= 1.8.1)
       jekyll (= 3.7.4)
       jekyll-avatar (= 0.6.0)
       jekyll-coffeescript (= 1.1.1)
       jekyll-commonmark-ghpages (= 0.1.5)
       jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.10.0)
+      jekyll-feed (= 0.11.0)
       jekyll-gist (= 1.5.0)
       jekyll-github-metadata (= 2.9.4)
       jekyll-mentions (= 1.4.1)
@@ -81,7 +81,7 @@ GEM
       octokit (~> 4.0)
       public_suffix (~> 2.0)
       typhoeus (~> 1.3)
-    html-pipeline (2.8.4)
+    html-pipeline (2.9.1)
       activesupport (>= 2)
       nokogiri (>= 1.4)
     http_parser.rb (0.6.0)
@@ -114,7 +114,7 @@ GEM
       rouge (~> 2)
     jekyll-default-layout (0.1.4)
       jekyll (~> 3.0)
-    jekyll-feed (0.10.0)
+    jekyll-feed (0.11.0)
       jekyll (~> 3.3)
     jekyll-gist (1.5.0)
       octokit (~> 4.2)
@@ -185,12 +185,13 @@ GEM
       jekyll-seo-tag (~> 2.0)
     jekyll-titles-from-headings (0.5.1)
       jekyll (~> 3.3)
-    jekyll-watch (2.0.0)
+    jekyll-watch (2.1.2)
       listen (~> 3.0)
     jemoji (0.10.1)
       gemoji (~> 3.0)
       html-pipeline (~> 2.2)
       jekyll (~> 3.0)
+    json (1.8.3.1)
     kramdown (1.17.0)
     liquid (4.0.0)
     listen (3.1.5)
@@ -205,11 +206,11 @@ GEM
       jekyll-seo-tag (~> 2.1)
     minitest (5.11.3)
     multipart-post (2.0.0)
-    nokogiri (1.8.4)
+    nokogiri (1.8.5)
       mini_portile2 (~> 2.3.0)
-    octokit (4.12.0)
+    octokit (4.13.0)
       sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.16.1)
+    pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (2.0.5)
     rb-fsevent (0.10.3)
@@ -221,7 +222,7 @@ GEM
     ruby_dep (1.5.0)
     rubyzip (1.2.2)
     safe_yaml (1.0.4)
-    sass (3.6.0)
+    sass (3.7.2)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -232,7 +233,7 @@ GEM
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     thread_safe (0.3.6)
-    typhoeus (1.3.0)
+    typhoeus (1.3.1)
       ethon (>= 0.9.0)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
@@ -242,7 +243,8 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  github-pages (= 192)
+  github-pages
+  json
 
 BUNDLED WITH
    1.16.1

_includes/markdown/JavaScript.md

@@ -103,7 +103,23 @@ Certain codebases may already have such libraries in place. Many legacy projects
 ### Concatenating Requests
 When constructing a page that contains a lot of client-side data requests you will want to consider concatenating your requests into a single Ajax call. This will help you avoid piling up requests or sending them through callbacks and nested promises when parts of the data depend on other parts.
 
-[GraphQL](https://graphql.org/) is an open source query language that can help with this situation by allowing you to combine multiple API requests into a single call. In a WordPress environment, the [WPGraphQL](https://github.com/wp-graphql/wp-graphql) plugin will let you directly access the WordPress JSON API.
+#### GraphQL
+[GraphQL](https://graphql.org/) is an open source data query and manipulation language. It provides an alternative to REST because it allows for a consistent way to make declarative queries. We first define the data structure(s) we need, then request the data, and return only the data that was requested. This creates an environment of smaller, more targeted calls to an API. It also allows us to concatenate multiple calls into single data requests, reducing the overhead and time to load.
+
+An essential part of a GraphQL API is an API schema. GraphQL requires a human-readable schema which describes the types which are available, and how they relate to one another. While writing a schema is reasonably straightforward, utilizing the standardized nature of WordPress’s database could save time. It may well be possible to reuse a schema from other projects, such as generated by a plugin like, [WPGraphQL](https://github.com/wp-graphql/wp-graphql).
+
+#### WPGraphQL
+If you are choosing to use GraphQL on a WordPress project, it is recommended to use the WPGraphQL plugin. This plugin will return WordPress data in JSON format through a GraphQL endpoint - in many cases you won’t need to write the schema yourself. This will give you all the benefits of concatenating your data requests as well as easy access to your data as it is output by WordPress. You can retrieve your data by passing a query directly into a simple fetch request:
+
+```javascript
+fetch( '/graphql', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: "[your query string goes here]" }),
+} ).then( res => res.json() );
+```
+
+The above code snippet will help you get started in making requests to the GraphQL service.
 
 <h2 id="design-patterns" class="anchor-heading">Design Patterns {% include Util/top %}</h2>
 

javascript.md

@@ -10,6 +10,8 @@ subnav:
     tag: performance
   - title: Design Patterns
     tag: design-patterns
+  - title: Client-Side Data
+    tag: client-side-data
   - title: Code Style & Documentation
     tag: code-style
   - title: Unit and Integration Testing