WIP: Relations/Tags/TBD Widget Feature

[moonmeister]

Summary

Associating objects from another collection with specific content. My personal use case was inputting computer languages/technologies into one collection that I could then use to tag on a project in another collection for a personal portfolio.

Additionally, there are at least 3 feature requests for this... #391, #1061 , kinda #1050.

Also:

1. I'm new to js/react so I wouldn't be surprised if I committed some terrible faux pas. Please educate me and please review my code closely.

2. Below I've gathered my own thoughts and tried to pullin the features I've seen mentioned on various feature requests.

3. If anyone else wants to contribute to the PR feel free.

4. Thanks to @erquhart and @tech4him1 for answering my questions on ✨Gitter✨, this was made possible and my ignorance was lessened.

Work in Progress

Questions

1. Does this upgrade the relation field or is it an alternative?
   • If we replace it we need to assure config compatibility for those upgrading. We could make the default mimik the relation widgets current functionality.
   • If it's an alternative is the relations name confusing cause it's so similar. Or useful cause it explains the functionality is similar to that of the relation widget
2. Do we render anything in preview?
   • Like the boolean widget it seems kinda necessary for simple tags.
   • BUT, if you're trying to include a related post or some other content...then seeing a preview could be useful.
   • Maybe make this a config option?
3. I copied a lot of code to implement the autocomplete functionality from the relation widget. Though I'm unsure how to, I'm guessing it'd be best practice to make the common code a library or react component of some kind. yes?

Task List

Configuration

• Accepts a reference to a field in an entry containing a list of tags - not certain if we support this
• Accepts a number to limit the number of flags
• Accepts a flag to require unique tags
• Accepts a list of tags
• Accepts a flag to disallow entering tags that are not in the list / autocomplete results

Tag list editing

• Tags don't really belong in a normal entry, nor in settings, probably a third "meta" entry type*
• The difference in entry type really only affects it's appearance in the UI
• The editing experience itself will be configurable just like any collection entry*

*I honestly don't understand what these means @erquhart can you explain this.

Widget UI

• Autocomplete
• Pressing enter transforms the typed tag into a visual tag with an x for deleting
• Tags can also be removed via backspace
• Customizable input field placeholder text via config.
• Press space transforms the typed tag into a visual tag with an x for deleting
• Counter for number of tags currently over the tag limit. Maybe turns red when you hit limit. Maybe doesn't show a limit and just counts tags if you have no limit.

Test plan

So far it's been manual, I'm new at react/js so testing it uncharted territory for me.

Description for the changelog

Implements a tag style widget for creating one-to-many relationships.

our cats

[verythorough]

Deploy preview for netlify-cms-www ready!

Built with commit 291523d

https://deploy-preview-1100--netlify-cms-www.netlify.com

[verythorough]

Deploy preview for cms-demo ready!

Built with commit 291523d

https://deploy-preview-1100--cms-demo.netlify.com

[moonmeister]

Known Issues:

UI of the auto complete results
The autocomplete results look like:

Where the current relation autocomplete results look like:

This is due to the fact that the input is an inline-block that stays to the right of the inputted tags. If you make it not inline it drops below the tags but the results look correct. We just need to figure out what the UI should be exactly or if we can somehow disassociate the results from the input box.

The Random error of DOOM!...or just a type error
consistently you get a complete failure:

It only happens when there are no existing tags and you start typing something that will return an autofill result. It happens before you even select a result. More debugging needed.

[erquhart]

@moonmeister would you like a quick review of your work in progress or need any help?

[moonmeister]

Yeah. That'd be a good start. I proposed some questions above too that it'd be useful to answer.

[erquhart]

Sorry for the delay, some responses for the questions above:

Does this upgrade the relation field or is it an alternative?

I would think upgrade, we could use a multiselect boolean option in the config to enable it.

Do we render anything in preview?

In my experience tags are generally rendered in content, e.g. at the top of a blog post, so I'd expect to preview tags by default.

I copied a lot of code to implement the autocomplete functionality from the relation widget. Though I'm unsure how to, I'm guessing it'd be best practice to make the common code a library or react component of some kind. yes?

We shouldn't have to worry about it if this functionality is added to the relation widget.

Further considerations from #619:

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.

---

As pointed out by @bjrn in #619, this should build off of the work in progress from #1061 if possible. Haven't considered the implications of adding autocompletion to that.

[moonmeister]

Thanks for the update @erquhart . I'll read more in depth into this later but looks good so far. I should have time to work on this more soon.

[erquhart]

@moonmeister also note the mostly working multiselect (non-relation) implementation in #922.

[moonmeister]

