Routes Management

Learn how to configure custom route paths for create and update operations using the `routes` property in `CMS_FORM_CONFIG`. This feature allows you to override default API endpoints and customize the

Overview

The routes property in CMS_FORM_CONFIG allows you to:

1. Override default API endpoints - Customize the URL paths used for create and update operations

2. Use static routes - Define fixed route paths for create operations

3. Use dynamic routes - Define function-based routes that accept parameters for update operations

4. Customize routing behavior - Control how form submissions are routed to your backend API

---

Use Case 1: Static and Dynamic Routes

Scenario

You want to customize the API endpoints for form operations:

• Create operation: Use a custom static route 'new-create'

• Update operation: Use a dynamic route that includes the item ID: new-update/${id.id}

Configuration

import { CMS_FORM_CONFIG } from '@tradinos/cms-frontend-form';

{
  provide: CMS_FORM_CONFIG,
  useValue: {
    formMode: 'merge',
    parseToFormData: false,
    removeNullValues: false,
    routes: {
      create: 'new-create',                              // Static route for create
      update: (id: any) => `new-update/${id.id}`,       // Dynamic route for update
    },
    // ... other configurations
  },
}

Example from Codebase

File: src/app/dashboard/project/project.component.ts

{
  provide: CMS_FORM_CONFIG,
  useValue: {
    formMode: 'merge',
    parseToFormData: false,
    removeNullValues: false,
    routes: {
      update: (id: any) => `new-update/${id.id}`,
      create: 'new-create',
    },
    // ... other configurations
  },
}

Parameters Explained

Parameter	Type	Description	Required
routes	object	Configuration object for route paths	Optional
routes.create	string	Static route path for create operations	Optional
routes.update	(id: any) => string	Function that returns dynamic route path for update operations	Optional

How it Works

1. Create Route: The create property accepts a static string

   • When a form is submitted for creating a new entity, the library will use this route

   • Example: 'new-create' → API call to /new-create

2. Update Route: The update property accepts a function that receives the item ID

   • The function receives the item object (or ID) as a parameter

   • It should return a string representing the route path

   • Example: (id: any) => \new-update/${id.id}`→ API call to/new-update/123`

3. Default Behavior: If routes is not specified, the library uses default endpoints from CMS_CRUD_CONFIG

---

Use Case 2: Alternative Route Property Name

Scenario

Some configurations use route (singular) instead of routes (plural). Both are supported for backward compatibility.

Configuration

{
  provide: CMS_FORM_CONFIG,
  useValue: {
    formMode: 'merge',
    route: {                                    // Note: singular 'route'
      create: 'hello',
      update: (item: any) => `test/${item.id}`
    },
    // ... other configurations
  },
}

Example from Codebase

File: src/app/dashboard/users/users.component.ts

{
  provide: CMS_FORM_CONFIG,
  useValue: {
    formMode: 'merge',
    parseToFormData: false,
    removeNullValues: false,
    route: {                                    // Using singular 'route'
      create: 'hello',
      update: (item: any) => `test/${item.id}`
    },
    // ... other configurations
  },
}

---

Use Case 3: Dynamic Route with Complex Parameters

Scenario

You need to build a route path using multiple properties from the item object.

Configuration

routes: {
  update: (item: any) => {
    const categoryId = item.category?.id || item.categoryId;
    const itemId = item.id;
    return `categories/${categoryId}/items/${itemId}`;
  },
  create: (item: any) => {
    const categoryId = item.categoryId;
    return `categories/${categoryId}/items`;
  },
}

Parameters Explained

Parameter	Type	Description	Example
item	any	The entity object being created/updated	{ id: 123, name: 'Project', categoryId: 5 }
Return value	string	The route path to use for the API call	'categories/5/items/123'

---

Complete Examples

Example 1: Basic Routes Configuration

import { Component } from '@angular/core';
import { CMS_FORM_CONFIG } from '@tradinos/cms-frontend-form';
import { ProjectService } from './services/project.service';
import { Project } from './project.model';

@Component({
  selector: 'app-project',
  standalone: true,
  providers: [
    ProjectService,
    {
      provide: CMS_FORM_CONFIG,
      useValue: {
        formMode: 'merge',
        routes: {
          create: 'projects/create',
          update: (id: any) => `projects/update/${id.id}`,
        },
      },
    },
  ],
})
export class ProjectComponent {}

Result:

• Creating a new project → POST to /projects/create

• Updating project with ID 123 → PUT to /projects/update/123

---

Example 2: Nested Routes

{
  provide: CMS_FORM_CONFIG,
  useValue: {
    formMode: 'merge',
    routes: {
      create: 'api/v1/projects',
      update: (item: any) => `api/v1/projects/${item.id}/update`,
    },
  },
}

Result:

• Creating → POST to /api/v1/projects

• Updating → PUT to /api/v1/projects/123/update

---

Example 3: Conditional Routes

routes: {
  create: 'projects',
  update: (item: any) => {
    // Use different routes based on item status
    if (item.status === 'draft') {
      return `projects/${item.id}/draft`;
    }
    return `projects/${item.id}`;
  },
}

---

Comparison Table

Property	Type	Use Case	Example
routes.create	string	Static route for create	'new-create'
routes.update	(id: any) => string	Dynamic route for update	(id) => \update/${id.id}``
route.create	string	Alternative property name (singular)	'hello'
route.update	(item: any) => string	Alternative property name (singular)	(item) => \test/${item.id}``

---

Best Practices

1. Use consistent naming: Prefer routes (plural) for consistency, though route (singular) is also supported

2. Handle undefined values: Always check if properties exist before using them in dynamic routes

   update: (item: any) => `update/${item?.id || item?.id}`

3. Use TypeScript types: Define proper types for better type safety

   update: (item: Project) => `projects/${item.id}`

4. Keep routes simple: Avoid complex logic in route functions; extract to helper functions if needed

5. Document custom routes: Add comments explaining why custom routes are used if they differ from defaults

---

Common Patterns

Pattern 1: Simple Static Routes

routes: {
  create: 'create',
  update: (id: any) => `update/${id.id}`,
}

Pattern 2: API Versioning

routes: {
  create: 'api/v2/entities',
  update: (id: any) => `api/v2/entities/${id.id}`,
}

Pattern 3: Nested Resources

routes: {
  create: (item: any) => `users/${item.userId}/projects`,
  update: (item: any) => `users/${item.userId}/projects/${item.id}`,
}

---

Related Documentation

• App configuration - Learn about other CMS_FORM_CONFIG options

• Entity Service - Understand how EntityService handles API calls

• CRUD Configuration - See how CRUD endpoints are configured

---

Summary

The routes property in CMS_FORM_CONFIG provides flexible options for customizing API endpoints:

• Static routes: Use string values for fixed paths

• Dynamic routes: Use functions to generate paths based on item properties

• Flexible naming: Both routes (plural) and route (singular) are supported

• Override defaults: Custom routes take precedence over default CRUD endpoints

This feature enables fine-grained control over how form submissions are routed to your backend API, supporting complex routing scenarios and API versioning strategies.