# @ncwidgets/file-relation

> Netlify custom widget file relation

Latest version **0.9.0** (published 2021-04-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ncwidgets/file-relation
pnpm add @ncwidgets/file-relation
yarn add @ncwidgets/file-relation
bun add @ncwidgets/file-relation
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2021-04-21 |
| First published | 2019-07-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 12.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 91 |
| Author | Derek Nguyen |
| Maintainers | d4rek |

## Links

- npm: https://www.npmjs.com/package/@ncwidgets/file-relation
- Repository: https://github.com/d4rekanguok/netlify-cms-widgets
- Homepage: https://github.com/d4rekanguok/netlify-cms-widgets#readme
- Issues: https://github.com/d4rekanguok/netlify-cms-widgets/issues
- npm.io page: https://npm.io/package/@ncwidgets/file-relation

## Dependencies (5)

- [react](https://npm.io/package/react.md) ^16.8.6
- [immutable](https://npm.io/package/immutable.md) ^4.0.0-rc.12
- [react-select](https://npm.io/package/react-select.md) ^3.0.4
- [netlify-cms-ui-default](https://npm.io/package/netlify-cms-ui-default.md) ^2.6.3
- [netlify-cms-lib-widgets](https://npm.io/package/netlify-cms-lib-widgets.md) ^1.3.0

## Recent versions

- 0.9.0 (latest) — 2021-04-21
- 0.8.0 — 2020-05-06
- 0.7.4 — 2020-05-06
- 0.7.0 — 2020-04-09
- 0.6.1 — 2020-03-22
- 0.6.0 — 2020-03-22
- 0.5.2 — 2020-03-21
- 0.5.0 — 2019-08-22
- 0.4.0 — 2019-08-07
- 0.3.0 — 2019-08-02
- 0.2.0 — 2019-07-26
- 0.1.0 — 2019-07-23

## README

<h1 align="center">File Relation Widget for NetlifyCMS</h1>

<p align="center">A widget for <a href="https://www.netlifycms.org/" target="_blank">netlify-cms</a> to dropdown select from a file collection instead of a folder collection.</p>

---

<p align="center">⚠ Unstable: Under active development</p>

## Installation
```
npm i @ncwidgets/file-relation
```

## Important

Please check your `netlify-cms-app`/`netlify-cms` version:
`@ncwidgets/file-relation@0.5.0` 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.

<a href="https://custom-widgets.netlify.com/#/collections/posts/entries/hej" target="_blank">Live demo</a>

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

cms.registerWidget(FileRelationWidget)

cms.init()
```

## Example use
How to Use

<img src="../../assets/ncw-file-relation.png" width=50%>

## How to use
### Example config

```yml
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:
```yml
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:
```json
{
  "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:
```json
{
  "title": "Hej världen!",
  "id": "post-HahELOG49",
  "categories": [{
    "value": "cats-GQnCNUpF2",
    "label": "Cat"
  }, {
    "value": "cats-S_Aev5Ts-B",
    "label": "Dog"
  }]
}
```

<p>Read more about configuration options on <a href='https://www.netlifycms.org/docs/configuration-options/'  target="_blank">netlifyCMS</a>.</p>


## 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.

---
_Source: https://npm.io/package/@ncwidgets/file-relation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._