Nested Multi Label

Learn how to configure labels for nested arrays and objects using the `FieldLabel` decorator with `property`, `nested`, and `type` options for arrays of objects and multi-language translations.

Overview

The FieldLabel decorator supports nested structures through the nested parameter, which allows you to:

1. Define labels for array items - When you have an array of objects, specify different labels for the array container and each item

2. Handle multi-language arrays - Use direct values for locale-based arrays

3. Configure editable nested fields - Use the property parameter to specify which field is editable in nested objects

---

Use Case 1: Array of Objects with i18n Labels

Scenario

You have an array of objects (e.g., tasks: TaskDTO[]) and you want:

• A label for the array itself: "Tasks" (plural)

• A label for each item in the array: "Task" (singular)

Configuration

import { FieldLabel } from '@tradinos/cms-backend-entity';
import { I18nTranslations } from 'src/generated/i18n.generated';

@ApiProperty({ type: TaskDTO, isArray: true })
@Type(() => TaskDTO)
@FieldLabel<TaskDTO, I18nTranslations>({
  property: "title",              // The property to use for editing/display
  type: "editable",               // Makes the field editable
  label: "labels.project.tasks",  // Label for the array (plural)
  nested: "labels.project.task"   // Label for each item (singular)
})
tasks: TaskDTO[];

Example from Codebase

File: src/domain/project/dtos/project.dto.ts

@ApiProperty({ type: TaskDTO, isArray: true })
@Type(() => TaskDTO)
@MinLength(1)
@MaxLength(5)
@FieldLabel<TaskDTO, I18nTranslations>({
  property: "title",
  type: "editable",
  label: "labels.project.tasks",
  nested: "labels.project.task"
})
tasks: TaskDTO[];

Parameters Explained

Parameter	Type	Description	Required
property	string	The property name in the nested object to use for editing/display (e.g., "title")	✅ Yes
type	"editable"	Makes the nested field editable in forms	Optional
label	string	i18n key for the array container label (plural)	✅ Yes
nested	string	i18n key for each item label (singular)	✅ Yes

How it Works

1. Array Label: The label parameter ("labels.project.tasks") is used for the array container

   • Example: "Tasks" (English) or "المهام" (Arabic)

2. Item Label: The nested parameter ("labels.project.task") is used for each item in the array

   • Example: "Task" (English) or "مهمة" (Arabic)

3. Editable Property: The property parameter ("title") specifies which field from TaskDTO is used for editing

   • When editing, the form will use the title field from each task

i18n Translation Files

English (src/i18n/en/labels.json):

{
  "project": {
    "tasks": "Tasks",
    "task": "Task"
  }
}

Arabic (src/i18n/ar/labels.json):

{
  "project": {
    "tasks": "المهام",
    "task": "مهمة"
  }
}

---

Use Case 2: Multi-Language Array with Direct Values

Scenario

You have an array of translation objects (e.g., translations: CreateCategoryTranslationDTO[]) where each item represents a different language, and you want to use direct locale values instead of i18n keys.

Configuration

@FieldLabel({ 
  property: 'locale',        // Property to use for identification
  nested: ['en', 'ar']       // Direct values for each language
})
translations!: CreateCategoryTranslationDTO[];

Example from Codebase

File: src/domain/category/dto/category.dto.ts

@IsArray()
@ApiProperty({ type: CreateCategoryTranslationDTO, isArray: true })
@Type(() => CreateCategoryTranslationDTO)
@ValidateNested({ each: true })
@FieldLabel({ property: 'locale', nested: ['en', 'ar'] })
translations!: CreateCategoryTranslationDTO[];

Parameters Explained

Parameter	Type	Description	Required
property	string	The property name that contains the identifier (e.g., "locale")	✅ Yes
nested	string[]	Array of direct values (not i18n keys)	✅ Yes

How it Works

1. Property Identification: The property parameter ("locale") identifies which field in the nested object contains the value

   • Each CreateCategoryTranslationDTO has a locale field

2. Direct Values: The nested array (['en', 'ar']) provides direct values

   • These are NOT i18n keys, but actual values that will be used

   • Each translation object will be labeled with its locale value: "en" or "ar"

Data Structure

// CategoryTranslationsDto
{
  id: string;
  name: string;
  locale: string;  // ← This property is used
  description?: string;
}

// Usage
translations: [
  { id: "1", name: "Category", locale: "en", description: "..." },
  { id: "2", name: "فئة", locale: "ar", description: "..." }
]

---

Use Case 3: Nested Object with Editable Property

Scenario

You have a nested object (not an array) and you want to specify which property is used for editing/display.

Configuration

@FieldLabel<BillingInformationDTO, I18nTranslations>({ 
  property: "country",        // Property to use for editing
  type: "editable",           // Makes it editable
  label: "labels.project.billing" 
})
billing: BillingInformationDTO;

Example from Codebase

File: src/domain/project/dtos/project.dto.ts

