Installation

npm i @ncwidgets/file-relation

Important

Please check your netlify-cms-app/netlify-cms version: @ncwidgets/[email protected] is only compatible with netlify-cms-app version 2.9.7 and below. Use @ncwidgets/file-relation^0.5.2 for netlify-cms-app^2.11.32.

Demo

In the demo below, the categories field is loaded from a file collection.

Live demo

Register

import cms from 'netlify-cms-app'
import { Widget as FileRelationWidget } from '@ncwidgets/file-relation'

cms.registerWidget(FileRelationWidget)

cms.init()

Example use

How to Use

How to use

Example config

collections:
  - label: Posts
    label_singular: Post
    name: posts
    folder: _posts
    create: true
    fields:
      - label: Categories
        name: cats

        # Default widget name
        widget: ncw-file-relation

        # Collection name
        collection: setting

        # The name of the file in that collection
        file: categories

        # The field that is a list
        target_field: categories

        # The field that will be used to store data
        # Only applicable to list with multi fields
        id_field: id

        # <Optional> The field that will be used to show as options
        # - Only applicable to list with multi fields
        # - If not specified, id_field will be used as label
        display_fields: name # or an array of fields: ["name", "desc"]

        # <Optional> Compose a label from a string template
        # - If specified, will disable display_fields
        display_summary: "{{name}} | {{desc}}"

        # <Optional> Allow multiple selection
        multiple: true 

The above configuration will target the following file collection:

collections:
  - label: Setting
    name: setting  # <---- 'collection'
    files:
      - label: Categories
        name: categories  # <---- 'file'
        file: _data/_cats.json
        fields:
          - label: Categories
            name: categories # <---- 'target_field'
            widget: list
            allow_add: true
            fields:
              - label: Name
                name: name # <--- 'display_fields'
                widget: string

              - label: Description
                name: desc
                widget: text

              - label: ID
                name: id # <---- 'id_field'
                widget: ncw-id
                prefix: cats

Say you have the following data in your file collection:

{
  "categories": [{
    "name": "Cat",
    "desc": "Cats are cool",
    "id": "cats-GQnCNUpF2"
  }, {
    "name": "Dog",
    "desc": "Dogs are alright",
    "id": "cats-S_Aev5Ts-B"
  }, {
    "name": "Hippo",
    "desc": "Hippo is love",
    "id": "cats-1wpAUDyA-W"
  }]
}

The data will be stored in the post as follow:

{
  "title": "Hej världen!",
  "id": "post-HahELOG49",
  "categories": [{
    "value": "cats-GQnCNUpF2",
    "label": "Cat"
  }, {
    "value": "cats-S_Aev5Ts-B",
    "label": "Dog"
  }]
}

Contribute

Found a bug or a missing feature? Please feel free to send over a PR, or open an issue with the bug or enhancement tag.