Generic Admin Panel

⚠️ Do not use React@19 while using this project!

For configuring your own admin panel, follow the next instructions.

How to install it?

The following command will download and install the specified package and its dependencies into your project's node_modules directory, making it available for use in your project.

• npm install admin_lsac

What do you need to import?

You can import these in App.js / App.ts or wherever your routes to the pages are located.

• import { pageToUrl } from 'admin_lsac'

• import { AdminPage } from 'admin_lsac'

If your project is TypeScript-based, you need to use the line from below as well. Import the component where you want to write your schemas. (See below for details about schemas)

• import { PageSchema } from 'admin_lsac'

How to add routes to the admin panel's pages?

You will need to create an array of schemas (if more than one schema) for your own admin panel.

{your_array.map((page, index) => (
  <Route
    key={index}
    path={`${your_url_to_admin_panel}/${pageToUrl(page)}`}
    element={
      <AdminPage
        pages={your_array}
        selectedPage={page} // 'page' param from above
        basePath={your_url_to_admin_panel} // use '', NOT '/' if at root
        apiURL={your_url_to_backend} // optional, for websockets
      />
    }
  />
))}
{your_array[0] ? ( // recommended default route when accessing admin panel
  <Route
    path={`${your_url_to_admin_panel}/*`}
    element={
      <AdminPage
        pages={your_array}
        selectedPage={your_array[0]}
        basePath={your_url_to_admin_panel} // use '', NOT '/' if at root
        apiURL={your_url_to_backend} // optional, for websockets
      />
    }
  />
) : null}

What is a schema?

export interface TableField {
  name: string;
  access: (obj: any) => any;
}

export interface SimpleField {
  name: string;
  label: string;
  type: 'string' | 'number' | 'file' | 'date' | 'datetime-local' | 'time';
  validationSchema?: any;
}

export interface Option {
  value: string | number | boolean;
  display: string;
}

export interface DropdownField {
  name: string;
  label: string;
  type: 'dropdown';
  validationSchema?: any;
  options?: Option[];
  getOptions?: () => Promise<Option[]>;
}

export interface ObjectField {
  name: string;
  label: string;
  type: 'object';
  fields: FormField[];
}

export interface ArrayField {
  name: string;
  label: string;
  type: 'array';
  element: Exclude<FormField, ArrayField>;
}

export type FormField = SimpleField | DropdownField | ObjectField | ArrayField;

export interface Action {
  name: string;
  fields?: FormField[];
  onSubmit: (obj1?: any, obj2?: any, obj3?: any) => Promise<any>;
}

export interface RowAction {
  name: string;
  fields?: FormField[];
  initialise?: (rowId: any) => Promise<any>;
  onSubmit: (obj1: any, obj2?: any, obj3?: any) => Promise<any>;
}

export interface PageSchema {
  name: string;
  actions: Action[];
  rowActions: RowAction[];
  getRequest: () => Promise<any[]>;
  tableFields: TableField[];
}

A page schema is based on these interfaces, and it describes how one table of your admin panel would need to be structured to accomplish what the user needs to do regarding an entity. (i.e. users, teams, companies, quizzes)

The most important interface is PageSchema, as it stands at the top of the relations between all these interfaces.

What do the fields of PageSchema refer to?

• name = name of the table
• actions = these are operations that can affect all entries in the table (like updating all or some of the entries in the table) or operations that envolve creating new entries (one by one)
• rowActions = these are operations that can affect just one entry/row (like updating or deleting an entry)
• getRequest = this is a field containg the function that will retrieve all the entries from one table in the database
• tableFields = these are the 'definitions' of the displayed table's columns

The operations for the rowActions and actions will generally (not mandatory) have a form to complete before executing it. There are 4 types of inputs for the form part:

• simpleField = simple data like numbers, strings, files and dates
• dropdownField = enable the user to choose an option from a predefined list
• arrayField = arrays of data
• objectField = an object containing more fields/inputs, or even other objects (some cool recursion)

Websockets Support

For real-time changes, this NPM module uses socket.io-client library to implement WebSockets. So, on the server-side, you will have to use socket.io library, and provide an apiURL as shown above.

In order for it to work, emit an event 'updateData' from the server for every route associated with an action/rowAction. You can also send a message that the client will receive (the message will be shown in the web console).

Other Specifications

Due to some corrupt dependencies, you will need a Node version >= 20.5.0 to use this NPM package (it may work in some cases, but we still recommend updating Node to a newer version).

For every entity you describe through a page schema, getRequest and onSubmit functions use routes created for the entity. getRequest function makes a GET request, while onSumbit function generally makes a POST, PATCH or DELETE request.

Learn More

For more details, especially about page schemas, contact the owner (LSAC Bucuresti). :)