@morningtrain/react-resources

React Resources

Concepts

The following section describes the different concepts introduces in this package.

Mentioned features are not exhaustive but will highlight core features. Extra features not mentioned here are mainly used internally by the package or are outdated.

Model

A model is at its core a JavaScript Map that is made observable using Mobx. It represents an object containing data that can be used throughout the React application.

Models are mostly used to represent a single (database) entry retrieved through an API. It can however be anything.

This package provides the following related features:

Model

The Model component will execute and API request to the operation matching the props and will provide a Model object with the results to any child components.

import React from 'react'
import { Model } from '@morningtrain/react-resources'

export default function MyComponent() {
  return (
    <Model namespace={'api'} resourceName={'users'} operationName={'read'}>
      {/* Components that will read from model */}
    </Model>
  )
}

ModelWithForm

This component extends the Model component but adds a form element.

The form element will submit to and refresh model through the specified API endpoints when paired with a model.

useModel

A hook to retrieve the nearest model. It will be the model provided through the ModelContext.

import React from 'react'
import { useModel } from '@morningtrain/react-resources'

export default function MyComponent() {
  const model = useModel()
  
  /// Any other logic in MyComponent
}

useValue

A hook to retrieve a value from the nearest model. The path provided to the hook supports dot notation for getting nested values.

Any updates to the value in the model will trigger a rerender of the component with the updated value.

import React from 'react'
import { useValue } from '@morningtrain/react-resources'

export default function MyComponent() {
  const value = useValue('path.to.value')
  
  /// Any other logic in MyComponent
}

WhenModel

Conditional component to only render child components when a model is provided and when the provided model has data.

WhenModelValue

Conditional component to only render child components when a value in the model matches certain conditions.

It takes 3 props:

name - Path to value in the model. Dot-notation is supported to get nested values.

condition - It will try to match the value to this prop directly. A function can be passed which will get the current value as a parameter. If the prop is not provided, then it will check if the value is neither null nor undefined.

negate - Boolean to reverse the conditional. Defaults to false.

Collection

A collection is an observable mobx array of models.

This package provides the following related features:

Collection

This is the primary component for calling an API endpoint and providing the resulting array as a collection instance to any child components.

import React from 'react'
import { Collection } from '@morningtrain/react-resources'

export default function MyComponent() {
  return (
    <Collection namespace={'api'} resourceName={'users'} operationName={'index'}>
      {/* Components that will read from collection */}
    </Collection>
  )
}

useCollection

A hook to retrieve the nearest collection. It will be the collection provided through the CollectionContext.

import React from 'react'
import { useCollection } from '@morningtrain/react-resources'

export default function MyComponent() {
  const collection = useCollection()
  
  /// Any other logic in MyComponent
}

ForEachModel

The ForEachModel component will loop over the collection and provide a model for each entry.

Any children provided to the component will be rendered for each entry.

import React from 'react'
import { Collection, ForEachModel } from '@morningtrain/react-resources'

export default function MyComponent() {
  return (
    <Collection namespace={'api'} resourceName={'users'} operationName={'index'}>
      <ForEachModel>
        {/* Components that will read from the model */}
      </ForEachModel>
    </Collection>
  )
}

ValueToCollection

WhenCollectionIsEmpty

A conditional component that will render its children when the closest collection instance does not have any entries.

This component can be used to display a fallback component when the collection is missing entries.

WhenCollectionIsNotEmpty

A conditional component that will render its children when the closest collection instance do have entries.

This component can be used to only start displaying the UI when the Collection has been created.

Selection

A selection is a class that keeps track of which items in a given collection has currently been selected.

These features are mostly used to support multi-select in tables by checking checkboxes in a table. The concepts are however abstract enough to be used for other scenarios where something from a list of items needs to be selected.

This package provides the following related features:

Selection

This is the primary component for creating and providing a Selection instance to child components.

The selection needs to be provided with a collection instance to work. It can either be provided manually using CollectionContext or through Collection.

import React from 'react'
import { Collection, Selection } from '@morningtrain/react-resources'

export default function MyComponent() {
  return (
    <Collection namespace={'api'} resourceName={'users'} operationName={'index'} >
      <Selection>
        {/* Components using the selection */}
      </Selection>
    </Collection>
  )
}

The selection will use id as the key to get the unique identifier of the model entry. When using a model with a different key, the modelKeyName prop should be supplied to the selection.

SelectOnPipe

This component is a pipe (see pipeline docs) to select an entry when piping.

Multi-select is enabled by default. This can be turned off by setting the multiple prop to false. When multi-select is not enabled, then the selection will be cleared upon selecting something new.

The SelectOnPipe component needs to be placed inside a model for it to figure out which items to select.

It could be used together with an OnClickPipeline to select collection items on click events.

ClearSelectionOnPipe

This component is a pipe (see pipeline docs) to clear (reset) the selection object when piping.

ClearMissingSelectionOnExecute

This component will react to any changes to the provided collection and validate the currently selected items.

If any of the currently selected items are missing from the collection, then these entries will be unselected.

This functionality can be used to clear selected items when paginating or filtering the collection.

SelectedToCollection

When placed inside a selection, it will provide a new collection to its children that is a copy of the original collection filtered to the currently selected items.