@bithero/react-entity-components

react-entity-components

React components to build UI's for entities

License

This project is licensed under AGPL-3.0. See the LICENSE file for more informations.

Usage

EntitySystemContext

First, your application (or atleast the components that should use the components provided by this library) needs to be wrapped inside an EntitySystemContext.Provider:

import { EntitySystemContext, IEntitySystemCtx } from '@bithero/react-entity-components';

const MyApp = () => {
    const sysCtx: IEntitySystemCtx = {
        fetchEntities(entityName: string): Promise<any[]> {
            // Async-callback to query all available entities of the type <entityName>
        },
        fetchEntity(entityName: string, id: string): Promise<any> {
            // Async-callback to query an entity of the type <entityName>, identitfied by <id>.
        },
        createEntity(entityName: string, entity: Object): Promise<any> {
            // Async-callback for the creation of an entity of the type <entityName> with the given content (<entity>).
            // Returns the entity once completed.
        },
        updateEntity(entityName: string, id: string, entity: Object): Promise<any> {
            // Async-callback to update an entity of the type <entityName> with the given content (<entity>),
            // identitfied by <id>. Returns the updated entity once completed.
        },
        tr(key: string, data?: Object): string {
            // Callback to translate the given <key> with additional data present in <data>.
        },

        // If this is set to true, the EntityDetail component prints out the current entity as json at the end of the component.
        debugPrint: true,
    }

    return (
        <EntitySystemContext.Provider value={sysCtx}>
            {/* ... */}
        </EntitySystemContext.Provider>
    );
}

EntityList

This component aids in displaying a list of entities:

import { EntityList } from '@bithero/react-entity-components';

const MyEntityList = () => {
    return (
        <div>
            <EntityList
                {/* The headers of the table; required */}
                header={[
                    {/* See desciption of IEntityListHeadConfig below */}
                    {label: 'ID', field: 'id'},
                    {label: 'Name', field: 'name'},
                ]}
                {/* Name of the entity which will be given to the entity callbacks in the EntitySystemContext; required */}
                entityName='myEntity'
                {/*
                    If set, the list shows an add button to create entities.
                    When the button is pressed, it navigates to the current location + the suffix '/new'.
                    Example:
                        List is displayed at route '/myEntities'. When the add button is pressed, the router
                        navigates to '/myEntities/new'.
                */}
                enableAdding
                {/* A render function to render a component when the list is in an loading state */}
                renderLoading={() => (<span>Is loading myEntity...</span>)}
            />
        </div>
    )
}

An heading entry has following structure:

type AsyncFieldGetter = (val: any) => Promise<string>;
type SyncFieldGetter = (val: any) => string;

interface IEntityListHeadConfig {
    // Label for the colum; displayed in the table's header.
    label: string

    // Provide an namespace for @bithero/simple-search-lib to map to the column.
    searchNamespace?: string

    // Used to lookup the value to display in the cells.
    //  - If an string: simply use as key into the object (i.e. `entity[field]`).
    //  - If an *FieldGetter: called with the current entity and expects it
    //    to return the value to display in the cell.
    field: string | AsyncFieldGetter | SyncFieldGetter
}

EntityDetail

This component is the "heart" of the library: here you build your form to display & modify entites. It can also be used as an creation dialog!

import { EntityDetail, FInput, FSelect, FSelectBox, FTextarea } from '@bithero/react-entity-components';

const MyEntityDetail = () => {
    const renderOption = (opt: any): JSX.Element => {
        return <option value={opt.id} key={opt.id}>{opt.name}</option>;
    }

    return (
        <EntityDetail
            title='New Entity'
            parentTitle='MyEntity'
            parentHref='/myEntity'
            {/* With this you can set an default entity; optional */}
            defaultEntity={{}}
            {/* Name of the entity which will be given to the entity callbacks in the EntitySystemContext; required */}
            entityName='myEntity'
            {/* If set, the entire form is readonly */}
            readonly
            {/* A render function to render a component when the list is in an loading state */}
            renderLoading={() => (<span>Is loading myEntity...</span>)}
        >
            {/*
                All components starting with F are components that provide some
                bootstrap components, wrapped so it works with the entity system.
                For more informations about them, see the documentation about field components (link below).
            */}
            <FInput attr="name" label="Name" defaultValue={'John'} required/>
            <FInput attr="pass" label="Password" type="password"/>
            <FTextarea attr="desc" label="Description" defaultValue={"Some fancy text"}/>
            <FCheck attr="enabled" label='Enabled' default={true}></FCheck>
            <FSelect attr="sel" label="Selection" entityName='refEntity' renderOption={renderOption}/>
            <FSelectBox attr="ref" label="Reference" entityName='refEntity' entityLabelAttr='name' required></FSelectBox>
        </EntityDetail>
    );
};

Link to the documentation about field-components: see here