AdminForth Documentation

By default, AdminForth connects directly to databases like PostgreSQL, MySQL, ClickHouse, or MongoDB. However, you can decouple AdminForth from your database by routing all read and write operations through an external API layer (such as REST, GraphQL, or JSON-RPC).

Why use an API-backed approach?

• Enforced Constraints: Your API can enforce custom validation rules that exist outside the database schema.
• Advanced Auditing: While AdminForth has a built-in AuditLog for data modifications, using an API allows you to log all operations, including read operations, via your own logging systems.
• Complex Logic: You can trigger distributed workflows or complex business logic during data mutations that the database layer alone cannot handle.
• Unsupported Databases: If you need to use a database not natively supported by AdminForth, you can implement a custom adapter.

Implementation Strategy

To implement this, you must extend the AdminForth data connector class and implement the specific methods responsible for data access (reads) and mutations (writes). This effectively turns AdminForth into a consumer of your API rather than a direct database client.

All AI completion adapters in AdminForth implement the CompletionAdapter interface, ensuring a consistent way to interact with different AI models (OpenAI, Gemini, etc.). The core method is complete(), which accepts a configuration object for text generation, structured output, and streaming.

Key parameters for complete():

• content: The prompt string.
• maxTokens: Maximum number of tokens to generate.
• outputSchema: (Optional) Defines a JSON schema for structured responses.
• reasoningEffort: (Optional) Controls reasoning depth ('none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'). Defaults to 'low'.
• tools: (Optional) Array of CompletionTool objects.
• onChunk: (Optional) A callback function for streaming responses and reasoning events.

complete({
  content: string,
  maxTokens: number,
  outputSchema?: any,
  reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh',
  tools?: CompletionTool[],
  onChunk?: (
    chunk: string,
    event?: {
      type: 'output' | 'reasoning';
      delta: string;
      text: string;
      source?: 'summary' | 'text';
    },
  ) => void | Promise<void>,
})

While most injections accept an array where the order is determined by the array index, you can dynamically control the rendering order using the meta.afOrder property.

How it works:

• The higher the afOrder value, the earlier the component is rendered.
• This is particularly useful for plugin developers who want to allow users to position plugin-provided components within an existing injection list.

// Using afOrder to control rendering sequence
{
  customization: {
    globalInjections: {
      userMenu: [
        {
          file: '@@/CustomUserMenuItem.vue',
          meta: { afOrder: 10 } // Renders first
        },
        {
          file: '@@/AnotherCustomUserMenuItem.vue',
          meta: { afOrder: 20 } // Renders second
        },
        {
          file: '@@/LastCustomUserMenuItem.vue',
          meta: { afOrder: 5 } // Renders last
        },
      ]
    }
  }
}

You can dynamically show or hide columns in forms and views based on the values of other fields using the showIf property. This supports equality, comparison, array, and logical operators.

Logical Operators

Use $and and $or to combine conditions. These must contain arrays of conditions.

Comparison Operators

• $gt: Greater than
• $gte: Greater than or equal to
• $lt: Less than
• $lte: Less than or equal to
• $eq: Equal to (default)
• $not: Not equal to

Array Operators

Note: $includes and $nincludes should only be used on columns where isArray: { enabled: true } is set.

• $in: Value is in array
• $nin: Value is not in array
• $includes: Array includes value
• $nincludes: Array does not include value

Example: Complex Logic

export default {
  columns: [
    {
      name: 'premium_features',
      type: AdminForthDataTypes.JSON,
      showIf: {
        $and: [
          { price: { $gte: 500000 } },
          { apartment_type: { $in: ['penthouse', 'apartment'] } }
        ]
      }
    }
  ]
}

When performing operations on multiple selected records, you have two patterns:

1. Using action with bulkButton (Parallel Execution)

If you define showIn.bulkButton: true and only provide an action handler, AdminForth will execute that action function once per selected record in parallel using Promise.all. This is suitable for simple, independent tasks.

2. Using bulkHandler (Batched Execution)

For efficiency (e.g., a single SQL UPDATE for all IDs), define a bulkHandler. This is called once with all selected IDs. If both action and bulkHandler are present, bulkHandler is used for bulk operations and action is used for single-record operations.

{
  name: 'Auto submit',
  // bulkHandler receives all recordIds in one call
  bulkHandler: async ({ recordIds, adminforth, resource }) => {
    await doSomethingBatch(recordIds);
    return { ok: true, successMessage: `Processed ${recordIds.length} records` };
  },
  // action is used for single-record show/edit buttons
  action: async ({ recordId }) => {
    await doSomething(recordId);
    return { ok: true, successMessage: 'Done' };
  },
  showIn: {
    bulkButton: true,
    showButton: true,
  }
}

AdminForth is built around several key abstractions that map database structures to an administrative UI:

• dataSource: A connection to a specific database (e.g., MySQL, Postgres, MongoDB) identified by a unique id and a standard URI url.
• resource: A representation of a database table or collection. It links to a dataSource via its ID and defines which table it represents.
• column / field: A representation of a database column. While column is used in the context of a resource definition, field is used when discussing the data within a specific record.
• record: A single row in a relational database or a single document in a document database.
• action: Operations performed on resources or records (e.g., create, edit, delete, list, show, filter).
• adminUser: The object representing the currently authenticated user.
• component: A Vue frontend component used to build custom pages or extend existing AdminForth UI elements.
• Plugin: A class used to extend AdminForth by modifying its configuration, adding frontend components, or injecting backend hooks, helping to reduce boilerplate in the main config.