Editor Component

Usage

// 'contract-crudeditor' package.
import React from 'react';

import createEditor, {
  VIEW_SEARCH,
  VIEW_CREATE,
  VIEW_EDIT,
  VIEW_SHOW
} from '@opuscapita/react-crudeditor';

const ContractEditor = createEditor(<Model Definition>);
export default ContractEditor;

// application.
import React from 'react';
import ContractEditor from 'contract-crudeditor';

export default class extends React.Component {
  render() {
    return (
      ...
      <ContractEditor
        ?view={?name: <string>, ?state: <object>}
        ?onTransition={<function>}
        ?externalOperations={<function>}
        ?uiConfig={{
          ?headerLevel: <integer>
        }}
      />;
      ...
    )

createEditor is a function which the only argument is Model Definition object. It returns EditorComponent.

Props

Editor component is a React component with the following props:

Name	Default	Description
view	{   name: "search",   state: {} }	View Name and full/sliced View State
onTransition	-	Editor State transition handler
externalOperations	-	Function returning a set of External Operations handlers

view.name

Name of a custom/standard View. Custom Views are defined in Model Definition's ui.customViews. Standard View is one of:

View Name	Description
search	Search criteria and result
create	New entity instance creation
edit	Existing entity instance editing
show	The same as edit but read-only
error	Error page

view.state

Full/sliced State describing props.view.name. Its structure is determined by View it describes.

If View State is sliced, not given or {}, all not-mentioned properties have their default values.

View State must be serializable.

state for "search" view:

{
  ?filter: {
    <field name>: <serializable, filter value for the field>,
    ...
  },
  ?sort: <string, sort field name>,
  ?order: <"asc"|"desc", sort order>,
  ?max: <natural number, search result limit>,
  ?offset: <whole number, search result offset>,
  ?hideSearchForm: <boolean, search form initial visibility>
}

Name	Default
filter	{}
sort	Result field marked with sortByDefault (first sortable result field if no sortByDefault marker is set, or first result field if there are neither sortByDefault no sortable fields)
order	"asc"
max	30
offset	0
hideSearchForm	false

state for "create" view:

{
  ?predefinedFields: <object, an entity instance with predefined field values>
}

Name	Default
predefinedFields	{}

state for "edit" and "show" views:

{
  instance: <object, an entity instance with Logical Key fields only>,
  ?tab: <string, active tab name>
}

Name	Default
instance	-
tab	First tab name

state for "error" view:

{
  code: <natural number, error code>,
  ?payload: <any, structure is defined by error code>
}

or

[{
  code: <natural number, error code>,
  ?payload: <any, structure is defined by error code>
}, ...]

Name	Default
code	-
payload	-

onTransition

A transition handler to be called after Editor State changes to the one with "ready" status. Its only argument is Editor State object. Usually the function reflects Editor State to URL. It may also change Editor State by rendering EditorComponent with new props.

function ({
  name: <string, View name>,  // See EditorComponent props.view.name
  state: <object, Full View State>  // See EditorComponent props.view.state
}) {
  ...
  return;  // Return value is ignored.
}

externalOperations

A function returning an array of External Operations. Each has a handler which is called when a corresponding External Operation is triggered by CRUD Editor.

No arguments are passed to the function in Create View since it does not have persistent instance.

In case of unsaved changes, Confirmation Dialog is called after dedicated button press and before handler() call => each external operation must have side effects, or set disabled to true, or set show to false - othersise calling Confirmation Dialog is in vain.

function(<object, entity persistent instance> ) {
  ...
  return [{
    handler() {
      ...
      return; // Return value is ignored.
    },
    ui({
      name: <string, View name>,  // See EditorComponent props.view.name
      state: <object, Full View State>  // See EditorComponent props.view.state
    }) {
      return {
        title() {
          ...
          return <string, external operation translated title>,
        },

        ?show: <boolean, true by default>,
        ?disabled: <boolean, false by default>,

        /*
         * whether the operation has own dedicated button (false)
         * or it is to be placed in a dropdown of a previous button (true).
         * A previous button is either previous external operation with "dropdown" set to false
         * OR previous custom operation with "dropdown" set to false if there is no such external operation
         * OR (for Search View) "Edit" button if there is no such external/custom operation.
         */
        ?dropdown: <boolean, true by default>,

        /*
         * React Element or string name of an icon to be displayed inside a button, ex. "trash", "edit";
         * see full list at
         * http://getbootstrap.com/components/#glyphicons
         */
        ?icon: <string|element>
      };
    }
  }, ...]
}

uiConfig

An object with optional configurations for UI.

Name	Type	Default	Description
headerLevel	integer from 1 to 6	1	Header text size in all Views. Specially designed for sub-editors.