Async Manual Inputs

Learn how to use async/await with `manualInputsFn` to load data dynamically before building form inputs.

Async Manual Inputs

Learn how to use async/await with manualInputsFn to load data dynamically before building form inputs. This feature allows you to fetch data from APIs, load configurations, or perform any asynchronous operations before returning the form input array.

A comprehensive guide for using asynchronous operations in manualInputsFn. This guide covers how to make manualInputsFn async, fetch data from APIs, load dropdown options dynamically, and handle loading states.

---

Overview

The manualInputsFn property in EntityService supports async functions, which allows you to:

1. Fetch data from APIs - Load dropdown options, configurations, or related data before building the form

2. Load external configurations - Fetch form configurations from remote sources

3. Perform async validations - Check data availability or permissions before showing fields

4. Handle dynamic form building - Build form inputs based on async data dependencies

---

Use Case 1: Loading Dropdown Options from API

Scenario

You need to load dropdown options from an API before building the form. Instead of using remoteDataConfiguration, you want to fetch the data upfront and populate the options synchronously.

Configuration

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { EntityService } from '@tradinos/cms-frontend-entity';
import { FormInput, FormInputType } from '@tradinos/cms-frontend-form';
import { Project } from './project.model';

@Injectable()
export class ProjectService extends EntityService<Project> {
  constructor(private http: HttpClient) {
    super();
  }

  override manualInputsFn = async (project?: Project) => {
    // Fetch users from API before building form
    const usersResponse = await firstValueFrom(
      this.http.get<any>('user', { params: { limit: 100 } })
    );
    const users = Array.isArray(usersResponse.data) 
      ? usersResponse.data 
      : [];

    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'user_id',
        label: 'users',
        inputType: FormInputType.dropdown,
        dropdownConfiguration: {
          showClear: true,
          filter: true,
          filterBy: 'name',
          options: users.map(user => ({
            name: user.name,
            id: user.id
          })),
          optionLabel: 'name',
          valueBy: 'id',
        }
      },
    ] as FormInput<Project>[];
  }
}

Example from Codebase

File: src/app/dashboard/project me/services/projectme.service.ts

import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

@Injectable()
export class ProjectService extends EntityService<Project> {
  constructor(private http: HttpClient) {
    super();
  }

  override manualInputsFn = async (project?: Project) => {
    // Load tags from API before building form inputs
    const tagsOptions = await this.loadTagsFromAPI();

    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'tags',
        label: 'Tags',
        inputType: FormInputType.multiSelect,
        multiSelectConfiguration: {
          options: tagsOptions,  // Tags loaded from API
          optionLabel: 'name',
          valueBy: 'tag_id',
        }
      },
    ] as FormInput<Project>[];
  }

  private async loadTagsFromAPI(): Promise<Array<{name: string, tag_id: string}>> {
    try {
      const response = await firstValueFrom(
        this.http.get<any>('tags', { params: { limit: 100 } })
      );
      const tags = Array.isArray(response.data) ? response.data : [];
      return tags.map((tag: any) => ({
        name: tag.name || tag.label || tag.title,
        tag_id: tag.id || tag.tag_id || tag.value
      }));
    } catch (error) {
      // Fallback to hardcoded tags if API fails
      console.warn('Failed to load tags from API, using fallback tags:', error);
      return this.getFallbackTags();
    }
  }

  private getFallbackTags(): Array<{name: string, tag_id: string}> {
    return [
      {name: 'Web Development', tag_id: 'web'},
      {name: 'Mobile App', tag_id: 'mobile'},
      // ... more tags
    ];
  }
}

Parameters Explained

Parameter	Type	Description	Required
manualInputsFn	(item?: T) => Promise<FormInput<T>[]>	Async function that returns a Promise of form inputs	Required
Return type	Promise<FormInput<T>[]>	Promise that resolves to an array of form inputs	Required

How it Works

