Merge branch 'v2.2.0'

graysonhicks · Jul 7, 2020 · 8b6d727 · 8b6d727
2 parents e0cc021 + 04cf19a
commit 8b6d727
Show file tree

Hide file tree

Showing 6 changed files with 346 additions and 56 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 /*.js
 !index.js
 node_modules/
-package-lock.json
+package-lock.json
+.vscode
+.history
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+v14.4.0
diff --git a/README.md b/README.md
@@ -1,18 +1,26 @@
-# :floppy_disk: gatsby-plugin-remote-images
+# 💾 gatsby-plugin-remote-images
 
 Download images from any string field on another node so that those images can
 be queried with `gatsby-image`.
 
-### Usage
+- [Usage](#usage)
+  - [Install](#install)
+  - [Options](#options) -
+    [Example Config with Optional Options](#example-config-with-optional-options)
+- [Why?](#why)
+- [Common Issues](#common-issues)
+  - [gatsby-source-graphql](#gatsby-source-graphql)
+  - [Traversing objects with arrays](#traversing-objects-with-arrays)
+  - [Handling an Array of Image URLs](#handling-an-array-of-image-urls)
 
-#### Install
+## Usage
+
+### Install
 
 First, install the plugin.
 
 `npm install --save gatsby-plugin-remote-images`
 
-#### Config
-
 Second, set up the `gatsby-config.js` with the plugin. The most common config
 would be this:
 
@@ -22,14 +30,28 @@ module.exports = {
     {
       resolve: `gatsby-plugin-remote-images`,
       options: {
-        nodeType: 'myNodes',
+        nodeType: 'MyNodes',
         imagePath: 'path.to.image',
       },
     },
   ],
 };
 ```
 
+### Options
+
+| Option Name | Description                                                                                                                                                                                                                                                                                                                                      | Required | Default      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------ |
+| nodeType    | The node type that has the images you want to grab. This is generally the camelcased version of the word after the 'all' in GraphQL ie. allMyImages type is myImages                                                                                                                                                                             | ✅       | `null`       |
+| imagePath   | For simple object traversal, this is the string path to the image you want to use, relative to the node. This uses lodash .get, see [docs for accepted formats here](https://lodash.com/docs/4.17.11#get). For traversing objects with arrays at given depths, see [how to handle arrays along the path below](#traversing-objects-with-arrays). | ✅       | `null`       |
+| name        | Name you want to give new image field on the node. Defaults to `localImage`.                                                                                                                                                                                                                                                                     | ❌       | `localImage` |
+| auth        | Adds htaccess authentication to the download request if passed in.                                                                                                                                                                                                                                                                               | ❌       | `{}`         |
+| ext         | Sets the file extension. Useful for APIs that separate the image file path from its extension. Or for changing the extension. Defaults to existing file extension.                                                                                                                                                                               | ❌       | `null`       |
+| prepareUrl  | Allows modification of the URL per image if needed. Expects a function taking the original URL as a parameter and returning the desired URL.                                                                                                                                                                                                     | ❌       | `null`       |
+| type        | Tell the plugin that the leaf node is an _array_ of images instead of one single string. Only option here is `array`. For example usage, [see here](#handling-an-array-of-image-urls).                                                                                                                                                           | ❌       | `object`     |
+
+#### Example Config with Optional Options
+
 However, you may need more optional config, which is documented here.
 
 ```javascript
@@ -38,39 +60,25 @@ module.exports = {
     {
       resolve: `gatsby-plugin-remote-images`,
       options: {
-        // The node type that has the images you want to grab.
-        // This is generally the camelcased version of the word
-        // after the 'all' in GraphQL ie. allMyImages type is myImages
-        nodeType: 'myNodes',
-        // For simple object traversal, this is the string path to the image you
-        // want to use, relative to the node.
-        // This uses lodash .get, see [docs for accepted formats here](https://lodash.com/docs/4.17.11#get).
-        // For traversing objects with arrays at given depths, see [how to handle arrays below](#traversing-objects-with-arrays)
+        nodeType: 'MyNodes',
         imagePath: 'path.to.image',
         // ** ALL OPTIONAL BELOW HERE: **
-        // Name you want to give new image field on the node.
-        // Defaults to 'localImage'.
         name: 'theNewImageField',
-        // Adds htaccess authentication to the download request if passed in.
         auth: { htaccess_user: `USER`, htaccess_pass: `PASSWORD` },
-        // Sets the file extension. Useful for APIs that separate the image file path
-        // from its extension. Or for changing the extention.  Defaults to existing
-        // file extension.
         ext: '.jpg',
-        // Allows modification of the URL per image if needed. Expects a function
-        // taking the original URL as a parameter and returning the desired URL.
         prepareUrl: url => (url.startsWith('//') ? `https:${url}` : url),
       },
     },
   ],
 };
 ```
 
-### Why?
+## Why?
 
 Why do you need this plugin? The fantastic gatsby-image tool only works on
-_relative_ paths. This lets you use it on images from an API with an _absolute_
-path. For example, look at these two response from one GraphQL query:
+_relative_ paths to locally stored images. This lets you use it on images from
+an API with an _absolute_ path. For example, look at these two response from one
+GraphQL query:
 
 _Query_
 
@@ -124,7 +132,7 @@ module.exports = {
     {
       resolve: `gatsby-plugin-remote-images`,
       options: {
-        nodeType: 'myNodes',
+        nodeType: 'MyNodes',
         imagePath: 'imageUrl',
         // OPTIONAL: Name you want to give new image field on the node.
         // Defaults to 'localImage'.
@@ -153,7 +161,13 @@ allMyNodes {
 }
 ```
 
-#### Note on `gatsby-source-graphql`
+**Note:** Many Gatsby source plugins already do this work for you under the
+hood. So if you are working with a common CMS's Gatsby plugin, odds are that
+_you don't need this!_
+
+## Common Issues
+
+### `gatsby-source-graphql`
 
 Due to the way `gatsby-source-graphql` creates nodes, it is currently impossible
 for any transformer type plugin to traverse the data from that plugin.
@@ -168,8 +182,6 @@ target data lives, `gatsby-plugin-remote-images` also supports traversing
 objects that have arrays at arbitrary depths. To opt in to this feature, add an
 array literal, `[]`, to the end of the node you want to indicate is an array.
 
-##### Note: arrays of image urls at leaf nodes are currently not supported
-
 Given an object structure like this:
 
 ```javascript
@@ -192,7 +204,7 @@ module.exports = {
     {
       resolve: `gatsby-plugin-remote-images`,
       options: {
-        nodeType: 'myNodes',
+        nodeType: 'MyNodes',
         imagePath: 'nodes[].imageUrl',
       },
     },
@@ -216,4 +228,65 @@ allMyNodes {
 }
 ```
 
-##### Note: While `lodash .get` doesn't natively support this syntax, it is still used to traverse the object structure, so [the documentation for `.get`](https://lodash.com/docs/4.17.11#get) still applies in full.
+**Note:** While `lodash .get` doesn't natively support this syntax, it is still
+used to traverse the object structure, so
+[the documentation for `.get`](https://lodash.com/docs/4.17.11#get) still
+applies in full.
+
+### Handling an Array of Image URLs
+
+In case your API offers an image path to an _array_ of images, instead of just
+one, there is a way to handle that with the plugin. For instances where there is
+an array somewhere along the _path to_ the images,
+[see above](#traversing-objects-with-arrays).
+
+For example, you API returns:
+
+```javascript
+// MyNode
+{
+  date: '1-1-2010',
+  category: 'cats'
+  // Note that here there are multiple images at the *leaf* node where the images are found.
+  images: [
+    'https://.../image1.png',
+    'https://.../image2.png'
+  ]
+}
+```
+
+To make your local image field an array of these images, adjust your config
+accordingly:
+
+```javascript
+ {
+   resolve: `gatsby-plugin-remote-images`,
+   options: {
+     nodeType: 'MyNodes',
+     // Making this plural (optional).
+     name: 'localImages',
+     // Path to the leaf node.
+     imagePath: 'images',
+     // Set type to array.
+     type: 'array'
+   }
+}
+```
+
+Now, if we query `allMyNodes` we can query as we would any gatsby-image node,
+but now `localImage` (or `localImages` as in the example above) we would get an
+array of Gatsby images, instead of just one.
+
+```graphql
+allMyNodes {
+  nodes {
+    localImages {
+      childImageSharp {
+        fluid(maxWidth: 400, maxHeight: 250) {
+          ...GatsbyImageSharpFluid
+        }
+      }
+    }
+  }
+}
+```
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gatsby-plugin-remote-images",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Gatsby plugin to use gatsby-image on remote images from absolute path string fields on other nodes.",
   "author": "Grayson Hicks <graysonhicks@gmail.com>",
   "main": "gatsby-node.js",
@@ -36,8 +36,8 @@
     "prettier": "^1.19.1"
   },
   "dependencies": {
-    "gatsby-source-filesystem": "^2.0.11",
-    "lodash": "^4.17.11"
+    "gatsby-source-filesystem": "^2.3.14",
+    "lodash": "^4.17.15"
   },
   "scripts": {
     "build": "babel src --out-dir . --ignore **/__tests__",