Merge branch 'next' of github.com:devforth/adminforth into next

Author: SerVitasik

README.md

@@ -27,6 +27,7 @@ Why AdminForth:
 * Define express APIs and call them from your components and pages
 * Use various modern back-office-must-have plugins like audit log, files/image upload, TOTP 2FA, I18N, Copilot-style AI writing and image generation
 
+
 ## Project initialisation
 
 ```
@@ -56,27 +57,35 @@ npx adminforth create-app
 
 # For developers
 
-```
+The most convenient way to add new features or fixes is using `dev-demo`. It imports the source code of the repository and plugins so you can edit them and see changes on the fly.
+
+Fork repo, pull it and do next:
+
+
+```sh
 cd adminforth
 npm ci
 npm run build
 
-
 # this will install all official plugins and link adminforth package, if plugin installed it will git pull and npm ci
 npm run install-plugins
 
 # same for official adapters
 npm run install-adapters
+```
 
-# this is dev demo for development
+To run dev demo:
+```sh
 cd dev-demo
 cp .env.sample .env
 npm ci
 npm run migrate
 npm start
 ```
 
-Add some columns to a database. Open .prisma file, modify it, and run:
+## Adding columns to a database in dev-demo
+
+Open `.prisma` file, modify it, and run:
 
 ```
 npm run namemigration -- --name desctiption_of_changes

adminforth/commands/createApp/templates/index.ts.hbs

@@ -13,8 +13,6 @@ export const admin = new AdminForth({
     rememberMeDays: 30,
     loginBackgroundImage: 'https://images.unsplash.com/photo-1534239697798-120952b76f2b?q=80&w=3389&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
     loginBackgroundPosition: '1/2',
-    demoCredentials: "adminforth:adminforth",
-    loginPromptHTML: "Use email <b>adminforth</b> and password <b>adminforth</b> to login",
   },
   customization: {
     brandName: "{{appName}}",
@@ -24,6 +22,7 @@ export const admin = new AdminForth({
     datesFormat: 'DD MMM',
     timeFormat: 'HH:mm a',
     showBrandNameInSidebar: true,
+    emptyFieldPlaceholder: '-',
     styles: {
       colors: {
         light: {

adminforth/dataConnectors/mysql.ts

@@ -86,15 +86,15 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
       } else if (baseType.startsWith('json')) {
         field.type = AdminForthDataTypes.JSON;
         field._underlineType = 'json';
-      } else if (baseType.startsWith('date')) {
-        field.type = AdminForthDataTypes.DATE;
-        field._underlineType = 'date';
       } else if (baseType.startsWith('time')) {
         field.type = AdminForthDataTypes.TIME;
         field._underlineType = 'time';
       } else if (baseType.startsWith('datetime') || baseType.startsWith('timestamp')) {
         field.type = AdminForthDataTypes.DATETIME;
         field._underlineType = 'timestamp';
+      } else if (baseType.startsWith('date')) {
+        field.type = AdminForthDataTypes.DATE;
+        field._underlineType = 'date';
       } else if (baseType.startsWith('year')) {
         field.type = AdminForthDataTypes.INTEGER;
         field._underlineType = 'year';
@@ -232,7 +232,7 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
       console.log('🪲📜 MySQL Q:', q, 'values:', filterValues);
     }
     const [results] = await this.client.query(q, filterValues);
-    return +results[0].count;
+    return +results[0]["COUNT(*)"];
   }
 
   async getMinMaxForColumnsWithOriginalTypes({ resource, columns }) {

adminforth/documentation/blog/2025-02-19-compose-ec2-deployment-ci-registry/ga-tf-aws.jpg

@@ -1,5 +1,5 @@
 ivanb:
-  name: Ivan Borshcho
+  name: Ivan Borshchov
   title: Maintainer of AdminForth
   url: https://github.com/ivictbor
   image_url: https://avatars.githubusercontent.com/u/1838656?v=4

adminforth/documentation/blog/2025-02-19-compose-ec2-deployment-ci-registry/index.md

@@ -54,54 +54,59 @@ Also, it excludes itself to avoid infinte logging loop.
 Add this code in `auditLogs.ts`:
 
 ```ts title='./resources/auditLogs.ts'