1. Async Function: Declare manualInputsFn as an async function

   override manualInputsFn = async (project?: Project) => {

2. Await Data: Use await to fetch data before building form inputs

   const users = await firstValueFrom(this.http.get('user'));

3. Return Inputs: Return the form inputs array after data is loaded

   return [/* form inputs */] as FormInput<Project>[];

4. Form Building: The form library waits for the Promise to resolve before rendering the form

---

Use Case 2: Loading Multiple Data Sources

Scenario

You need to load data from multiple APIs before building the form, and some fields depend on the loaded data.

Configuration

override manualInputsFn = async (project?: Project) => {
  // Load multiple data sources in parallel
  const [users, categories, tags] = await Promise.all([
    firstValueFrom(this.http.get('user')).then(r => r.data || []),
    firstValueFrom(this.http.get('categories')).then(r => r.data || []),
    firstValueFrom(this.http.get('tags')).then(r => r.data || []),
  ]);

  // Build form inputs with loaded data
  return [
    {
      key: 'name',
      inputType: FormInputType.text,
      value: project?.name,
    },
    {
      key: 'user_id',
      inputType: FormInputType.dropdown,
      dropdownConfiguration: {
        options: users.map(u => ({ name: u.name, id: u.id })),
        optionLabel: 'name',
        valueBy: 'id',
      }
    },
    {
      key: 'category_id',
      inputType: FormInputType.dropdown,
      dropdownConfiguration: {
        options: categories.map(c => ({ name: c.name, id: c.id })),
        optionLabel: 'name',
        valueBy: 'id',
      }
    },
    {
      key: 'tags',
      inputType: FormInputType.multiSelect,
      multiSelectConfiguration: {
        options: tags.map(t => ({ name: t.name, id: t.id })),
        optionLabel: 'name',
        valueBy: 'id',
      }
    },
  ] as FormInput<Project>[];
}

How it Works

1. Parallel Loading: Use Promise.all() to load multiple data sources simultaneously

2. Data Transformation: Transform API responses into the format needed for form inputs

3. Form Building: Build form inputs with all loaded data available

---

Use Case 3: Conditional Fields Based on Async Data

Scenario

You need to check permissions or fetch user-specific data to determine which fields should be visible in the form.

Configuration

override manualInputsFn = async (project?: Project) => {
  // Fetch user permissions
  const permissions = await firstValueFrom(
    this.http.get('user/permissions')
  );

  const inputs: FormInput<Project>[] = [
    {
      key: 'name',
      inputType: FormInputType.text,
      value: project?.name,
    },
  ];

  // Conditionally add fields based on permissions
  if (permissions.canManageUsers) {
    inputs.push({
      key: 'user_id',
      inputType: FormInputType.dropdown,
      dropdownConfiguration: {
        options: await this.loadUsers(),
        optionLabel: 'name',
        valueBy: 'id',
      }
    });
  }

  if (permissions.canManageCategories) {
    inputs.push({
      key: 'category_id',
      inputType: FormInputType.dropdown,
      dropdownConfiguration: {
        options: await this.loadCategories(),
        optionLabel: 'name',
        valueBy: 'id',
      }
    });
  }

  return inputs;
}

---

Use Case 4: Loading Form Configuration from API

Scenario

You want to fetch form field configurations from a remote API, allowing dynamic form structure without code changes.

Configuration

override manualInputsFn = async (project?: Project) => {
  // Fetch form configuration from API
  const formConfig = await firstValueFrom(
    this.http.get<FormConfig>('forms/project-config')
  );

  // Build form inputs based on configuration
  return formConfig.fields.map(field => ({
    key: field.key,
    inputType: field.type,
    label: field.label,
    value: project?.[field.key],
    validation: field.validation,
  })) as FormInput<Project>[];
}

---

Complete Examples

Example 1: Loading Tags from API (Real Implementation)

This example shows a real implementation from the codebase where tags are loaded from API with fallback mechanism.

File: src/app/dashboard/project me/services/projectme.service.ts

import { HttpClient, HttpResponse } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { EntityService } from '@tradinos/cms-frontend-entity';
import { FormInput, FormInputType } from '@tradinos/cms-frontend-form';
import { Project } from '../projectme.model';
import { firstValueFrom } from 'rxjs';

@Injectable()
export class ProjectService extends EntityService<Project> {
  constructor(private http: HttpClient) {
    super();
  }

  // Async Manual Inputs Configuration
  // See documentation: docs/[Frontend] Form/Async Manual Inputs.md
  // Loading tags from API instead of hardcoded values
  override manualInputsFn = async (project?: Project) => {
    // Load tags from API before building form inputs
    const tagsOptions = await this.loadTagsFromAPI();

    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'tags',
        label: 'Tags',
        inputType: FormInputType.multiSelect,
        value: project?.tags ?
          project.tags.filter(tag => tag !== null && tag !== undefined && tag !== '')
            .map(tag => ({ tag_id: tag, name: this.getTagName(tag) }))
          : [],
        multiSelectConfiguration: {
          showClear: true,
          filter: true,
          filterBy: 'name',
          optionLabel: 'name',
          valueBy: 'tag_id',
          // Async Tags Loading: Loading tags from API instead of hardcoded values
          // See documentation: docs/[Frontend] Form/Async Manual Inputs.md
          options: tagsOptions,
        },
      },
    ] as FormInput<Project>[];
  }

  // Async Tags Loading Method
  // Loads tags from API endpoint
  // Falls back to hardcoded tags if API fails
  private async loadTagsFromAPI(): Promise<Array<{name: string, tag_id: string}>> {
    try {
      // Try to load tags from API
      const response = await firstValueFrom(
        this.http.get<any>('tags', { params: { limit: 100 } })
      );
      
      // Map API response to expected format
      const tags = Array.isArray(response.data) ? response.data : [];
      return tags.map((tag: any) => ({
        name: tag.name || tag.label || tag.title,
        tag_id: tag.id || tag.tag_id || tag.value
      }));
    } catch (error) {
      // Fallback to hardcoded tags if API fails
      console.warn('Failed to load tags from API, using fallback tags:', error);
      return this.getFallbackTags();
    }
  }

  // Fallback tags if API fails
  private getFallbackTags(): Array<{name: string, tag_id: string}> {
    return [
      {name: 'Web Development', tag_id: 'web'},
      {name: 'Mobile App', tag_id: 'mobile'},
      {name: 'UI/UX Design', tag_id: 'design'},
      {name: 'E-commerce', tag_id: 'ecommerce'},
      {name: 'API Integration', tag_id: 'api'},
      {name: 'Database', tag_id: 'database'},
      {name: 'Cloud Computing', tag_id: 'cloud'},
      {name: 'Machine Learning', tag_id: 'ml'},
      {name: 'DevOps', tag_id: 'devops'},
      {name: 'Security', tag_id: 'security'}
    ];
  }

  private getTagName(tagValue: string): string {
    const fallbackTags = this.getFallbackTags();
    const foundTag = fallbackTags.find(option => option.tag_id === tagValue);
    return foundTag ? foundTag.name : tagValue;
  }
}

