From 03714f8d1bd83eab92eaa45d6cb8341d9cb9bba3 Mon Sep 17 00:00:00 2001
From: Shawn Erquhart <shawn@shawn.works>
Date: Mon, 6 Mar 2017 17:57:43 -0500
Subject: [PATCH] add documentation for widgetsFor helper

---
 docs/extending.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 91 insertions(+), 1 deletion(-)

diff --git a/docs/extending.md b/docs/extending.md
index 2fb44d23..82d4d57d 100644
--- a/docs/extending.md
+++ b/docs/extending.md
@@ -37,9 +37,10 @@ Registers a template for a collection.
 **React Component Props:**
 
 * collection: The name of the collection which this preview component will be used for.
-* react_component: A React component that renders the collection data. Three props will be passed to your component during render:
+* react_component: A React component that renders the collection data. Four props will be passed to your component during render:
   * entry: Immutable collection containing the entry data.
   * widgetFor: Returns the appropriate widget preview component for a given field.
+  * [widgetsFor](#lists-and-objects): Returns an array of objects with widgets and associated field data. For use with list and object type entries.
   * getAsset: Returns the correct filePath or in-memory preview for uploaded images.
 
 **Example:**
@@ -63,6 +64,95 @@ CMS.registerPreviewTemplate("posts", PostPreview);
 </script>
 ```
 
+### Lists and Objects
+The API for accessing the individual fields of list and object type entries is similar to the API
+for accessing fields in standard entries, but there are a few key differences. Access to these
+nested fields is facilitated through the `widgetsFor` function, which is passed to the preview
+template component during render.
+
+**Note**: as is often the case with the Netlify CMS API, arrays and objects are created with
+Immutable.js. If some of the methods that we use are unfamiliar, such as `getIn`, check out
+[their docs](https://facebook.github.io/immutable-js/docs/#/) to get a better understanding.
+
+**List Example:**
+
+```html
+<script>
+var AuthorsPreview = createClass({
+  // For list fields, the widgetFor function returns an array of objects
+  // which you can map over in your template. If our field is a list of
+  // authors containing two entries, with fields `name` and `description`,
+  // the return value of `widgetsFor` would look like this:
+  //
+  // [{
+  //   data: { name: 'Mathias', description: 'Co-Founder'},
+  //   widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
+  // },
+  // {
+  //   data: { name: 'Chris', description: 'Co-Founder'},
+  //   widgets: { name: (<WidgetComponent>), description: (WidgetComponent>)}
+  // }]
+  //
+  // Templating would look something like this:
+
+  render: function() {
+    return h('div', {},
+
+      // This is a static header that would only be rendered once for the entire list
+      h('h1', {}, 'Authors'),
+
+      // Here we provide a simple mapping function that will be applied to each
+      // object in the array of authors
+      this.props.widgetsFor('authors').map(function(author, index) {
+        return h('div', {key: index},
+          h('hr', {}),
+          h('strong', {}, author.getIn(['data', 'name'])),
+          author.getIn(['widgets', 'description'])
+        );
+      })
+    );
+  }
+});
+
+CMS.registerPreviewTemplate("authors", AuthorsPreview);
+</script>
+```
+
+**Object Example:**
+
+```html
+<script>
+var GeneralPreview = createClass({
+  // Object fields are simpler than lists - instead of `widgetsFor` returning
+  // an array of objects, it returns a single object. Accessing the shape of
+  // that object is the same as the shape of objects returned for list fields:
+  //
+  // {
+  //   data: { front_limit: 0, author: 'Chris' },
+  //   widgets: { front_limit: (<WidgetComponent>), author: (WidgetComponent>)}
+  // }
+  render: function() {
+    var entry = this.props.entry;
+    var title = entry.getIn(['data', 'site_title']);
+    var posts = entry.getIn(['data', 'posts']);
+
+    return h('div', {},
+      h('h1', {}, title),
+      h('dl', {},
+        h('dt', {}, 'Posts on Frontpage'),
+        h('dd', {}, this.props.widgetsFor('posts').getIn(['widgets', 'front_limit']) || 0),
+
+        h('dt', {}, 'Default Author'),
+        h('dd', {}, this.props.widgetsFor('posts').getIn(['data', 'author']) || 'None'),
+      )
+    );
+  }
+});
+
+CMS.registerPreviewTemplate("general", GeneralPreview);
+</script>
+```
+
 ### Accessing Metadata
 Preview Components also receive an additional prop: `fieldsMetaData`. It contains aditional information (besides the plain plain textual value of each field) that can be useful for preview purposes.