@erquhart Looks like there has been some good work done on #922, I didn't see that when I posted/worked on this. The overall UI design looks identical. I guess then my main question is what's the difference? If the final UIs are going to be this similar and the defining differences in the plugin are features that may be very confusing for folks. If we define the specific use cases different and show that in how the UI functions then there is a case for different plugins. Things like autocomplete should be a feature of the plugin but should not require a different plugin. Thoughts?

On another note: I'm thinking it'd be really awesome if we could make it possible for a user to pass in a React object that defines how the the searched object renders in the preview and possibly the editor.

[erquhart]

react-select is a more versatile library with a lot of momentum. The customization of passing in a tag rendering component could be cool, but it may be best to consider that separately from the main goal here.

Questioning the differences did get me thinking in yet another direction, though: what if we combined the select, multi select, and relation widgets into a single, more versatile select widget? It would basically be the multiselect widget in the pr I linked, the underlying library being able to handle standard select among other things, and then getting relation data from other content becomes an internalized service that any widget can tap into.

Thoughts?

[erquhart]

Hmm did I just say what you said in a different way? I think I did lol

[moonmeister]

@erquhart Yeah, I think this is what I've been trying to get at with this PR. They're all trying to create a relationship from one object/widget/collection to another. Whether it's a one-to-one relationship or one-to-many can be a simple config choice. The Select and List widgets also fit this description. The List widget does too but due to it's complexity can be ignored for now.

Basically I think there should be a single widget that has different config options to change it's features. Those features should cover the needs that Select, Relation, and multi-select currently cover plus adding all the auto complete, and such that's been talked about here and other places.

I think we're on the same page now, also I support using the react-select library...it's clearly more popular and better maintained than what I used.

[erquhart]

@moonmeister I don't believe there are any other PR's in active development that parallel this. The multiselect widget PR is on pause. Is there anything specific you need to move forward with things? Couldn't recall if you specifically mentioned being blocked during the call, or if you just wanted a review of the latest work.

[moonmeister]

@erquhart I just had a chance to look over the multiselect widget...looks like that's way better than what I'm using and has tons of great features. I can pull the code from #922 and replace a lot of what I've done. I'll play around with it and get back to you on questions and next steps...I can already think of some but I'll probably answer some of my own questions working through the code.

[moonmeister]

@erquhart Okay, finally found some time to get started. So here's what I'm proposing to create using the react-select base. We "update" the select widget and include configuration options in it to support multiselect options. Additionally, instead of specifying a list of objects it'd be nice if we could specify another collection to be the source of the dropdown. For those using a predefined list there could be a setting allow items not on the list.

Theoretically the select widget would be backwards compatible. These changes would eliminate the need for the existing Relation widget and any new tags/multiselect widget.

Currently the multi select works, and is mostly compatible as a drop in replacement for the select widget. There's a couple bugs when you make it single select and I'd need to figure out building out the collection integration.

Thoughts?

[verythorough]

That sounds pretty awesome!

Additionally, instead of specifying a list of objects it'd be nice if we could specify another collection to be the source of the dropdown.

Another related feature people often request is to specify an individual file as the source of the dropdown.

I wonder what's the best way to handle overlap here with the relation widget?

[moonmeister]

@verythorough I hadn't thought of a file import. Shouldn't be too difficult. As for the Relation widget...I don't have any strong opinions on the subject. I would say maybe remove it from documentation or mark it as obsolete. then give folks some time to move over to the new widget? Maybe next major release finally just eliminate it from the code base.

[erquhart]

What you're saying makes sense @moonmeister. Regarding "file import", that boils down to selecting individual values from within an entry, versus the relation widget's current function of selecting an entry from a collection. That concern is voiced in #473, and should probably be handled subsequent to this PR.

I agree with deprecating the relation widget as well, since we'll soon be providing relations as a service within the CMS rather than as a standalone widget anyhow.

[moonmeister]

So, some news, I'm leaving town on April 28th to go backpacking on the Pacific Crest Trail from Mexico to Canada. This is a 5 month and 2650 mile journey.

Needless to say, I won't be able to contribute code from the trail. I was really hoping to get this finished, but I'm just not going to have the time to do it, let alone do it right. I'm really excited about these changes and maybe someone else can implement them. If not, I might when I'm back to civilization in October. Sorry again, I hate leaving this PR half done. If there's anything you need/want from me other than code before I leave let me know.

If anyone is interested in following my trek you can follow me on instagram @moon_meister

Thanks everyone who's helped define what this PR should be...hope it happens eventually!

[erquhart]

Sounds awesome @moonmeister - thanks for the heads up, and enjoy the trip!!

[erquhart]

Closing as stale.