Result:

• Tags are loaded from API before form renders

• If API fails, fallback tags are used automatically

• Form displays tags immediately without waiting for dropdown open

• Tags are dynamic and can be managed from backend

---

Example 2: Simple Async Dropdown Loading

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { EntityService } from '@tradinos/cms-frontend-entity';
import { FormInput, FormInputType } from '@tradinos/cms-frontend-form';
import { Project } from './project.model';

@Injectable()
export class ProjectService extends EntityService<Project> {
  constructor(private http: HttpClient) {
    super();
  }

  override manualInputsFn = async (project?: Project) => {
    // Load users from API
    const usersResponse = await firstValueFrom(
      this.http.get<any>('user', { params: { limit: 100 } })
    );
    const users = usersResponse.data || [];

    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'user_id',
        label: 'Assigned User',
        inputType: FormInputType.dropdown,
        value: project?.user_id,
        dropdownConfiguration: {
          showClear: true,
          filter: true,
          options: users.map(user => ({
            name: user.name,
            id: user.id
          })),
          optionLabel: 'name',
          valueBy: 'id',
        }
      },
    ] as FormInput<Project>[];
  }
}

Result:

• Form waits for users to load before rendering

• Dropdown is populated with user options

• No need for remoteDataConfiguration since data is loaded upfront

---

Example 2: Loading with Error Handling

override manualInputsFn = async (project?: Project) => {
  try {
    // Attempt to load users
    const usersResponse = await firstValueFrom(
      this.http.get<any>('user', { params: { limit: 100 } })
    );
    const users = usersResponse.data || [];

    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'user_id',
        inputType: FormInputType.dropdown,
        dropdownConfiguration: {
          options: users,
          optionLabel: 'name',
          valueBy: 'id',
        }
      },
    ] as FormInput<Project>[];
  } catch (error) {
    // Fallback to empty options if API fails
    console.error('Failed to load users:', error);
    return [
      {
        key: 'name',
        inputType: FormInputType.text,
        value: project?.name,
      },
      {
        key: 'user_id',
        inputType: FormInputType.dropdown,
        dropdownConfiguration: {
          options: [],
          optionLabel: 'name',
          valueBy: 'id',
        }
      },
    ] as FormInput<Project>[];
  }
}

---

Example 3: Sequential Data Loading with Dependencies

