Add documentation for Data File collections. #656

tech4him1 · 2017-10-05T13:57:25Z

- Summary
This adds documentation for how to use specific data files in a collection. Th example is copied from /example/config.yml.

NOTE: This will need a PR on the site to add the new page before it gets merged.

- Test plan
N/A -- docs

- Description for the changelog
Add documentation for Data File collections.

- A picture of a cute animal (not mandatory but encouraged)

erquhart · 2017-10-05T15:09:35Z

docs/quick-start.md

@@ -211,6 +211,44 @@ collections:
    fields:
      - {label: "Language", name: "language"}
 ```
+
+### Data Files


What you're describing here isn't actually specific to data files, it's actually about the files type collection (versus the folder type collection). Markdown files can work this way, too.

We should update this title accordingly, and have a separate section about the types of files we support (with examples). We should also move this out of quick start, I think it should all go in a new "Collections" page for now.

tech4him1 · 2017-10-05T16:11:03Z

@erquhart How does this look?

erquhart

@tech4him1 thanks so much for this! Bunch of fun change requests for you 😛

erquhart · 2017-10-05T21:08:50Z

docs/collections.md

+# Collections
+Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different from one site to the next.
+
+Let's say your site has a blog, with the posts stored in `_posts/blog`, and files saved in a date-title format, like `1999-12-31-lets-party.md`. Each post begins with settings in yaml-formatted front matter, like so:


Mix in a little more explanation that, based on the scenario, it would be best to use a folder type collection.

Also, "settings in YAML front matter".

erquhart · 2017-10-05T21:09:47Z

docs/collections.md

+    <td>Where files of this type are stored, relative to the repo root.</td>
+  </tr>
+  <tr>
+  <td><code><em>files</em></code></td>


Drop the em tags.

erquhart · 2017-10-05T21:12:37Z

docs/collections.md

+  </tr>
+  <tr>
+    <td><code>folder</code></td>
+    <td>Where files of this type are stored, relative to the repo root.</td>


Instead: 'Indicates that this is a "folder" type collection, with every file in the folder being an instance of the collection, all sharing the same fields.' Cannot be used with the files setting.

erquhart · 2017-10-05T21:15:30Z

docs/collections.md

@@ -0,0 +1,138 @@
+# Collections
+Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different from one site to the next.
+


Add a second level "Folder Type Collections" header.

erquhart · 2017-10-05T21:17:17Z

docs/collections.md

+      - {label: "Rating (scale of 1-5)", name: "rating", widget: "number"}
+      - {label: "Body", name: "body", widget: "markdown"}
+```
+


Move the Files section here.

erquhart · 2017-10-05T21:17:57Z

docs/collections.md