-  export default {
-    dataSource: 'maindb', 
-    table: 'audit_logs',
-    columns: [
-      { name: 'id', primaryKey: true, required: false, fillOnCreate: ({initialRecord}: any) => uuid(),
-        showIn: {
-          list: false,
-          edit: false,
-          create: false,
-          filter: false,
-        } },
-      { name: 'created_at', required: false },
-      { name: 'resource_id', required: false },
-      { name: 'user_id', required: false, 
-          foreignResource: {
-          resourceId: 'adminuser',
-        } },
-      { name: 'action', required: false },
-      { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
-          list: false,
-          edit: false,
-          create: false,
-          filter: false,
-        } },
-      { name: 'record_id', required: false },
-    ],
-    options: {
-      allowedActions: {
+
+import AuditLogPlugin from "@adminforth/audit-log/index.js";
+import { AdminForthDataTypes } from "adminforth";
+import { randomUUID } from "crypto";
+
+export default {
+  dataSource: 'maindb', 
+  table: 'audit_logs',
+  columns: [
+    { name: 'id', primaryKey: true, required: false, fillOnCreate: ({initialRecord}: any) => randomUUID(),
+      showIn: {
+        list: false,
+        edit: false,
+        create: false,
+        filter: false,
+      } },
+    { name: 'created_at', required: false },
+    { name: 'resource_id', required: false },
+    { name: 'user_id', required: false, 
+        foreignResource: {
+        resourceId: 'adminuser',
+      } },
+    { name: 'action', required: false },
+    { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
+        list: false,
         edit: false,
-        delete: false,
-        create: false
+        create: false,
+        filter: false,
+      } },
+    { name: 'record_id', required: false },
+  ],
+  options: {
+    allowedActions: {
+      edit: false,
+      delete: false,
+      create: false
+    }
+  },
+  plugins: [
+    new AuditLogPlugin({
+      // if you want to exclude some resources from logging
+      //excludeResourceIds: ['adminuser'],
+      resourceColumns: {
+        resourceIdColumnName: 'resource_id',
+        resourceActionColumnName: 'action',
+        resourceDataColumnName: 'diff',
+        resourceUserIdColumnName: 'user_id',
+        resourceRecordIdColumnName: 'record_id',
+        resourceCreatedColumnName: 'created_at'
       }
-    },
-    plugins: [
-      new AuditLogPlugin({
-        // if you want to exclude some resources from logging
-        //excludeResourceIds: ['adminuser'],
-        resourceColumns: {
-          resourceIdColumnName: 'resource_id',
-          resourceActionColumnName: 'action',
-          resourceDataColumnName: 'diff',
-          resourceUserIdColumnName: 'user_id',
-          resourceRecordIdColumnName: 'record_id',
-          resourceCreatedColumnName: 'created_at'
-        }
-      }),
-    ],
-  }
+    }),
+  ],
+}
 ```
 
 Then you need to import `./resources/auditLogs`:

adminforth/documentation/blog/authors.yml

@@ -40,6 +40,7 @@ model translations {
     // we need both indexes on en_string+category and separately on category
     @@index([en_string, category])
     @@index([category])
+    @@index([completedLangs])
 }
 ```
 
@@ -454,7 +455,7 @@ import { admin } from '../index';
 
 You can use this module not only to translate admin area of your application but also to translate other parts like SEO-facing or user-facing services.
 This will allow you to reuse the same functionality and AI completion adapters for all your translations and manage them in one place. 
