adminforth 1.1.1 → 1.1.3

package/documentation/docs/Getting Started.md

@@ -1,374 +0,0 @@
-
-# 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

@@ -1,37 +0,0 @@
-
-# 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

@@ -1,171 +0,0 @@
-import {themes as prismThemes} from 'prism-react-renderer';
-import type {Config} from '@docusaurus/types';
-import type * as Preset from '@docusaurus/preset-classic';
-
-const config: Config = {
-  title: 'AdminForth',
-  tagline: 'OpenSource Dashboard on Tailwind UI extendable with Vue3 ',
-  favicon: 'img/favicon.png',
-
-  // Set the production url of your site here
-  url: 'https://adminforth.dev',
-  // Set the /<baseUrl>/ pathname under which your site is served
-  // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/',
-
-  // GitHub pages deployment config.
-  // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'devforth', // Usually your GitHub org/user name.
-  projectName: 'devforth.github.io', // Usually your repo name.
-
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
-
-  // Even if you don't use internationalization, you can use this field to set
-  // useful metadata like html lang. For example, if your site is Chinese, you
-  // may want to replace "en" with "zh-Hans".
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
-  },
-
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          sidebarPath: './sidebars.ts',
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          // editUrl:
-          //   'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-        },
-        // blog: {
-        //   showReadingTime: true,
-        //   // Please change this to your repo.
-        //   // Remove this to remove the "edit this page" links.
-        //   // editUrl:
-        //   //   'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-        // },
-        theme: {
-          customCss: './src/css/custom.css',
-        },
-      } satisfies Preset.Options,
-    ],
-  ],
-
-  plugins: [
-    [
-      "docusaurus-plugin-typedoc",
-      {
-        entryPoints: ["../types/AdminForthConfig.ts", "../types/FrontendAPI.ts"],
-        plugin: ["./typedoc-plugin.mjs"],
-        readme: "none",
-        indexFormat: "table",
-        disableSources: true,
-        sidebar: { pretty: true },
-        textContentMappings: {
-          "title.indexPage": "TypeDoc API",
-          "title.memberPage": "{name}",
-        },
-        parametersFormat: "table",
-        enumMembersFormat: "table",
-      },
-    ],
-  ],
-
-  themeConfig: {
-    // Replace with your project's social card
-    // image: 'img/docusaurus-social-card.jpg',
-    navbar: {
-      title: 'AdminForth',
-      logo: {
-        alt: 'AdminForth Logo',
-        src: 'img/logo.svg',
-      },
-      items: [
-        {
-          type: 'docSidebar',
-          sidebarId: 'tutorialSidebar',
-          position: 'left',
-          label: 'Tutorial',
-        },
-        {
-          type: 'docSidebar',
-          sidebarId: 'apiSidebar',
-          position: 'left',
-          label: 'API',
-        },
-        // {to: '/blog', label: 'Blog', position: 'left'},
-        {
-          href: 'https://github.com/devforth/adminforth',
-          label: 'GitHub',
-          position: 'right',
-        },
-      ],
-    },
-    footer: {
-      style: 'dark',
-      links: [
-        {
-          title: 'Docs',
-          items: [
-            {
-              label: 'Tutorial',
-              to: '/docs/Getting%20Started',
-            },
-            {
-              label: 'API',
-              to: '/docs/api',
-            },
-          ],
-        },
-        // {
-        //   title: 'Community',
-        //   items: [
-        //     {
-        //       label: 'Stack Overflow',
-        //       href: 'https://stackoverflow.com/questions/tagged/docusaurus',
-        //     },
-        //     {
-        //       label: 'Discord',
-        //       href: 'https://discordapp.com/invite/docusaurus',
-        //     },
-        //     {
-        //       label: 'Twitter',
-        //       href: 'https://twitter.com/docusaurus',
-        //     },
-        //   ],
-        // },
-        {
-          title: 'More',
-          items: [
-            // {
-            //   label: 'Blog',
-            //   to: '/blog',
-            // },
-            {
-              label: 'DevForth.io',
-              href: 'https://devforth.io',
-            },
-            {
-              label: 'We can develop dashboard for you',
-              href: 'https://devforth.io/contact',
-            },
-            {
-              label: 'GitHub',
-              href: 'https://github.com/devforth/adminforth',
-            },
-          ],
-        },
-      ],
-      copyright: `Copyright © ${new Date().getFullYear()} Devforth sp. z o.o.`,
-    },
-    prism: {
-      theme: prismThemes.okaidia,
-      darkTheme: prismThemes.dracula,
-    },
-  } satisfies Preset.ThemeConfig,
-};
-
-export default config;