adminforth 1.0.83 → 1.0.86

package/documentation/docs/Getting Started.md

@@ -0,0 +1,374 @@
+
+# Installation
+
+## Prerequisites
+
+We recommend using Node v18 and higher
+
+## Installation
+
+```bash
+mkdir myadmin
+cd myadmin
+npm install adminforth
+```
+
+AdminForth does not provide own HTTP server, but can add own listeners over exisitng [Express](https://expressjs.com/) server (Fastify support is planned in future). This allows to create custom APIs for backoffice in a way you know.
+
+Let's install express:
+
+```bash
+npm install express@4.19.2
+```
+
+For demo purposes we will use SQLite data source. You can use postgress, Mongo or Clickhouse as well. 
+
+
+```bash
+npm install better-sqlite3@10.0.0
+```
+
+You can use adminforth in pure Node, but we recommend using TypeScript for better development experience.
+
+```bash
+npm install typescript@5.4.5 --save-dev
+npm install tsx@4.11.2 --save-dev
+```
+
+# Philosophy
+
+AdminForth connects to existing databases and provide a backoffice for managing data including CRUD operations, filtering, sorting, and more.
+
+Database should be already created by using any database management tool, ORM or migrator. AdminForth does not provide a way to create tables or columns in the database.
+
+Once you have a database, you pass a connection string to AdminForth and define resources(tables) and columns you would like to see in backoffice. For most DB AdminForth can guess column types and constraints (e.g. max-lenght) by connecting to DB. However you can redefine them in AdminForth configuration. Type and constraints definition are take precedence over DB metadata.
+
+Also in AdminForth you can define in "Vue" way how each field will be rendered, and create own pages e.g. Dashboards.
+
+In the demo we will create a simple database with 2 tables: `apartments` and `users`. We will just use plain SQL to create tables and insert some fake data.
+
+Users table will be used to store a credentials for login into backoffice itself.
+
+## Possible configuration options
+
+We will use schema with different column types for apartments to show many of AdminForth features.
+
+Check [AdminForthConfig](/docs/api/type-aliases/AdminForthConfig.md) for all possible AdminForth Configs.
+
+
+# Setting up a demo
+
+Open `package.json`, set `type` to `module` and add `start` script:
+
+```json
+{
+  ...
+  "type": "module",
+  "scripts": {
+    ...
+    "start": "ADMINFORTH_SECRET=CHANGE_ME_IN_PRODUCTION NODE_ENV=development tsx watch index.ts"
+  },
+}
+```
+
+
+Create `index.ts` file with following content:
+
+```typescript
+
+import betterSqlite3 from 'better-sqlite3';
+import express from 'express';
+import AdminForth from 'adminforth';
+
+const dbFile = 'test.sqlite';
+const db = betterSqlite3(dbFile)
+  
+const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='apartments';`).get();
+if (!tableExists) {
+  await db.prepare(`
+    CREATE TABLE apartments (
+        id VARCHAR(20) PRIMARY KEY NOT NULL,
+        title VARCHAR(255) NOT NULL,
+        square_meter REAL,
+        price DECIMAL(10, 2) NOT NULL,
+        number_of_rooms INT,
+        description TEXT,
+        property_type VARCHAR(255) DEFAULT 'apartment',
+        listed BOOLEAN DEFAULT FALSE,
+        created_at TIMESTAMP,
+        user_id VARCHAR(255)
+    );`).run();
+
+  await db.prepare(`
+    CREATE TABLE users (
+        id VARCHAR(255) PRIMARY KEY NOT NULL,
+        email VARCHAR(255) NOT NULL,
+        password_hash VARCHAR(255) NOT NULL,
+        created_at VARCHAR(255) NOT NULL,
+        role VARCHAR(255) NOT NULL
+    );`).run();
+
+  for (let i = 0; i < 50; i++) {
+    await db.prepare(`
+      INSERT INTO apartments (
+        id, title, square_meter, price, number_of_rooms, description, created_at, listed, property_type
+      ) VALUES ('${i}', 'Apartment ${i}', ${Math.random() * 100}, ${Math.random() * 10000}, ${Math
+        .floor(Math.random() * 5) }, 'Next gen appartments', ${Date.now() / 1000 - i * 60 * 60 * 24}, ${i % 2 == 0}, ${i % 2 == 0 ? "'house'" : "'apartment'"});
+      `).run();
+  }
+}
+
+const ADMIN_BASE_URL = '';
+
+const admin = new AdminForth({
+  baseUrl : ADMIN_BASE_URL,
+  rootUser: {
+    username: 'adminforth',  // use these as credentials to login
+    password: 'adminforth',
+  },
+  auth: {
+    resourceId: 'users',  // resource for getting user
+    usernameField: 'email',
+    passwordHashField: 'password_hash',
+  },
+  customization: {
+    brandName: 'My Admin',
+    datesFormat: 'D MMM YY HH:mm:ss',
+    emptyFieldPlaceholder: '-',
+  },
+
+  dataSources: [
+    {
+      id: 'maindb',
+      url: `sqlite://${dbFile}`
+    },
+  ],
+  resources: [
+    {
+      dataSource: 'maindb', 
+      table: 'apartments',
+      resourceId: 'apparts', // resourceId is defaulted to table name but you can change it e.g. 
+                             // in case of same table names from different data sources
+      label: 'Apartments',   // label is defaulted to table name but you can change it
+      recordLabel: (r) => `🏡 ${r.title}`,
+      columns: [
+        { 
+          name: 'id', 
+          label: 'Identifier',  // if you wish you can redefine label
+          showIn: ['filter', 'show'], // show in filter and in show page
+          primaryKey: true,
+          fillOnCreate: ({initialRecord, adminUser}) => Math.random().toString(36).substring(7),  // initialRecord is values user entered, adminUser object of user who creates record
+        },
+        { 
+          name: 'title',
+          required: true,
+          showIn: ['list', 'create', 'edit', 'filter', 'show'],  // the default is full set
+          maxLength: 255,  // you can set max length for string fields
+          minLength: 3,  // you can set min length for string fields
+        }, 
+        {
+          name: 'created_at',
+          type: AdminForth.Types.DATETIME ,
+          allowMinMaxQuery: true,
+          showIn: ['list', 'filter', 'show', 'edit'],
+          fillOnCreate: ({initialRecord, adminUser}) => (new Date()).toISOString(),
+        },
+        { 
+          name: 'price',
+          min: 10,
+          max: 10000.12,
+          allowMinMaxQuery: true,  // use better experience for filtering e.g. date range, set it only if you have index on this column or if there will be low number of rows
+          editingNote: 'Price is in USD',  // you can appear note on editing or creating page
+        },
+        { 
+          name: 'square_meter', 
+          label: 'Square', 
+          allowMinMaxQuery: true,
+          minValue: 1,  // you can set min /max value for number fields
+          maxValue: 1000,
+        },
+        { 
+          name: 'number_of_rooms',
+          allowMinMaxQuery: true,
+          enum: [
+            { value: 1, label: '1 room' },
+            { value: 2, label: '2 rooms' },
+            { value: 3, label: '3 rooms' },
+            { value: 4, label: '4 rooms' },
+            { value: 5, label: '5 rooms' },
+          ],
+          allowCustomValue: true,
+        },
+        { 
+          name: 'description',
+          sortable: false,
+        },
+        {
+          name: 'property_type',
+          enum: [{
+            value: 'house',
+            label: 'House'
+          }, {
+            value: 'apartment',
+            label: 'Apartment'
+          }, {
+            value: null,
+            label: 'Not defined'
+          }],
+        },
+        {
+          name: 'listed',
+          required: true,  // will be required on create/edit
+        },
+        {
+          name: 'user_id',
+          foreignResource: {
+            resourceId: 'users',
+          }
+        }
+      ],
+      options: {
+        listPageSize: 12,
+        allowedActions:{
+          edit: false,
+          delete: true,
+          show: true,
+          filter: true,
+        },
+      },
+    },
+    { 
+      dataSource: 'maindb', 
+      table: 'users',
+      resourceId: 'users',
+      label: 'Users',  
+      recordLabel: (r) => `👤 ${r.email}`,
+      columns: [
+        { 
+          name: 'id', 
+          primaryKey: true,
+          fillOnCreate: ({initialRecord, adminUser}) => Math.random().toString(36).substring(7),
+          showIn: ['list', 'filter', 'show'],
+        },
+        { 
+          name: 'email', 
+          required: true,
+          isUnique: true,
+          validation: [
+            {
+              regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+              message: 'Email is not valid, must be in format example@test.com'
+            },
+          ]
+        },
+        { 
+          name: 'created_at', 
+          type: AdminForth.Types.DATETIME,
+          showIn: ['list', 'filter', 'show'],
+          fillOnCreate: ({initialRecord, adminUser}) => (new Date()).toISOString(),
+        },
+        {
+          name: 'role',
+          enum: [
+            { value: 'superadmin', label: 'Super Admin' },
+            { value: 'user', label: 'User' },
+          ]
+        },
+        {
+          name: 'password',
+          virtual: true,  // field will not be persisted into db
+          required: { create: true }, // make required only on create page
+          editingNote: { edit: 'Leave empty to keep password unchanged' },
+          minLength: 8,
+          type: AdminForth.Types.STRING,
+          showIn: ['create', 'edit'], // to show field only on create and edit pages
+          masked: true, // to show stars in input field
+        }
+      ],
+      hooks: {
+        create: {
+          beforeSave: async ({ record, adminUser, resource }) => {
+            record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+            return { ok:true, error: false };
+          }
+        },
+        edit: {
+          beforeSave: async ({ record, adminUser, resource}) => {
+            if (record.password) {
+              record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+            }
+            return { ok: true, error: false }
+          },
+        },
+      }
+    },
+  ],
+  menu: [
+    {
+      label: 'Core',
+      icon: 'flowbite:brain-solid', // any icon from iconify supported in format <setname>:<icon>, e.g. from here https://icon-sets.iconify.design/flowbite/
+      open: true,
+      children: [
+        {
+          homepage: true,
+          label: 'Appartments',
+          icon: 'flowbite:home-solid',
+          resourceId: 'apparts',
+        },
+      ]
+    },
+    {
+      type: 'gap'
+    },
+    {
+      type: 'divider'
+    },
+    {
+      type: 'heading',
+      label: 'SYSTEM',
+    },
+    {
+      label: 'Users',
+      icon: 'flowbite:user-solid',
+      resourceId: 'users',
+    }
+  ],
+})
+
+
+const app = express()
+app.use(express.json());
+const port = 3500;
+
+(async () => {
+    // needed to compile SPA. Call it here or from a build script e.g. in Docker build time to reduce downtime
+    await admin.bundleNow({ hotReload: process.env.NODE_ENV === 'development'});
+    console.log('Bundling AdminForth done. For faster serving consider calling bundleNow() from a build script.');
+})();
+
+
+// serve after you added all api
+admin.express.serve(app, express)
+admin.discoverDatabases();
+
+
+app.listen(port, () => {
+  console.log(`Example app listening at http://localhost:${port}`)
+  console.log(`\n⚡ AdminForth is available at http://localhost:${port}${ADMIN_BASE_URL}\n`)
+});
+```
+
+
+Now you can run your app:
+
+```bash
+npm start
+```
+
+Open http://localhost:3500 in your browser and login with credentials `adminforth` / `adminforth`.
+
+![alt text](image.png)
+
+
+After Login you should see:
+

package/documentation/docs/Glossary.md

@@ -0,0 +1,37 @@
+
+# dataSource
+
+A DataSource is a connection to one database. Datasources has id for references from resources and URL which follows the standard URI format. For example `mysql://user:password@localhost:3306/database`.
+It used to:
+
+* Discover the columns in the database
+* Make queries to get the list and show records
+* Make queries to modify data
+
+There might be several datasources in the system for vairous databases e.g. One 2 Mongo DBs and 1 Postgres DB. 
+
+# resource
+
+A Resource is a representation of a table or collection in AdminForth. One resource is one table in the database.
+It has a `name` which should match name in database, a datasource id, and a list of columns.
+Also it has various customization options.
+
+# column
+
+A Column is a representation of a column in a table. It has a `name` which should be equal to name in database and various configuration options.
+
+# record
+
+A record is a row in a relational database table. Or Document in document database table.
+
+# adminUser
+
+Object which represents a user who logged in to the AdminForth
+
+# hook
+
+Hook is a optional async function which allows to inject in backend logic before exuting the datasource query or after it
+
+# component
+
+Component is a Vue component which is used to add or modify UI elements in AdminForth.