-For example in this app we will consider translating a Nuxt.js SEO-centric frontend which we want to translate with [vue-i18n](https://vue-i18n.intlify.dev/).
+For example in this app we will consider translating a Nuxt.js SEO-centric frontend which we want to translate with [nuxt i18n](https://i18n.nuxtjs.org/).
 
 To do it you need to use 2 exposed methods from the plugin: `feedCategoryTranslations` and `getCategoryTranslations`. 
 
@@ -478,7 +479,7 @@ First of all, at some step, e.g. CI pipeline you should get all translation stri
 
       admin.getPluginByClassName<I18nPlugin>('I18nPlugin').feedCategoryTranslations(
         messagesForFeed,
-        'nextApp'
+        'seoApp'
       )
 
       res.json({
@@ -489,60 +490,99 @@ First of all, at some step, e.g. CI pipeline you should get all translation stri
 
 ```
 
-For extracting 18n messages we use [vue-i18n-extract](https://github.com/Spittal/vue-i18n-extract) package. 
+For extracting i18n messages we use [vue-i18n-extract](https://github.com/Spittal/vue-i18n-extract) package. 
 You can add extract command to `package.json`:
 
 ```json
 {
   "scripts": {
-    "i18n:extract": "echo '{}' > i18n-empty.json && vue-i18n-extract report --vueFiles './src/**/*.?(js|vue)' --output ./i18n-messages.json --languageFiles 'i18n-empty.json' --add",
-    "i18n:feed-to-backoffice": "npm run i18n:extract && curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://adminforth:3000/feed-nuxt-strings"
+    "i18n:extract": "echo '{}' > i18n-empty.json && vue-i18n-extract report --vueFiles './?(pages|components)/**/*.?(js|vue)' --output ./i18n-messages.json --languageFiles 'i18n-empty.json' --add",
+    "i18n:feed-to-local-backoffice": "npm run i18n:extract && curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://localhost:3000/feed-nuxt-strings"
   }
 }
 ```
 
-Make sure to replace `adminforth:3000` with AdminForth API URL. We are assuming it is docker container name in internal docker network.
+> For plain non-nuxt apps `--vueFiles './?(pages|components)/**/*.?(js|vue)'` should be replaced with `--vueFiles './src/**/*.?(js|vue)'`
 
-So in the pipeline you should run `npm run i18n:feed-to-backoffice` to extract messages from your Nuxt.js app and feed them to AdminForth.
+Make sure to replace `localhost:3000` with AdminForth API URL.
 
-> 👆 The example method is just a stub, please make sure you not expose endpoint to public or add some simple authorization on it,
-> otherwise someone might flood you with dump translations requests.
-
-Then in your Nuxt.js app you should call this API and store the strings in the same.
+So locally you can run `npm run i18n:feed-to-local-backoffice` to extract messages from your Nuxt.js app and feed them to AdminForth.
 
 Next part. When we will need translations on the nuxt instance, we should use [vue-i18n's lazy loading feature](https://vue-i18n.intlify.dev/guide/advanced/lazy):
 
 ```typescript title="./your-nuxt-app-source-file.ts"
-import { callAdminForthApi } from '@/utils';
-
-export async function loadLocaleMessages(i18n, locale) {
-  // load locale messages with dynamic import
-  const messages = await callAdminForthApi({
-    path: `/api/translations/?lang=${locale}`,
+const { locale, setLocaleMessage, } = useI18n();
+const { data: messages } = await useFetch(
+  useRuntimeConfig().public.adminUrl + `api/translations/?lang=${locale.value}`,
+  {
     method: 'GET',
-  });
-
-  // set locale and locale message
-  i18n.global.setLocaleMessage(locale, messages.default)
-
-  return nextTick()
+  }
+);
+if (messages.value) {
+  setLocaleMessage(locale.value, messages.value);
+} else {
+  console.error('Translations or language data are missing.');
 }
 ```
 
-See [vue-i18n's lazy loading feature](https://vue-i18n.intlify.dev/guide/advanced/lazy) to understand where better to call `loadLocaleMessages` function.
-
 Here is how API for messages will look:
 
 ```ts title="./index.ts"
 app.get(`${ADMIN_BASE_URL}/api/translations/`, 
   async (req, res) => {
-    const lang = req.query.lang;
-    const messages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').getCategoryTranslations('nextApp', lang);
+    const lang = req.query.lang as string;
+    const messages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').getCategoryTranslations('seoApp', lang);
     res.json(messages);
   }
 );
 ```
 
+Also in `nuxt.config.ts` you can set `prefix_except_default` strategy and put it in `i18n` config as this:
+
+```
+  ...
+  i18n: {
+    locales: ['en', 'uk', 'ja', 'fr'],
+    defaultLocale: 'en',
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: false,
+  },
+  ...
+```
+
+
+#### Feeding messages during build time
+
+For Dockerized pipelines you can feed messages when building the image in Docker build time:
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+ADD package.json /app
+ADD package-lock.json /app
+RUN true | npm ci
+ADD . /app
+RUN --mount=type=cache,target=/app/node_modules/.cache true | npm run build
+
+//diff-add
+# Run i18n extraction and API call
+//diff-add
+RUN npm run i18n:extract && \
+//diff-add
+    curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://adminforth:3000/bo/api/feed-nuxt-strings
+
+CMD ["node", ".output/server/index.mjs"]
+EXPOSE 3000
+```
+
+This assumes that `http://adminforth:3000/` is the name of the Docker service running AdminForth. 
+
+This will work if you are building the image in the same Docker network as AdminForth. Otherwise you might need use absolute URL of the AdminForth instance.
+
+> 👆 The example method is just a stub, please make sure you not expose endpoint to public or add some simple authorization on it,
+> otherwise someone might flood you with dump translations requests.
+
+
 ### Get language names
 
 Also you can use handy method to get language names in native and English form with emoji flags:
@@ -575,3 +615,16 @@ Response will look like this:
             "emojiFlag": "🇦🇷"
         },
 ```
+
+### Disable translation for admin (external app only)
+
+If you want to use this plugin only for external app, and not backoffice, which is probably the case, you can disable translation for admin by setting `externalAppOnly` to `true`:
+
+```ts title="./resources/translations.ts"
+    new I18nPlugin({
+    //diff-add
+      externalAppOnly: true,
+      supportedLanguages: ['en', 'uk', 'ja', 'fr'],
+      ...
+    }),
+```