Merge pull request #511 from devforth/feature/AdminForth/1155/backend-validation-function-le

Feature/admin forth/1155/backend validation function le

Author: SerVitasik

adminforth/documentation/docs/tutorial/03-Customization/13-standardPagesTuning.md

@@ -677,34 +677,6 @@ export default {
 > `minValue` and `maxValue` checks are enforced both on frontend and backend.
 
 
-### Validation
-
-In cases when column values must follow certain format, you can add `validation` to it.
-`validation` is an array of rules, each containing `regExp` that defines a format for a value and `message` that will be displayed in case when entered value does not pass the check.
-
-```typescript title="./resources/adminuser.ts"
-export default {
-      name: 'adminuser',
-      columns: [
-        ...
-        {
-          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',
-            },
-          ],
-        },
-      ],
-    },
-    ...
-  ],
-```
-
-> `validation` checks are enforced both on frontend and backend.
 
 ### Input prefix and suffix
 
@@ -967,6 +939,81 @@ When defined like this, adminforth will use value in `property_type` to figure o
 
 If `beforeDatasourceRequest` or `afterDatasourceResponse` hooks are set for polymorphic foreign resource, they will be called for each resource in `polymorphicResources` array.
 
+## Validation (create/edit view)
+In cases when column values must follow certain format, you can add `validation` to it.
+`validation` is an array of rules, each containing `regExp` or `validator function` that defines a format for a value and `message` that will be displayed in case when entered value does not pass the check.
+
+### Frontend validation
+We recommend to use this validation with regExp, because it validates fields in real time
+
+```typescript title="./resources/adminuser.ts"
+export default {
+      name: 'adminuser',
+      columns: [
+        ...
+        {
+          name: 'email',
+          required: true,
+          isUnique: true,
+          //diff-add
+          validation: [
+            //diff-add
+            {
+              //diff-add
+              regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+              //diff-add
+              message: 'Email is not valid, must be in format example@test.com',
+              //diff-add
+            },
+            //diff-add
+          ],
+        },
+      ],
+    },
+    ...
+  ],
+```
+
+### Backend validation
+There might be rare cases, when you want to have your own validation function. For this you can use `validator` callback:
+```typescript title="./resources/adminuser.ts"
+export default {
+      name: 'adminuser',
+      columns: [
+        ...
+        {
+          name: 'email',
+          required: true,
+          isUnique: true,
+          //diff-add
+          validation: [
+            //diff-add
+            {
+              //diff-add
+              async validator(value: any, record: any) {
+                //diff-add
+                if (value.endsWith("@example.com")) {
+                  //diff-add
+                  return { isValid: false, message: 'Your email can`t end with `@example.com`' };
+                  //diff-add
+                }
+                //diff-add
+                return { isValid: true }
+                //diff-add
+              }
+              //diff-add
+            }
+            //diff-add
+          ],
+        },
+      ],
+    },
+    ...
+  ],
+```
+
+>Avoid using a custom validator because every time you change a field (after a failed first save attempt), it will make an API call.
+
 ## Filtering
 
 ### Filter Options

adminforth/documentation/docs/tutorial/08-Plugins/05-1-upload-api.md

@@ -405,4 +405,30 @@ app.post(
 
 > ⚠️ Do not call `commitUrlToUpdateExistingRecord` or `commitUrlToNewRecord` from the same resource’s `beforeSave`/`afterSave` hooks, as it would create an infinite loop of updates/creates. These methods are intended to be called from your own API endpoints after the browser upload finishes.
 
+## Handling Internal vs. External Links (isInternalUrl)
+
+Have you ever encountered a situation where a user pastes a beautiful image directly from Google Images into the Markdown editor, but your system tries to save it as if it were a file from your own S3 bucket? Previously, this could lead to "broken" paths and corrupted data in your database.
+
+### You can easily use this method in your code:
+Imagine you are building a custom preview page or a specialized plugin, and you need to know: Is this file something we manage in our storage, or is it just a link to an external resource?
+
+```ts title="./index.ts"
+// Get the upload plugin instance
+const uploadPlugin = admin.getPluginById('my_s3_storage');
+
+const urlFromEditor = "https://my-bucket.s3.eu-central-1.amazonaws.com/apartments/flat.png";
+const externalUrl = "https://images.unsplash.com/photo-1503376780353-7e6692767b70";
+
+// Check the first link
+if (await uploadPlugin.isInternalUrl(urlFromEditor)) {
+  console.log("✅ This is our file. We can extract the path and manage it in S3.");
+  const path = uploadPlugin.getPathFromUrl(urlFromEditor); 
+  // Result: "capartmentsars/flat.png"
+}
+
+// Check the second link
+if (!(await uploadPlugin.isInternalUrl(externalUrl))) {
+  console.log("🌐 This is an external link.");
+}
+```
 

adminforth/modules/restApi.ts

@@ -610,9 +610,10 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
                     let validation = null;
                     if (col.validation) {
                       validation = await Promise.all(                  
-                        col.validation.map(async (val) => {
+                        col.validation.map(async (val, index) => {
                           return  {
                             ...val,
+                            validator: inCol.validation[index].validator ? true: false,
                             message: await tr(val.message, `resource.${resource.resourceId}`),
                           }
                         })
@@ -1588,7 +1589,46 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
       }
     });
+    server.endpoint({
+      method: 'POST',
+      path: '/validate_columns',
+      handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
+        const { resourceId, editableColumns, record } = body;
+        const resource = this.adminforth.config.resources.find((res) => res.resourceId == resourceId);
+        if (!resource) {
+          return { error: `Resource '${resourceId}' not found` };
+        }
+        const validationResults = {};
+        const customColumnValidatorsFunctions = [];
+        for (const col of editableColumns) {
+          const columnConfig = resource.columns.find((c) => c.name === col.name);
+          if (columnConfig && columnConfig.validation)  {
+            customColumnValidatorsFunctions.push(async ()=>{
+              for (const val of columnConfig.validation) {
+                if (val.validator) {
+                  const result = await val.validator(col.value, record, this.adminforth);
+                  if (typeof result === 'object' && result.isValid === false) {
+                    validationResults[col.name] = {
+                      isValid: result.isValid,
+                      message: result.message,
+                    }
+                    break;
+                  }
+                }
+              }
+            })
+          }
+        }
+        
+        if (customColumnValidatorsFunctions.length) {
+          await Promise.all(customColumnValidatorsFunctions.map((fn) => fn()));
+        }
 
+        return {
+          validationResults
+        }
+      }
+    });
     // setup endpoints for all plugins
     this.adminforth.activatedPlugins.forEach((plugin) => {
       plugin.setupEndpoints(server);