feat: implement conditional column display logic with showIf property

Author: dominicDeCoco-bravo

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

@@ -143,6 +143,167 @@ export default {
 
 >⚠️ Please note that sticky columns can only be applied to one column per resource.
 
+### Conditional display
+You can conditionally display columns in forms and views based on the values of other fields in the current record using the `showIf` property. This enables dynamic layouts that automatically adapt to user input, creating more intuitive and context-aware interfaces.
+
+```typescript title="./resources/apartments.ts"
+export default {
+  resourceId: 'aparts',
+  columns: [
+    {
+      name: 'apartment_type',
+      enum: [
+        { value: 'studio', label: 'Studio' },
+        { value: 'apartment', label: 'Apartment' },
+        { value: 'penthouse', label: 'Penthouse' }
+      ]
+    },
+    {
+      name: 'number_of_rooms',
+      type: AdminForthDataTypes.INTEGER,
+//diff-add
+      showIf: { apartment_type: { $not: 'studio' } }
+    },
+    {
+      name: 'has_balcony',
+      type: AdminForthDataTypes.BOOLEAN,
+//diff-add
+      showIf: { apartment_type: 'penthouse' }
+    }
+  ]
+}
+```
+
+#### Logical Operators
+
+Use `$and` and `$or` operators to create complex conditional logic:
+
+```typescript title="./resources/apartments.ts"
+export default {
+  columns: [
+    {
+      name: 'premium_features',
+      type: AdminForthDataTypes.JSON,
+//diff-add
+      showIf: {
+//diff-add
+        $and: [
+//diff-add
+          { price: { $gte: 500000 } },
+//diff-add
+          { apartment_type: { $in: ['penthouse', 'apartment'] } }
+//diff-add
+        ]
+//diff-add
+      }
+    },
+    {
+      name: 'discount_reason',
+      type: AdminForthDataTypes.STRING,
+//diff-add
+      showIf: {
+//diff-add
+        $or: [
+//diff-add
+          { price: { $lt: 100000 } },
+//diff-add
+          { listed: false }
+//diff-add
+        ]
+//diff-add
+      }
+    }
+  ]
+}
+```
+
+#### Comparison Operators
+
+Use various comparison operators for numeric and string fields:
+
+```typescript title="./resources/apartments.ts"
+export default {
+  columns: [
+    {
+      name: 'luxury_amenities',
+//diff-add
+      showIf: { square_meter: { $gt: 100 } }
+    },
+    {
+      name: 'budget_options',
+//diff-add
+      showIf: { price: { $lte: 200000 } }
+    },
+    {
+      name: 'special_offers',
+//diff-add
+      showIf: { country: { $nin: ['US', 'GB'] } }
+    }
+  ]
+}
+```
+
+#### Array Operators
+
+For fields that contain arrays, use array-specific operators:
+
+```typescript title="./resources/apartments.ts"
+export default {
+  columns: [
+    {
+      name: 'pet_policy',
+//diff-add
+      showIf: { amenities: { $includes: 'pet_friendly' } }
+    },
+    {
+      name: 'security_deposit',
+//diff-add
+      showIf: { features: { $nincludes: 'furnished' } }
+    }
+  ]
+}
+```
+
+#### Available Operators
+
+The following operators are available for use in `showIf` conditions:
+
+**Equality Operators:**
+- `$eq` - Equal to (default if no operator specified)
+  - `{ price: { $eq: 100000 } }` or `{ price: 100000 }`
+- `$not` - Not equal to
+  - `{ apartment_type: { $not: 'studio' } }`
+
+**Comparison Operators:**
+- `$gt` - Greater than
+  - `{ square_meter: { $gt: 100 } }`
+- `$gte` - Greater than or equal to
+  - `{ price: { $gte: 500000 } }`
+- `$lt` - Less than
+  - `{ price: { $lt: 100000 } }`
+- `$lte` - Less than or equal to
+  - `{ price: { $lte: 200000 } }`
+
+**Array Operators:**
+- `$in` - Value is in array
+  - `{ apartment_type: { $in: ['penthouse', 'apartment'] } }`
+- `$nin` - Value is not in array
+  - `{ country: { $nin: ['US', 'GB'] } }`
+- `$includes` - Array includes value
+  - `{ amenities: { $includes: 'pet_friendly' } }`
+- `$nincludes` - Array does not include value
+  - `{ features: { $nincludes: 'furnished' } }`
+
+**Logical Operators:**
+- `$and` - Logical AND operation
+  - `{ $and: [{ price: { $gte: 500000 } }, { listed: true }] }`
+- `$or` - Logical OR operation
+  - `{ $or: [{ price: { $lt: 100000 } }, { listed: false }] }`
+
+> ⚠️ **Warning**: When using `showIf` with complex conditions, ensure that:
+> - `$and` and `$or` operators contain arrays of conditions
+> - `$in` and `$nin` operators contain arrays of values
+> - `$includes` and `$nincludes` operators are only used on columns marked as arrays (`isArray: { enabled: true }`)
 ### Page size 
 
 use `options.listPageSize` to define how many records will be shown on the page

adminforth/modules/configValidator.ts

@@ -25,6 +25,7 @@ import {
   AdminForthComponentDeclaration , 
   AdminForthResourcePages,
   AdminForthDataTypes,
+  Predicate,
 } from "../types/Common.js";
 import AdminForth from "adminforth";
 import { AdminForthConfigMenuItem } from "adminforth";
@@ -781,6 +782,48 @@ export default class ConfigValidator implements IConfigValidator {
         errors.push(`Resource "${res.resourceId}" has more than one listSticky column. Only one column can be sticky in the list view.`);
       }
 
+      const conditionalColumns = res.columns.filter(c => c.showIf);
+      if (conditionalColumns.length) {
+        const checkConditionArrays = (predicate: Predicate, column: AdminForthResourceColumn) => {
+          if ("$and" in predicate && !Array.isArray(predicate.$and)) {
+        errors.push(`Resource "${res.resourceId}" column "${column.name}" has showIf with $and that is not an array`);
+          } else if ("$and" in predicate && Array.isArray(predicate.$and)) {
+        predicate.$and.forEach((item) => checkConditionArrays(item, column));
+          }
+
+          if ("$or" in predicate && !Array.isArray(predicate.$or)) {
+        errors.push(`Resource "${res.resourceId}" column "${column.name}" has showIf with $or that is not an array`);
+          } else if ("$or" in predicate && Array.isArray(predicate.$or)) {
+        predicate.$or.forEach((item) => checkConditionArrays(item, column));
+          }
+      
+          const fieldEntries = Object.entries(predicate).filter(([key]) => !key.startsWith('$'));
+          if (fieldEntries.length > 0) {
+        fieldEntries.forEach(([field, condition]) => {
+          if (typeof condition !== 'object') {
+            return;
+          }
+          if ("$in" in condition && !Array.isArray(condition.$in)) {
+            errors.push(`Resource "${res.resourceId}" column "${column.name}" has showIf with $in that is not an array`);
+          }
+          if ("$nin" in condition && !Array.isArray(condition.$nin)) {
+            errors.push(`Resource "${res.resourceId}" column "${column.name}" has showIf with $nin that is not an array`);
+          }
+          if ("$includes" in condition && !column.isArray) {
+            errors.push(`Resource "${res.resourceId}" has showIf with $includes on non-array column "${column.name}"`);
+          }
+          if ("$nincludes" in condition && !column.isArray) {
+            errors.push(`Resource "${res.resourceId}" has showIf with $nincludes on non-array column "${column.name}"`);
+          }
+        });
+          }
+        };
+        
+        conditionalColumns.forEach((column) => {
+          checkConditionArrays(column.showIf, column);
+        });
+      }
+
       const options: Partial<AdminForthResource['options']> = {...resInput.options, bulkActions: undefined, allowedActions: undefined};
 
       options.allowedActions = this.validateAndNormalizeAllowedActions(resInput, errors);

adminforth/spa/src/components/ResourceForm.vue

@@ -63,7 +63,7 @@
 
 <script setup lang="ts">
 
-import { applyRegexValidation, callAdminForthApi, loadMoreForeignOptions, searchForeignOptions, createSearchInputHandlers} from '@/utils';
+import { applyRegexValidation, callAdminForthApi, loadMoreForeignOptions, searchForeignOptions, createSearchInputHandlers, checkShowIf } from '@/utils';
 import { computedAsync } from '@vueuse/core';
 import { computed, onMounted, reactive, ref, watch, provide, type Ref } from 'vue';
 import { useRouter, useRoute } from 'vue-router';
@@ -322,7 +322,7 @@ async function searchOptions(columnName: string, searchTerm: string) {
 
 
 const editableColumns = computed(() => {
-  return props.resource?.columns?.filter(column => column.showIn?.[mode.value]);
+  return props.resource?.columns?.filter(column => column.showIn?.[mode.value] && (currentValues.value ? checkShowIf(column, currentValues.value) : true));
 });
 
 const isValid = computed(() => {

adminforth/spa/src/components/ShowTable.vue

@@ -24,14 +24,14 @@
               dark:bg-darkShowTablesBodyBackground dark:border-darkShowTableBodyBorder block md:table-row"
           >
             <component
-                v-if="column.components?.showRow"
+                v-if="column.components?.showRow && checkShowIf(column, record)"
                   :is="getCustomComponent(column.components.showRow)"
                   :meta="column.components.showRow.meta"
                   :column="column"
                   :resource="coreStore.resource"
                   :record="coreStore.record"
               />
-            <template v-else>
+            <template v-else-if="checkShowIf(column, record)">
               <td class="px-6 py-4 relative block md:table-cell font-bold md:font-normal pb-0 md:pb-4">
                 {{ column.label }}
               </td>
@@ -59,14 +59,15 @@
 
   <script setup lang="ts">
   import ValueRenderer from '@/components/ValueRenderer.vue';
-  import { getCustomComponent } from '@/utils';
+  import { getCustomComponent, checkShowIf } from '@/utils';
   import { useCoreStore } from '@/stores/core';
   import { computed } from 'vue';
-  import type { AdminForthResourceCommon } from '@/types/Common';
+  import type { AdminForthResourceCommon, AdminForthResourceColumnInputCommon } from '@/types/Common';
   const props = withDefaults(defineProps<{ 
     columns: Array<{
         name: string;
         label?: string;
+        showIf?: AdminForthResourceColumnInputCommon['showIf'];
         components?: {
           show?: {
             file: string;

adminforth/spa/src/utils.ts

@@ -8,6 +8,7 @@ import { Dropdown } from 'flowbite';
 import adminforth from './adminforth';
 import sanitizeHtml  from 'sanitize-html'
 import debounce from 'debounce';
+import type { AdminForthResourceColumnInputCommon, Predicate } from '@/types/Common';
 
 const LS_LANG_KEY = `afLanguage`;
 const MAX_CONSECUTIVE_EMPTY_RESULTS = 2;
@@ -421,4 +422,60 @@ export function createSearchInputHandlers(
     }
     return acc;
   }, {} as Record<string, (searchTerm: string) => void>);
+}
+
+export function checkShowIf(c: AdminForthResourceColumnInputCommon, record: Record<string, any>) {
+  if (!c.showIf) return true;
+
+  const evaluatePredicate = (predicate: Predicate): boolean => {
+    const results: boolean[] = [];
+
+    if ("$and" in predicate) {
+      results.push(predicate.$and.every(evaluatePredicate));
+    }
+
+    if ("$or" in predicate) {
+      results.push(predicate.$or.some(evaluatePredicate));
+    }
+
+    const fieldEntries = Object.entries(predicate).filter(([key]) => !key.startsWith('$'));
+    if (fieldEntries.length > 0) {
+      const fieldResult = fieldEntries.every(([field, condition]) => {
+        const recordValue = record[field];
+
+        if (condition === undefined) {
+          return true;
+        }
+        if (typeof condition !== "object" || condition === null) {
+          return recordValue === condition;
+        }
+
+        if ("$eq" in condition) return recordValue === condition.$eq;
+        if ("$not" in condition) return recordValue !== condition.$not;
+        if ("$gt" in condition) return recordValue > condition.$gt;
+        if ("$gte" in condition) return recordValue >= condition.$gte;
+        if ("$lt" in condition) return recordValue < condition.$lt;
+        if ("$lte" in condition) return recordValue <= condition.$lte;
+        if ("$in" in condition) return (Array.isArray(condition.$in) && condition.$in.includes(recordValue));
+        if ("$nin" in condition) return (Array.isArray(condition.$nin) && !condition.$nin.includes(recordValue));
+        if ("$includes" in condition)
+          return (
+            Array.isArray(recordValue) &&
+            recordValue.includes(condition.$includes)
+          );
+        if ("$nincludes" in condition)
+          return (
+            Array.isArray(recordValue) &&
+            !recordValue.includes(condition.$nicludes)
+          );
+
+        return true;
+      });
+      results.push(fieldResult);
+    }
+
+    return results.every(result => result);
+  };
+
+  return evaluatePredicate(c.showIf);
 }

adminforth/types/Common.ts

@@ -67,6 +67,11 @@ export type AllowedActionsResolved = {
   [key in AllowedActionsEnum]: boolean
 }
 
+// conditional operators for predicates
+type Value = any;
+type Operators = { $eq: Value } | { $not: Value } | { $gt: Value } | { $gte: Value } | { $lt: Value } | { $lte: Value } | { $in: Value[] } | { $nin: Value[] } | { $includes: Value } | { $nincludes: Value };
+export type Predicate = { $and: Predicate[] } | { $or: Predicate[] } | { [key: string]: Operators | Value };
+
 export interface AdminUser {
   /**
    * primaryKey field value of user in table which is defined by {@link AdminForthConfig.auth.usersResourceId}
@@ -876,6 +881,11 @@ export interface AdminForthResourceColumnInputCommon {
    * Sticky position for column
    */
   listSticky?: boolean;
+
+  /**
+   * Show field only if certain conditions are met.
+   */
+  showIf?: Predicate;
 }
 
 export interface AdminForthResourceColumnCommon extends AdminForthResourceColumnInputCommon {

dev-demo/resources/apartments.ts

@@ -118,6 +118,9 @@ export default {
       showIn: {list: true, create: true, edit: true, filter: true, show: true}, // 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
+      showIf: {number_of_rooms: {
+        $in: [3, 4]
+      }},
       components: {
         // edit: {
         //     file: '@@/IdShow.vue',