package/documentation/docusaurus.config.ts

@@ -8,7 +8,7 @@ const config: Config = {
   favicon: 'img/favicon.png',
 
   // Set the production url of your site here
-  url: 'https://adminforth.devforth.io',
+  url: 'https://adminforth.dev',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
@@ -58,7 +58,7 @@ const config: Config = {
     [
       "docusaurus-plugin-typedoc",
       {
-        entryPoints: ["../types/AdminForthConfig.ts"],
+        entryPoints: ["../types/AdminForthConfig.ts", "../types/FrontendAPI.ts"],
         plugin: ["./typedoc-plugin.mjs"],
         readme: "none",
         indexFormat: "table",
@@ -76,7 +76,7 @@ const config: Config = {
 
   themeConfig: {
     // Replace with your project's social card
-    image: 'img/docusaurus-social-card.jpg',
+    // image: 'img/docusaurus-social-card.jpg',
     navbar: {
       title: 'AdminForth',
       logo: {
@@ -162,7 +162,7 @@ const config: Config = {
       copyright: `Copyright © ${new Date().getFullYear()} Devforth sp. z o.o.`,
     },
     prism: {
-      theme: prismThemes.vsLight,
+      theme: prismThemes.okaidia,
       darkTheme: prismThemes.dracula,
     },
   } satisfies Preset.ThemeConfig,

package/documentation/static/CNAME

@@ -0,0 +1 @@
+adminforth.dev

package/index.ts

@@ -9,18 +9,15 @@ import ExpressServer from './servers/express.js';
 import {v1 as uuid} from 'uuid';
 import fs from 'fs';
 import { ADMINFORTH_VERSION } from './modules/utils.js';
-import { AdminForthConfig, AdminForthClass, AdminForthFilterOperators, AdminForthDataTypes } from './types/AdminForthConfig.js';
+import { AdminForthConfig, AdminForthClass, AdminForthFilterOperators, AdminForthDataTypes, AdminForthResourcePages } from './types/AdminForthConfig.js';
 import { getFunctionList } from './modules/utils.js';
 import path from 'path';
 
-const AVAILABLE_SHOW_IN = ['list', 'edit', 'create', 'filter', 'show'];
-const DEFAULT_ALLOWED_ACTIONS = {create: true, edit: true, show: true, delete: true};
 
+//get array from enum AdminForthResourcePages
+
+const DEFAULT_ALLOWED_ACTIONS = {create: true, edit: true, show: true, delete: true};
 
-type ValidationObject = {
-  regex: string,
-  message: string,
-}
 
 class AdminForth implements AdminForthClass {
   static Types = AdminForthDataTypes;
@@ -41,7 +38,7 @@ class AdminForth implements AdminForthClass {
   codeInjector: CodeInjector;
   connectors: any;
   connectorClasses: any;
-  runningHotReload?: boolean;
+  runningHotReload: boolean;
 
   statuses: {
     dbDiscover?: 'running' | 'done',
@@ -151,12 +148,12 @@ class AdminForth implements AdminForthClass {
         if (!res.table) {
           errors.push(`Resource "${res.dataSource}" is missing table`);
         }
-        // if itemLabel is not callable, throw error
-        if (res.itemLabel && typeof res.itemLabel !== 'function') {
-          errors.push(`Resource "${res.dataSource}" itemLabel is not a function`);
+        // if recordLabel is not callable, throw error
+        if (res.recordLabel && typeof res.recordLabel !== 'function') {
+          errors.push(`Resource "${res.dataSource}" recordLabel is not a function`);
         }
-        if (!res.itemLabel) {
-          res.itemLabel = (item) => {
+        if (!res.recordLabel) {
+          res.recordLabel = (item) => {
             const pkVal = item[res.columns.find((col) => col.primaryKey).name];
             return `${res.label} ${pkVal}`;
           }
@@ -203,13 +200,11 @@ class AdminForth implements AdminForthClass {
             }
           }
 
-
-
-          const wrongShowIn = col.showIn && col.showIn.find((c) => !AVAILABLE_SHOW_IN.includes(c));
+          const wrongShowIn = col.showIn && col.showIn.find((c) => AdminForthResourcePages[c] === undefined);
           if (wrongShowIn) {
-            errors.push(`Resource "${res.resourceId}" column "${col.name}" has invalid showIn value "${wrongShowIn}", allowed values are ${AVAILABLE_SHOW_IN.join(', ')}`);
+            errors.push(`Resource "${res.resourceId}" column "${col.name}" has invalid showIn value "${wrongShowIn}", allowed values are ${Object.keys(AdminForthResourcePages).join(', ')}`);
           }
-          col.showIn = col.showIn?.map(c => c.toLowerCase()) || AVAILABLE_SHOW_IN;
+          col.showIn = col.showIn || Object.values(AdminForthResourcePages);
         })
 
         if (!res.options) {
@@ -243,21 +238,41 @@ class AdminForth implements AdminForthClass {
             return Object.assign(action, {id: uuid()});
           });
           bulkActions = newBulkActions;
-        }
 
-          //add default allowedActions to resources
-          if(res.options.allowedActions){
-            //check if allowedActions is an object
-            if(typeof res.options.allowedActions !== 'object'){
-              errors.push(`Resource "${res.resourceId}" allowedActions must be an object`);
-            }
-            const userAllowedActions = res.options.allowedActions 
-            res.options.allowedActions = Object.assign({}, DEFAULT_ALLOWED_ACTIONS, userAllowedActions);         
-          } else {
-            res.options.allowedActions = DEFAULT_ALLOWED_ACTIONS;
+          // if pageInjection is a string, make array with one element. Also check file exists
+          const possibleInjections = ['beforeBreadcrumbs', 'afterBreadcrumbs', 'bottom'];
+          if(res.options.pageInjections) {
+            Object.entries(res.options.pageInjections).map(([key, value]) => {
+              Object.entries(value).map(([injection, target]) => {
+                if (possibleInjections.includes(injection)) {
+                  if (typeof target === 'string') {
+                    res.options.pageInjections[key][injection] = [target];
+                  }
+                  res.options.pageInjections[key][injection].forEach((target) => {
+                    errors.push(...this.checkCustomFileExists(target));
+                  });
+                } else {
+                  errors.push(`Resource "${res.resourceId}" has invalid pageInjection key "${injection}", Supported keys are ${possibleInjections.join(', ')}`);
+                }
+              });
+                  
+            })
           }
-        })
 
+        }
+
+        //add default allowedActions to resources
+        if(res.options.allowedActions){
+          //check if allowedActions is an object
+          if(typeof res.options.allowedActions !== 'object'){
+            errors.push(`Resource "${res.resourceId}" allowedActions must be an object`);
+          }
+          const userAllowedActions = res.options.allowedActions 
+          res.options.allowedActions = Object.assign({}, DEFAULT_ALLOWED_ACTIONS, userAllowedActions);         
+        } else {
+          res.options.allowedActions = DEFAULT_ALLOWED_ACTIONS;
+        }
+      })
     
 
 
@@ -335,8 +350,8 @@ class AdminForth implements AdminForthClass {
     // check is all custom components files exists
     for (const resource of this.config.resources) {
       for (const column of resource.columns) {
-          if (column.component) {
-            for (const [key, value] of Object.entries(column.component)) {
+          if (column.components) {
+            for (const [key, value] of Object.entries(column.components)) {
                 if (this.codeInjector.allComponentNames[value]) {
                   // not obvious, but if we are in this if, it means that this is plugin component
                   // and there is no sense to check if it exists in users folder
@@ -675,7 +690,7 @@ class AdminForth implements AdminForthClass {
             });
             const targetDataMap = targetData.data.reduce((acc, item) => {
               acc[item[targetResourcePkField]] = {
-                label: targetResource.itemLabel(item),
+                label: targetResource.recordLabel(item),
                 pk: item[targetResourcePkField],
               }
               return acc;
@@ -707,7 +722,7 @@ class AdminForth implements AdminForthClass {
         });
 
         data.data.forEach((item) => {
-          item._label = resource.itemLabel(item);
+          item._label = resource.recordLabel(item);
         });
 
         return {
@@ -761,7 +776,7 @@ class AdminForth implements AdminForthClass {
         });
         const items = dbDataItems.data.map((item) => {
           const pk = item[targetResource.columns.find((col) => col.primaryKey).name];
-          const labler = targetResource.itemLabel;
+          const labler = targetResource.recordLabel;
           return { 
             value: pk,
             label: labler(item),

package/modules/codeInjector.ts

@@ -10,7 +10,7 @@ import AdminForth from '../index.js';
 import { ADMIN_FORTH_ABSOLUTE_PATH } from './utils.js';
 import { getComponentNameFromPath } from './utils.js';
 import { styles } from '../styles.js'
-
+import { CodeInjectorType } from '../types/AdminForthConfig.js';
 
 
 
@@ -30,7 +30,7 @@ function hashify(obj) {
     ('sha256').update(JSON.stringify(obj)).digest('hex');
 }
 
-class CodeInjector {
+class CodeInjector implements CodeInjectorType {
 
   allWatchers = [];
   adminforth: AdminForth;
@@ -260,19 +260,28 @@ class CodeInjector {
     }).join('\n');
 
     // for each custom component generate import statement
-    const customComponentsDir = this.adminforth.config.customization?.customComponentsDir;
-
     const customResourceComponents = [];
     this.adminforth.config.resources.forEach((resource) => {
       resource.columns.forEach((field) => {
-        if (field.component) {
-          Object.values(field.component).forEach((filePath) => {
+        if (field.components) {
+          Object.values(field.components).forEach((filePath) => {
             if (!customResourceComponents.includes(filePath)) {
               customResourceComponents.push(filePath);
             }
           });
         }
       });
+      (Object.values(resource.options?.pageInjections || {})).forEach((injection) => {
+        Object.values(injection).forEach((filePathes: string[]) => {
+          filePathes.forEach((filePath) => {
+            if (!customResourceComponents.includes(filePath)) {
+              customResourceComponents.push(filePath);
+            }
+          });
+        });
+      });
+
+
     });
 
     customResourceComponents.forEach((filePath) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adminforth",
-  "version": "1.0.83",
+  "version": "1.0.86",
   "description": "OpenSource Vue3 powered forth-generation admin panel",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugins/ForeignInlineListPlugin/index.ts

@@ -1,4 +1,4 @@
-import { AdminForthResource } from "../../types/AdminForthConfig.js";
+import { AdminForthResource, AdminForthResourcePages } from "../../types/AdminForthConfig.js";
 import AdminForthPlugin from "../base.js";
 import AdminForth from "../../index.js";
 
@@ -30,8 +30,8 @@ export default class ForeignInlineListPlugin extends AdminForthPlugin {
       name: `foreignInlineList_${this.foreignResource.resourceId}`,
       label: 'Foreign Inline List',
       virtual: true,
-      showIn: ['show'],
-      component: {
+      showIn: [AdminForthResourcePages.show],
+      components: {
         showRow: this.componentPath('InlineList.vue'),
       },
     });