Widget docs a bit thin

[benogle]

I setup netlify cms for the first time yesterday and had / still have some trouble getting the widgets to do what I want(ed). There is a lot here, but I thought it better to be cohesive than 6 issues. Here was my discovery process after having known what a widget was for < 5 minutes.

First I went to the quick start, and setup my config. There is a section of the widgets in the collections section, and the table indicates some widgets. Initially I thought that those were all the widgets that were supported. I admittedly didnt see the Widgets link on the left sidebar. A link to the widgets page would have been nice right after the table e.g. 'here are all the widgets we support'.

I wanted an enum widget or something like it, so I searched google for enum widget, to no avail. I finally found the widgets link in the sidebar, and saw that there is a select and a list widget.

The list widget seemed like a candidate, but was a little complicated to grok at first. I think an image of the what each of the examples produces would be helpful.

The object widget seems like I could probably use it and there are probably many options, but there is no example section, so I am not sure what it is for.

The select widget has no example or usage instructions, but seemed like the best candidate. So I searched for it (https://www.google.com/search?q=netlify+select+widget) but didnt come up with anything specific, so I wasnt sure.

The top result was https://github.com/netlify/netlify-cms/blob/master/example/config.yml, which was huge. Yay, examples. IMO, this should be linked to in the Widgets docs page.

But there is a lot there that is not covered in any docs. e.g. File and folder collections. Nested collections

The settings.author situation seems really interesting, and it seems like I could reference the authors in a relation widget. But none of the relation examples show how to work with a nested collection. What goes in the collection field? authors? settings.authors? Something else? I couldnt get anything to work (Cannot read property 'get' of undefined on the post page). I also tried a top level collection:

collections:
  - name: "authors"
    label: "Authors"
    file: "_data/authors.yml"
    description: "Author descriptions"
    fields:
      - name: authors
        label: Authors
        ...

But that gave me an error about collections being a file or folder. There is a file specified, I thought, but it seems there needs to be files or folder.

Overall, I felt like I was constantly guessing and checking when setting up the config. There are other more complicated things I want to do like have a list of categories we can pick in the post UI, get the authors relation to work, etc. But I am hesitant to spend a bunch of time spelunking, so most everything is a string.

It would be nice to have a some really complete examples that show all the things that are possible linked to from the widget docs page. Or complete for common usecases. The example authors case would be amazing if a relation widget handled it in the example config. I assume a categories or tags case could be handled similarly.

I see there is #598 so maybe these things are slated in that work. Hopefully this account is helpful. I've written my share of docs, and it is always hard to know where people get stuck.

[Benaiah]

Thanks a lot for the issue. I already knew our docs needed some work, but it's great to have reports of particularly sparse areas that are tripping people up.

[verythorough]

Thanks for the detailed report! I'm using this issue to track improvements to the widget docs as I break up the outline from #598. Here's the Widgets section:

• Built-in widgets

  • Intro to widgets, link to config
  • Reference listing for every type of widget, with the following:
    • UI sample (screenshot, gif, or working demo)
    • required/optional fields, defaults
    • sample config for more complex widgets (like list)

• Custom widgets

  • Adapt, update, improve extending.md
  • Include advanced validation info from validation.md

The UI sample part may wait until the new UI is in place, but the rest can start now, and would definitely be an improvement.

[verythorough]

Just noticed that #486 is related to this work as well.

[syariffudinzo]

Take me hours to understand the widget parts, I'm pretty new in static CMS and finally found this issue posted! pheew thanks @benogle for pointing it out.

[hdoro]

@benogle you pretty much described my journey as well, a lot of hours were spent with browsersync and a trial and error process with the config.yml file!
I'm nowhere proficiente as I'd like to be, so that's why I've set myself the task to help redesigning the widgets page, and the first step, in my opinion, is changing the widgets table. I explored this into further detail on #486 but I'd love to have your contribution to it as well 😄

[erquhart]

I don't have time this red hot second, but we should make a list of the specific issues outlined in @benogle's OP and check them off before closing. Even after @verythorough's extensive reboot of our documentation, a number of them still need to be addressed, such as images of how the widget looks to aid in grokability.

@hcavalieri's PR will help a ton :)

[verythorough]

Here's what I've pulled from the OP:

• Link to Widgets doc from Quick Start (now "Add to your site")
• Link to the example config from the Widget doc
• Add code examples for each widget type
• Add docs about file/folder collection types
• Add working demos for docs code snippets into example config (including a working relation widget) (Add widget doc demo collection to example config #910)
• Add demo UI screenshot for each code snippet (relies on Add widget doc demo collection to example config #910)
• Document limitations of the relation widget, specifically that it searches whole files, not fields within a single file, so it requires a folder collection (which is good for a multi-field item like an author, but can feel clunky for a single-field item like a tag).
• Add a note that the select widget is good for enum use cases? (Is this a mobile app dev thing? I've never encountered that term in web dev, so I'm not positive about the accuracy of that suggestion.)
• Add information about nested collections? (I think this specifically refers to file collections nested under a files collection. Specifically, how to refer to a collection configured like this in, for example, a relation widget)

I can file an issue (#910) for adding the widget code samples to the example config and then screenshotting them for the Widget doc.

For the relation widget limitation, I can add that note about as quickly as I can write an issue for it, so I'll just make a PR. (#911)

For the last two items (enum widgets and nested collections), @benogle could you confirm that I've characterized your issue properly?

[Benaiah]

@verythorough an enum is just a programming term for a variable type that is a member of a given list of constants - so if your enum had "a", "b", and "c", "a" would be a valid member of the enum, but "d" wouldn't. It's usually used in statically-typed languages, so it doesn't show up in JS programming much. That suggestion about enum therefore sounds like good advice to me - not sure how else you'd model that to be honest outside of an arbitrary string input + validation.

[benogle]

@benogle could you confirm that I've characterized your issue properly?

Yep, this list seems great, and the docs look better already. ❤️ ❤️ for taking my rambling account super seriously :)

[ffdead]

What is the solution to @benogle's original question?

How do I specify a relation to a nested collection like that? I'm trying to add post authors - feels like a quite common use case so I'm curious how to solve this?

Thanks!

[verythorough]

@ffdead Previously missing and erroneous information in the docs implied that it was possible to create a single-file "collection" and nest it under a files collection, leading people to think that the relation widget could search the contents of a single file and match on a single object within the file. In fact, relation widget matching only works by selecting whole files in a single folder.

We've revised the Collection Types doc to clarify the available options: a collection can be either a folder type, with a template defining all files within it, or a files type, with individually configured files defined within it.

In the case of having an author collection, I'd recommend making a folder collection called 'Authors' and have each file in the collection represent a single author. If you have thoughts on how to clarify that in the relation widget doc, that'd be a great docs contribution. :)

[bjrn]

@verythorough Hi, I'm trying to wrap my head around this: so if I just like to have a relation field in a blog post called "tags", and it's a pretty much preset list (and a tag only has a name prop) … In order to build a usable relation field I then need to create a folder "tags" as a collection where each tag must have its own file?

I've seen plenty of examples having an authors.yml file where all authors are listed, but that won't work as a relation field?

If I'd still prefer to have the list of tags in a single file, would that require building a custom widget?

[erquhart]

Yep, the relation widget works only at the entry level - it can select an entire entry and utilize a field within that entry. What you need is to search within a specific file in files type collection, and select multiple items from an iterable field within that entry. This isn't currently possible.

I would expect that this functionality could be patched onto the existing relation widget, and you'd provide an additional file property, and the collection would have to be a files type collection. To select from a file with a configured name tags in a files collection named meta, config could look like this:

# config.yml
collections:
  - name: meta
    label: Meta
    files:
      - name: tags
        label: Tags
        file: data/tags.yaml
        fields:
          - name: tags
            label: Tags
            widget: list
            fields: [{ name: tag, label: Tag }]
  - name: blog
    label: Blog
    create: true
    folder: content/blog
    fields:
      - { name: title, label: Title }
      - { name: body, label: Body, widget: markdown }
      - name: tags
        label: Tags
  		widget: relation
  		collection: meta
  		entry: tags
  		searchFields: ['tags']
  		multiselect: true

# data/tags.yml
- { tag: my-tag }
- { tag: another-tag }

• The entry field would match against the name of a file entry in the collection.
• searchFields would be optional, and assume the file is an array of values by default.
• valueFields would also be optional, defaulting to the entire array value.
• This would make adding a displayField property, as attempted in Add a displayField property to the relation widget #594, even more crucial (so you can configure which field to display if your file is an array of objects).

Unfortunately Netlify CMS doesn't support data files that contain a top level array, but that would make this even better. Support for that is in the works under #468.

[bjrn]

Thanks for the pointers @erquhart! I'll take a closer look at the relation widget. Both PRs you mentioned seems to be inactive, but still functionality you'd like to see added to the project right?

Also, seems like there's a few other related WIPs: #922 (multiselect for fixed values that can be set in the config.yml) and #1100

[erquhart]

@bjrn good point. The author of #1100 is very open to help, and I've added comments based on what was discussed here, let's move this conversation to that PR.

[verythorough]

I'm going to close this as it has generally been fixed or covered in other ways. Looking at he unchecked items in the list in my comment above:

• Demos and screenshots are requested in issue Add widget doc demo collection to example config #910 .
• Improved docs for select and list widgets should make it easier to identify them as good candidates for enum-style data.
• "Nested" collections are now correctly described as files collections.
• The relation widget restrictions are clearer now that the non-existent single-file collection is no longer erroneously included in the collection types doc.
• Existing PRs may soon provide relation-widget functionality for fields in a single file (like an authors.yml).

[benogle]

I appreciate you all doing something with this. So many projects would just let a rambly issue like this languish.