UI CRUD FRAMEWORK

Version

1.0.6

A framework to easily implement RESTful CRUD actions on any entity passed to it.

Installation

No installations at the moment

Usage Example

       <PaginateComponent
   		rowsPerPage={5}
   		tableKey='Name'
   		uniqueRoleIdentifier='id'
   		fields={columnsToDisplay}
   		fieldsToCreate={fieldsToCreate}
   		fieldsToUpdate={fieldsToCreate}
   		autoFields={autoFields}
   		tableHeading='Example Table'
   		baseEntityAPI='fundinggrouptypes/v1'
   	/>

The Admin Paginate Framework can be used in several ways:

• In-built table with in-built forms to create and update as modals
• In-built table with custom forms to create and update as modals
• In-built table with custom forms to create and update on separate pages

Props

| Name | Type | Description | Optional? | | ------ | --- | ------ | ------ | | rowsPerPage | Integer | Number of rows to be used as default in pagination | Yes | | tableKey | String | Unique field to be displayed on the table (If available) | No | | uniqueRoleIdentifier | String | Unique key available in each data object such as 'id' | No | | fields | Array of Objects | Array of details of each field to be displayed on the table. Maximum of 5 columns | No | | fieldsToCreate | Array of Objects | Array of details of each field that should be created with the POST request | No | | fieldsToUpdate | Array of Objects | Array of details of each field that should be updated with the PUT request | No | | fieldRules | Array of Objects | Array of rules for each field that should be applied on the static form | Yes, based on case | | autoFields | Array | Array of fields that are autogenerated by the API during a POST and returned by the GET API | No | | tableHeading | String | The Heading to be given to the table | No | | baseEntityAPI | String | The Base API to be used for the entity | No | | FormComponent | Jsx | Custom form designed by user to create the entity on a modal | Yes, based on case | | NewPageFormComponent | Jsx | Custom form designed by user to create the entity on another page | Yes, based on case | | UpdateFormComponent | Jsx | Custom form designed by user to update the entity on another page | Yes, based on case | | CustomViewComponent | Jsx | Custom view one display designed by user to display for view one | Yes, based on case | | templateCase | String | String to describe the template case | Yes, based on case | | fieldRules | Array of Objects | Array of Objects that carry the id, label and rules of the fields in the update with a static form | Yes, based on case |

Sample Code

Rows Per Page (rowsPerPage)

Number of rows to display by default on the table with paginated data. Pass this in as an integer. Number of rows to be viewed at once can be changed by the user in the dropdown below the table.

rowsPerPage={5}

Table Key (tableKey)

One of the fields in each row which is unique and will also be displayed on the table is needed. This is needed in the selection functionality. Pass this in as a string.

tableKey='name'

Unique Role Identifier (uniqueRoleIdentifier)

This prop is a field in each role that is unique in the data coming from the database. It could be 'id'. Pass this in as a string.

uniqueRoleIdentifier='id'

Fields (fields)

This is an array of objects that contain the details and specifications of each column to be displayed. Each object contains the id, disablePadding, label and type properties.