override manualInputsFn = async (project?: Project) => {
  // Step 1: Load categories
  const categoriesResponse = await firstValueFrom(
    this.http.get('categories')
  );
  const categories = categoriesResponse.data || [];

  // Step 2: Load subcategories based on selected category
  let subcategories = [];
  if (project?.category_id) {
    const subcategoriesResponse = await firstValueFrom(
      this.http.get(`categories/${project.category_id}/subcategories`)
    );
    subcategories = subcategoriesResponse.data || [];
  }

  return [
    {
      key: 'name',
      inputType: FormInputType.text,
      value: project?.name,
    },
    {
      key: 'category_id',
      inputType: FormInputType.dropdown,
      value: project?.category_id,
      dropdownConfiguration: {
        options: categories,
        optionLabel: 'name',
        valueBy: 'id',
      },
      onChange: async (categoryId: string) => {
        // Load subcategories when category changes
        if (categoryId) {
          const response = await firstValueFrom(
            this.http.get(`categories/${categoryId}/subcategories`)
          );
          // Update subcategory dropdown options
          // (This would require additional form update logic)
        }
      }
    },
    {
      key: 'subcategory_id',
      inputType: FormInputType.dropdown,
      value: project?.subcategory_id,
      dropdownConfiguration: {
        options: subcategories,
        optionLabel: 'name',
        valueBy: 'id',
      }
    },
  ] as FormInput<Project>[];
}

---

Comparison Table

Approach	Use Case	Pros	Cons
Async manualInputsFn	Load data before form renders	Data available immediately, simpler dropdown config	Form waits for data to load
remoteDataConfiguration	Load data on dropdown open	Faster initial load, lazy loading	More complex configuration
Static options	Fixed, known options	Fastest, no API calls	Not dynamic

---

Best Practices

1. Use Promise.all() for parallel loading: When loading multiple independent data sources, load them in parallel

   const [users, categories] = await Promise.all([
     this.loadUsers(),
     this.loadCategories(),
   ]);

2. Handle errors gracefully: Always wrap async operations in try-catch blocks

   try {
     const data = await this.loadData();
   } catch (error) {
     console.error('Failed to load data:', error);
     // Provide fallback
   }

3. Cache loaded data: Consider caching data if it doesn't change frequently

   private cachedUsers: any[] | null = null;
   
   private async loadUsers(): Promise<any[]> {
     if (this.cachedUsers) return this.cachedUsers;
     this.cachedUsers = await firstValueFrom(this.http.get('user'));
     return this.cachedUsers;
   }

4. Use firstValueFrom for HTTP calls: Convert Observables to Promises using firstValueFrom

   const data = await firstValueFrom(this.http.get('endpoint'));

5. Provide loading states: Consider showing a loading indicator while form inputs are being built

6. Type your responses: Use TypeScript types for better type safety

   interface UsersResponse {
     data: User[];
   }
   const response = await firstValueFrom(
     this.http.get<UsersResponse>('user')
   );

---

Common Patterns

Pattern 1: Simple API Data Loading

override manualInputsFn = async (item?: T) => {
  const data = await firstValueFrom(this.http.get('endpoint'));
  return [/* form inputs using data */];
}

Pattern 2: Parallel Data Loading

override manualInputsFn = async (item?: T) => {
  const [data1, data2, data3] = await Promise.all([
    firstValueFrom(this.http.get('endpoint1')),
    firstValueFrom(this.http.get('endpoint2')),
    firstValueFrom(this.http.get('endpoint3')),
  ]);
  return [/* form inputs */];
}

Pattern 3: Conditional Field Loading

override manualInputsFn = async (item?: T) => {
  const permissions = await this.loadPermissions();
  const inputs: FormInput<T>[] = [/* base inputs */];
  
  if (permissions.canEdit) {
    inputs.push(/* additional inputs */);
  }
  
  return inputs;
}

Pattern 4: Error Handling with Fallback

override manualInputsFn = async (item?: T) => {
  try {
    const data = await this.loadData();
    return [/* inputs with data */];
  } catch (error) {
    console.error('Error loading data:', error);
    return [/* fallback inputs */];
  }
}

---

Related Documentation

• Observable Value - Learn about using Observables in form values

• Form Input Types - See available form input types

• Dropdown Configuration - Understand dropdown options

---

Summary

The manualInputsFn property supports async functions, enabling powerful form building capabilities:

• Async/await support: Use async functions to load data before building forms

• API integration: Fetch dropdown options, configurations, or related data

• Parallel loading: Load multiple data sources simultaneously with Promise.all()

• Error handling: Gracefully handle API failures with try-catch blocks

• Conditional fields: Show/hide fields based on async data (permissions, configurations)

This feature enables dynamic form building where form structure and options depend on data loaded from APIs or other async sources, providing flexibility and reducing the need for static configurations.