+      - {label: "Language", name: "language"}
+```
+
+## Files


Change to "Files Type Collections", and move below the "Folder Type Collections section", just before the table of properties.

erquhart · 2017-10-05T21:18:59Z

docs/collections.md

+
+As described above, the `widget` property specifies a built-in or custom UI widget for a given field. The first field in the example, `layout`, uses a `hidden` widget. This widget will not show in the editor UI, but will be saved with the `default` value (assuming it's been set) in the document front matter. The rest of the widgets work as follows:
+
+Widget | UI | Data Type


Instead of this table, just link to the Widgets page.

erquhart · 2017-10-05T21:19:49Z

docs/collections.md

+  </tr>
+  <tr>
+    <td><code>fields</code></td>
+    <td>Fields listed here are shown as fields in the content editor, then saved as front matter at the beginning of the document (except for <code>body</code>, which follows the front matter). Each field contains the following properties:


Append the last sentence to mention that some field/widget types have additional params, and link to the Widgets page for reference.

erquhart · 2017-10-05T21:20:35Z

docs/collections.md

+Based on this example, you can go through the post types in your site and add the appropriate settings to your `config.yml` file. Each post type should be listed as a separate node under the `collections` field.
+
+## Filter
+The entries for any collection can be filtered based on the value of a single field. The example collection, below, would only show post entries with the value "en" in the language field.


"The example collection below" (drop commas).

erquhart · 2017-10-05T21:21:22Z

docs/collections.md

@@ -0,0 +1,138 @@
+# Collections
+Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different from one site to the next.


Note that the examples below are present in the CMS repo example, and link to the relevant source.

tech4him1 · 2017-10-05T21:26:45Z

docs/quick-start.md

@@ -114,103 +114,8 @@ This configuration adds a new setting, `public_folder`. While `media_folder` spe
 >If `public_folder` is not set, Netlify CMS will default to the same value as `media_folder`, adding an opening `/` if one is not included.

 ### Collections
-Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different from one site to the next.
+Collections define the structure for the different content types on your static site. They will be the main part of your config, and are explained in detail on the [Collections](collections.md) page.


@erquhart Is it good to drop everything except this from the quick-start page?

Yeah, that's fine.

verythorough · 2017-10-05T22:35:45Z

Thanks for creating this file! I started an outline for a Collections page within the larger docs outline in #598. I'd be curious to know what y'all think of it:

Collections: file, folder, filter
(explain the differences, show config examples for each)
- file:
  - single file or grouping of files, with fields specified for each file individually
  - can be useful for data files with settings or highly customized pages
  - cannot be filtered; cannot add new items
- folder:
  - grouping of separate files based on the same template, stored in the same folder
  - UI field will be identical for all items in the folder (or all matching the filter)
  - may or may not be able to add new items (depending on create field)
- filter:
  - used with folder type
  - can be used to pull only items matching the specified field value
  - requires field and value: must be an exact match
- Note: regardless of collection type, each item in the main area of the collection browser represents a separate file (though separate files may be combined into a single published page via templating)

Of course, even if we agree to that outline that doesn't mean it's what the initial content here has to be. However, we also seem to be working with conflicting purposes at the moment in the docs, because I've PR'd a bunch of edits to the Quick Start that would conflict significantly here. I suggest we discuss in #598 how to break that outline up into issues that can be tackled separately without stepping on each others' work.

tech4him1 · 2017-10-06T23:02:17Z

@verythorough That outline looks great. Do you suggest that we just close this one for now, and incorporate it as part of your main PRs?

verythorough · 2017-10-06T23:12:19Z

I think that makes sense. I'll update the current Quick Start based on review (and to incorporate the 0.5.0 release!), then figure we merge that in as a short term solution. In the meantime, I'll break #598 into smaller, more actionable issues.

I think it will make sense to talk about the role of the Quick Start in the new hierarchy. It was written under the auspices of "We don't have time for you to write full docs, so fit as much as you can into a quick tutorial." Now that we'll have full docs, I'm not even sure a tutorial will be necessary. I suppose we can discuss it further in a specific issue. :)

tech4him1 · 2017-10-06T23:18:29Z

Closed in favor of #598.

tech4him1 requested review from erquhart and verythorough October 5, 2017 13:57

erquhart suggested changes Oct 5, 2017

View reviewed changes

Add documentation for Data File collections.

8530534

tech4him1 force-pushed the data-file-docs branch from 9d21c44 to 8530534 Compare October 5, 2017 16:09

erquhart suggested changes Oct 5, 2017

View reviewed changes

tech4him1 commented Oct 5, 2017

View reviewed changes

tech4him1 closed this Oct 6, 2017

verythorough mentioned this pull request Oct 11, 2017

Add Collection Types doc #679

Closed

tech4him1 deleted the data-file-docs branch December 12, 2017 02:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for Data File collections. #656

Add documentation for Data File collections. #656

tech4him1 commented Oct 5, 2017 •

edited

Loading

erquhart Oct 5, 2017

tech4him1 commented Oct 5, 2017

erquhart left a comment •

edited

Loading

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

erquhart Oct 5, 2017

tech4him1 Oct 5, 2017

erquhart Oct 5, 2017

verythorough commented Oct 5, 2017

tech4him1 commented Oct 6, 2017

verythorough commented Oct 6, 2017

tech4him1 commented Oct 6, 2017

		@@ -0,0 +1,138 @@
		# Collections
		Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different from one site to the next.


		As described above, the `widget` property specifies a built-in or custom UI widget for a given field. The first field in the example, `layout`, uses a `hidden` widget. This widget will not show in the editor UI, but will be saved with the `default` value (assuming it's been set) in the document front matter. The rest of the widgets work as follows:

		Widget \| UI \| Data Type

Add documentation for Data File collections. #656

Add documentation for Data File collections. #656

Conversation

tech4him1 commented Oct 5, 2017 • edited Loading

Choose a reason for hiding this comment

tech4him1 commented Oct 5, 2017

erquhart left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

verythorough commented Oct 5, 2017

tech4him1 commented Oct 6, 2017

verythorough commented Oct 6, 2017

tech4him1 commented Oct 6, 2017

tech4him1 commented Oct 5, 2017 •

edited

Loading

erquhart left a comment •

edited

Loading