• id - The name of the field as it comes from API.
• disablePadding - Either true or false. Says whether there should be left padding placed on the column header text.
• label - Text representation of the field column header. As you want it to be seen on the table
• type - Type of value to come into the column: - 'string' for strings. - 'date' for date fields - 'numeric' for numbers - 'object' for fields that contain an object of data. When this condition applies for any field, a `fieldToDisplay should be passed as well. This tells the template what field to render when it comes into the object.

    const fields = [
      { 
        id: "name",
        disablePadding: true,
        label: "Name",
        type: "string"
      },
      { 
        id: "createdAt",
        disablePadding: false,
        label: "Created At",
        type: "date"
      }
    ];

Fields To Create (fieldsToCreate)

This is an array of objects that contain the details and specifications of each field to be displayed on the dynamic form. Each object contains the id, label, type, multiline and rules properties.

• id - The name of the field as it should go to the API.
• label - Text representation of the field. As you want it to be seen on the form
• type - Type of input field to be created on the form - 'select' for select fields - 'textfield' for text inputs - 'radio' for radio fields - 'number' for fields to take in whole number positive integers - 'jsonarea' for fields to take in json inputs
• multiline - true or excluded. Goes with type as textfield. Include if you want the textfield to take multi lines.
• rules - An object containing the rules to be applied to that field. - required - true or excluded if not required - string - true or excluded if not string - numeric - true or excluded if not numeric - match - If the field should match a predefined format, include as an object the regex to check the match and the message to be displayed as an error if wrongly filled. Example:

   match: {
      match: /\d+(d|w|m)/,
      message: "Must match this format: [1d, 2d, 1w, 2w, 1m, 2m]"
    }
  }

Fields to create sample:

const fieldsToCreate = [
      {
        id: "name",
        label: "Name",
        type: "textfield",
        rules: {
          required: true,
          string: true
        }
      },
      {
        id: "description",
        label: "Description",
        type: "textfield",
        multiline: true,
        rules: {
          required: true,
          string: true
        }
      }]

Fields To Update (fieldsToUpdate)

This is an array of objects that contain the details and specifications of each field to be displayed on the dynamic form to update an entity. It's specifications are similar to that of the fields to create.

Auto Fields (autoFields)

This is an array of the names of the fields that are autogenerated from the API. Include them as strings in the autoFields array. These fields need to be omitted when rendering the form for the dynamic update functionality.

autoFields={['id', 'createdAt', 'updatedAt']}

Table Heading (tableHeading)

This is the heading that the table should take. Pass this in as a string.

tableHeading='Example Table Heading'

Base Entity API (baseEntityAPI)

Having defined the domain in your .env file, the base Entity API is a string that contains the url for the particular entity. Since the template is for RESTful implementations, it is expected that this url should match in all the verbs (POST, GET, PUT, DELETE). The id appended to the url for GET ONE, PUT and DELETE is done dynamically, so no need to worry about it. Say for an entity of dogs hosted on http://localhost:3000/, complete API could be http://localhost:3000/api/v1/dogs/. If the root url is http://localhost:3000/api/, the base entity api would be v1/dogs.

baseEntityAPI='v1/dogs'

Form Component (FormComponent)

When you want to use the framework while passing in your predefined forms, it is quite easy: Just import the file, say, CustomComponent from where the functional component is defined and pass it in as:

FormComponent={CustomComponent}

If you are passing in the Form Component, then the templateCase value should be static-form. The Form Component should take the values as shown in the gist below:

Custom Component

The following values should be destructured from props in the Form Component and used as below:

• FieldErrors - This is an object that will contain the errors generated in the form when being filled. Each key in the object represents a field in the fields defined in the fieldsToCreate prop. Every key has its value as an array of errors. To display the errors for each field, map through the values of the particular field. For example, to display the errors for the name field, you can target the errors as shown below: <p>{fieldErrors.name && fieldErrors.name.map((error) => <li key={error}>{error}</li>)}</p>

• changeHandler - The changeHandler is the method triggered when values change in each field. Pass it to the onChange event of the field. It takes as an argument, the name of the field, example:

  onChange={changeHandler('name')}

• data - Data is the object that will contain the values of each field. Each key in the object changes as the user types into the field that has the key as its name. Assign each field the corresponding key in the object (Example as shown below):

  value={data.name && data.name}

• onSubmit - onSubmit is the method that handles the submission of the form. Pass it to the onClick event on the button for submission or on any other element that is to handle the submission. Usage is shown below:

  onClick={onSubmit}

• validator - validator is the method that handles the validation of each field based on the rules defined for that field. Pass it to the onBlur event on each field. It takes the name of the field, the label, the rules as an object and the value (as defined in the value props above) of the field respectively. Example below (with a field to take name):

  onBlur={() => validator('name', 'Name', {
      required: true,
      string: true,
  }, data.name)}

• confirmValidation - confirmValidation is the method that handles the final validations of all the fields when the user is about to submit. Pass it to the onMouseOver event on the button for submission (or any other means of submission). It does not take any arguments. Example usage:

  onMouseOver={confirmValidation}

Update Form Component (UpdateFormComponent)

When you define a custom form to create an entity, you would also have to define a custom form to update the entity. Import the custom component as you would the FormComponent and assign it to the UpdateFormComponent. The Update Form Component should take the values as shown in the gist below: Update Form Component

The following values should be destructured from props in the Form Component and used as below:

• fieldErrors - Usage is similar to that in the FormComponent.
• changeHandler - Usage is similar to that in the FormComponent.
• data - Usage is similar to that in the FormComponent.
• onSubmit - Usage is similar to that in the FormComponent.
• validator - Usage is similar to that in the FormComponent.
• confirmValidation - Usage is similar to that in the FormComponent.

Custom View Component (CustomViewComponent)

Pass this as props to the template when you want to display a custom view one component to the user. This also passes in with all the necesdsary logic to control it. Values that are gotten from the props include:

• dataToDisplay - This contains the data to be displayed on the modal. It comes in as an object.
• closeModal - This is the method passed to the button to close the modal.
• extraData - This contains any extra data that has been fetched by the template. It contains all the data fetched as specified by extraEntitiesToFetch.

New Page Form Component (NewPageFormComponent)

Pass this as props to the template when you want the create page to appear on a separate page. This component should take the values as shown in the gist below: New Page Form Component

The following values should be destructured from props in the New Page Form Component and used as below:

• fields - Fields contains the array of objects of all the fields to be created. It is used in the validator method to access the rules of each field. Use as so:

  onBlur={() =>
      validator(
        "name",
        "Name",
        fields
          .filter(field => field.id === "name")
          .map(field => field.rules)[0],
        data.name
      )
    }

• validator - Usage is similar to that in the FormComponent. Except that for the rules, pass in a simple method as shown above that filters through the fields array and targets the object where the name of the field matches the object id.
• data - Usage is similar to that in the FormComponent.
• fieldErrors - Usage is similar to that in the FormComponent.
• isCreatedDataLoading - This is the boolean that controls the showing of the page loader when submitting data. If you have a page loader in the component, simply call the loader conditionally with this boolean value as in:

  isCreatedDataLoading && <Spinner />

• onSubmit - Usage is similar to the onSubmit method in the FormComponent.
• confirmValidation - Usage is similar to that in the FormComponent.

Template Case (templateCase)

This value holds the case that the template should be applied in. It is currently possible to take 3 states. Undefined, static-form, or new-page-form.

• Undefined - When not defined, the template takes its default form. It generates the fields and consequently the form for the fields passed to it. When undefined, it does not expect either of the FormComponent, UpdateFormComponent or the NewPageFormComponent.

• static-form - When given this value, it expects a custom forms assigned to the FormComponent and the UpdateFormComponent prop values. When in this state, takes the form passed to it and presents them as modals to be filled.

• new-page-form - When given this value, it also expects custom forms for update and create functionalities. It expects values in the NewPageFormComponent prop value. When in this state, it takes the form passed to it and presents it on a new page. Usage:

  templateCase='static-form'

Field Rules (fieldRules)

When passing in a custom form and with templateCase as 'static-form', it is necessary to pass in the rules for each field to handle field validations when updating an entity. The fieldRules is an array of objects that contain the rules and specific details of every field to be updated. Each object contains the id, label and rules of the particular field.

• id - The name of the field as it is from the API.
• label - Text representation of the field.As you want it to show in the validation error message.
• rules - An object containing the rules to be applied to that field. - required - true or excluded if not required - string - true or excluded if not string - numeric - true or excluded if not numeric - match - If the field should match a predefined format, include as an object the regex to check the match and the message to be displayed as an error if wrongly filled. Example:

   match: {
      match: /\d+(d|w|m)/,
      message: "Must match this format: [1d, 2d, 1w, 2w, 1m, 2m]"
    }
  }