@ApiProperty({ type: BillingInformationDTO })
@Type(() => BillingInformationDTO)
@ValidateNested({
  message: i18nValidationMessage('validation.INVALID_NESTED_OBJECT'),
})
@FieldLabel<BillingInformationDTO, I18nTranslations>({ 
  property: "country", 
  type: "editable", 
  label: "labels.project.billing" 
})
billing: BillingInformationDTO;

Parameters Explained

Parameter	Type	Description	Required
property	string	The property name in the nested object to use for editing/display	✅ Yes
type	"editable"	Makes the nested field editable in forms	Optional
label	string	i18n key for the nested object label	✅ Yes

---

Complete Examples

Example 1: Tasks Array (Full Implementation)

// TaskDTO
export class TaskDTO {
  @ApiProperty({ type: String })
  @IsString()
  id: string;

  @ApiProperty({ type: String })
  @IsString()
  title: string;  // ← This property is used

  @ApiProperty({ type: String, required: false })
  @IsString()
  @IsOptional()
  description: string | null;
}

// ProjectDTO
export class ProjectDTO {
  @ApiProperty({ type: TaskDTO, isArray: true })
  @Type(() => TaskDTO)
  @MinLength(1)
  @MaxLength(5)
  @FieldLabel<TaskDTO, I18nTranslations>({
    property: "title",              // Uses TaskDTO.title
    type: "editable",               // Editable in forms
    label: "labels.project.tasks",  // Array label: "Tasks"
    nested: "labels.project.task"   // Item label: "Task"
  })
  tasks: TaskDTO[];
}

Result:

• Array is labeled: "Tasks" (from labels.project.tasks)

• Each item is labeled: "Task" (from labels.project.task)

• The title property is used for editing each task

---

Example 2: Translations Array (Full Implementation)

// CreateCategoryTranslationDTO
export class CreateCategoryTranslationDTO {
  @ApiProperty({ type: "string" })
  @IsString()
  id: string;

  @ApiProperty({ type: "string" })
  @IsString()
  name: string;

  @ApiProperty({ type: "string" })
  @IsString()
  locale: string;  // ← This property is used

  @ApiProperty({ type: "string", required: false })
  @IsString()
  @IsOptional()
  description?: string | null;
}

// CreateCategoryDTO
export class CreateCategoryDTO {
  @IsArray()
  @ApiProperty({ type: CreateCategoryTranslationDTO, isArray: true })
  @Type(() => CreateCategoryTranslationDTO)
  @ValidateNested({ each: true })
  @FieldLabel({ 
    property: 'locale',        // Uses CreateCategoryTranslationDTO.locale
    nested: ['en', 'ar']       // Direct values: "en" and "ar"
  })
  translations!: CreateCategoryTranslationDTO[];
}

Result:

• Each translation item is labeled with its locale value: "en" or "ar"

• No i18n translation needed for the labels (direct values)

---

Comparison Table

Use Case	nested Type	property	type	Use Case
Array with i18n	string (i18n key)	✅ Required	"editable"	Array of objects with translated labels
Multi-language array	string[] (direct values)	✅ Required	❌ Not used	Array with locale-based items
Nested object	❌ Not used	✅ Required	"editable"	Single nested object

---

Best Practices

1. Use i18n for user-facing labels: When labels need translation, use string i18n keys in the nested parameter

2. Use direct values for identifiers: When labels are identifiers (like locale codes), use string arrays

3. Always specify property: The property parameter is required for nested structures to identify which field to use

4. Use type: "editable" for forms: When you want the nested field to be editable in forms, include type: "editable"

---

Common Patterns

Pattern 1: Array of Objects with Singular/Plural Labels

@FieldLabel<ItemDTO, I18nTranslations>({
  property: "name",
  type: "editable",
  label: "labels.entity.items",    // Plural: "Items"
  nested: "labels.entity.item"      // Singular: "Item"
})
items: ItemDTO[];

Pattern 2: Multi-Language Translations

@FieldLabel({ 
  property: 'locale', 
  nested: ['en', 'ar', 'fr'] 
})
translations!: TranslationDTO[];

Pattern 3: Nested Object with Display Property

@FieldLabel<NestedDTO, I18nTranslations>({ 
  property: "displayName", 
  type: "editable", 
  label: "labels.entity.nested" 
})
nested: NestedDTO;

---

Related Documentation

• Fields Labels Control - Learn about basic FieldLabel usage

• Localization - Understand how localization works

• Validation Messages - See how validation works with nested structures

---

Summary

The nested parameter in FieldLabel decorator provides powerful options for handling complex nested structures:

• String (i18n key): For translated labels in arrays of objects

• String array (direct values): For locale-based or identifier-based arrays

• Property parameter: Always required to specify which field to use

• Type parameter: Use "editable" to make nested fields editable in forms

This feature enables flexible labeling for arrays, nested objects, and multi-language structures in your DTOs.