Module Theming Configuration

1. Overview

The mobile app allows custom color theming for each module's UI cards through gradient color codes. This is implemented via Dart evaluation code that returns two hexadecimal color values.

2. Gradient Color Configuration

Purpose

• Apply brand-specific or module-specific color schemes

• Create visual distinction between different modules

• Enhance user experience with consistent theming

Implementation

List<String> gradientColors() {
  return [
    '0xff1c5f71', // Primary gradient color (dark teal)
    '0xffd0e1e6' // Secondary gradient color (light blue)
  ];
}

Technical Notes

1. Format Requirements

   • Must return exactly 2 colors

   • Colors must be in ARGB format

   • Function name must be gradientColors()

2. Error Handling

   • Invalid colors default to system theme

   • Missing function shows neutral gray gradient

3. Performance

   • Colors are cached after first load

   • No impact on list scrolling performance

Activity Tab Visibility Control (My journey , Team Journey)

1. Overview

The mobile app provides control over the display of activity tabs (Appointment/Journey Plan/Visit Plan) through a Dart evaluation function. This allows administrators to configure whether users see individual and team records in these modules.

2. Configuration Options

Default Behavior

• Activity tabs are visible by default (true)

• Shows both individual and team records

Disabling the Feature

bool activityTab() {
  return false; // Hides the activity tab completely
}

3. Implementation Guide

Key Characteristics:

• Simple boolean toggle (true/false)

• Affects all activity-type modules

• Applies to both mobile and tablet views

4. Usage Scenarios

When to Enable (true)

• Field teams need to coordinate visits

• Managers must view team schedules

• Shared appointment tracking required

When to Disable (false)

• Individual-only tracking needed

• Confidential visit records

• Simplified user interface desired

5. Technical Specifications

Function Requirements:

• Must be named exactly activityTab()

• Must return boolean primitive

• No parameters accepted

Date Field Range Configuration

1. Overview

Control date field behavior in forms by specifying valid date ranges through Dart evaluation. This ensures users can only select dates within business-appropriate timeframes.

2. Configuration Structure

Base Template

Map<String, dynamic> dateConfiguration() {
  return {
    "date_properties": [
      {
        "api_name": "field_api_name",
        "start_date": "YYYY-MM-DD",
        "end_date": "YYYY-MM-DD"
      }
    ]
  };
}

3. Common Use Cases

A. Date of Birth (Past Dates Only)

dateConfiguration() {
  return {
    "date_properties": [
      {
        "api_name": "dob",
        "start_date": "1900-01-01",
        "end_date": "today" // No future dates
      }
    ]
  };
}

B. Closing Date (Future Dates Only)

dateConfiguration() {
  return {
    "date_properties": [
      {
        "api_name": "Closing_Date",
        "start_date": "today", // No past dates
        "end_date": "2100-01-01"
      }
    ]
  };
}

C. Event Date (Specific Range)

dateConfiguration() {
  return {
    "date_properties": [
      {
        "api_name": "Event_Date",
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
      }
    ]
  };
}

4. Default Behavior

If no configuration is specified:

• All date fields default to 1900-01-01 through 2100-01-01

• Full calendar history/future available

5. Technical Specifications

Validation Rules:

1. Date format must be YYYY-MM-DD

2. start_date must be ≤ end_date

3. Field API names are case-sensitive

6. Implementation Guide

1. For Birth Dates:

   "start_date": "today",
   "end_date": "2100-01-01"

2. For Future Deadlines:

   "start_date": "today",
   "end_date": "2100-01-01"

3. For Fiscal Year:

   "start_date": "2024-04-01",
   "end_date": "2025-03-31"

   7. Error Handling

   Issue	System Response
   Invalid date format	Falls back to default range
   Nonexistent field	Ignores configuration
   Overlapping ranges	Uses most restrictive bounds

Work Location Attendance Configuration

1. Overview

The attendance system supports multiple work location options with geofencing validation. This configuration enables:

• Flexible work location tracking (Office/Home/Client Site)

• Location-based attendance validation

• Client site lookup functionality

2. Configuration Structure

Map<String,dynamic> isWorkAt() {
  return {
    "work_at": "Office,Home,Client Site",
    "url": "https://org-specific-api-endpoint",
    "lookup_data": {
        "label": "Display Field",
        "associatedDoctype": "Related_Module",
        "doctype": "Target_Module"
    },
    "geofence": [
      {"lat": "27.196978", "long": "77.997150", "range_in_meter": 500}
    ]
  };
}

Parameter Details

Core Parameters

Lookup Configuration

Geofencing

Implementation Examples

Basic Configuration

{
  "work_at": "Office,Remote",
  "url": "https://yourdomain.com/api/attendance"
}

With Client Site Lookup

{
  "work_at": "HQ,Branch,Client Location",
  "lookup_data": {
    "label": "Client Name",
    "associatedDoctype": "Client_Visits",
    "doctype": "Contacts"
  }
}

With Geofencing

{
  "geofence": [
    {"lat": "28.4595", "long": "77.0266", "range_in_meter": 300}, // Office
    {"lat": "28.7041", "long": "77.1025", "range_in_meter": 1000} // Warehouse
  ]
}

UI Behavior

1. Location Selection

   • Presents as chip options

   • Changes required fields dynamically

   • Client Site selection triggers lookup

2. Geofencing

   • Validates user is within radius

   • Shows distance indicator

   • Allows manual override with reason

Data Flow

Troubleshooting

Dynamic Card Color Coding by Status

1. Overview

Implement status-based visual indicators for list records through dynamic color coding. This feature allows immediate visual recognition of record statuses through background or accent colors.

2. Configuration Structure

Map<String,dynamic> colorCode() {
  return {
    "Status": {
      "Draft": "4dbada",       // Light blue
      "Approved": "a6ec88",    // Green
      "Pending": "9c9c9c",     // Gray
      "Rejected": "f82945"     // Red
    }
  };
}

3. Implementation Guide

Color Mapping Rules

Supported Status Types

• System-defined statuses (e.g., "Approved", "Pending")

• Custom status values

• Multi-word statuses (use exact phrasing)

UI Behavior

1. Visual Representation

   • Status bar accent coloring

   • Full card background tinting

   • Badge color synchronization

     Field Visibility & Form Validations

     Overview

     This document outlines the field visibility rules and form validations applied to the Create & Edit forms. These rules ensure that only relevant fields are displayed and validate user inputs before saving.

     Field Visibility Validations

     Use Case

     When selecting a Payment Method, specific fields should be displayed based on the selected option:

     • If UPI is selected, the UPI_Id field should be visible and required.

     • If Cheque is selected, the Cheque_no and Cheque_Information fields should be visible and required.

     • If Cash, NEFT/RTGS, or UPI is selected, the Cash_UPI_NEFT_Information field should be visible and required.

     Implementation

     The following structure defines the field visibility rules in a Dart evaluation script (dart_eval field inside the Allowed Doctypes child table):

     Field Visibility Configuration

     Map<String, dynamic> FieldValidations() {
       return {
         "conditions": [
           {
             "depends_on": "Payment_Method",
             "field_type": "picklist",
             "dependent_fields": [
               {
                 "field_name": "UPI_Id",
                 "req_options": "UPI",
                 "visible_options": "UPI",
                 "required": true,
                 "visible": true,
                 "read_only": true
               },
               {
                 "field_name": "Cheque_no",
                 "req_options": "CHEQUE",
                 "visible_options": "CHEQUE",
                 "required": true,
                 "visible": true,
                 "read_only": true
               },
               {
                 "field_name": "Cheque_Information",
                 "req_options": "CHEQUE",
                 "visible_options": "CHEQUE",
                 "required": true,
                 "visible": true,
                 "read_only": true
               },
               {
                 "field_name": "Cash_UPI_NEFT_Information",
                 "req_options": "CASH,NEFT/RTGS,UPI",
                 "visible_options": "CASH,NEFT/RTGS,UPI",
                 "required": true,
                 "visible": true,
                 "read_only": true
               }
             ]
           }
         ]
       };
     }

     Explanation of Parameters

     Parameter	Description
     depends_on	The field that controls visibility (e.g., Payment_Method).
     field_type	The type of the dependent field (e.g., picklist).
     field_name	The name of the field that will be shown/hidden.
     req_options	The value(s) that trigger the field’s visibility (e.g., UPI, CHEQUE).
     visible_options	The value(s) for which the field should be visible.
     required	Specifies if the field is mandatory when visible.
     visible	Determines if the field should be displayed.
     read_only	Indicates whether the field should be editable or read-only.

     Behavior Example

     Payment Method Selected	Fields Displayed
     UPI	UPI_Id
     Cheque	Cheque_no, Cheque_Information
     Cash, NEFT/RTGS, UPI	Cash_UPI_NEFT_Information

     ---

     Form Validations on Save Button

     Use Case

     To prevent incorrect data submission, the form enforces validation rules before saving:

     • The Amount Received should not be greater than Balance Due.

     • The Payment Method cannot be set to an invalid static value ("H").

     Implementation

     The following structure defines the form validation rules applied to the Create & Edit forms(dart_eval field inside the Allowed Doctypes child table):

     Form Validation Configuration

     Map<String, dynamic> FormValidations() {
       return {
         "edit_validations": [
           {
             "key": "Form-Amount_Received",
             "operator": ">",
             "value": "Record-Balance_Due1",
             "error": "Amount {Form-Amount_Received} Can't be Greater than Balance Due {Record-Balance_Due1}"
           },
           {
             "key": "Form-Payment_Method",
             "operator": "==",
             "value": "Static-H",
             "error": "Payment Method Can't be H"
           }
         ],
         "create_validations": [
           {
             "key": "Form-Payment_Method",
             "operator": "==",
             "value": "Static-H",
             "error": "Payment Method Can't be H"
           }
         ]
       };
     }

     Explanation of Parameters

     Parameter	Description
     edit_validations	List of validation rules applied when editing a record.
     create_validations	List of validation rules applied when creating a new record.
     key	The form field being validated (e.g., Form-Amount_Received).
     operator	The condition to check (e.g., >, ==).
     value	The value to compare against (e.g., Record-Balance_Due1).
     error	The error message displayed when validation fails.

     Validation Behavior Example

     Scenario	Validation Rule	Error Message Displayed
     Amount Received = ₹5000, Balance Due = ₹4000	Amount Received > Balance Due	"Amount ₹5000 Can't be Greater than Balance Due ₹4000"
     Payment Method = "H"	Payment Method == Static-H	"Payment Method Can't be H"

     ---

     Best Practices

     • Ensure that validation rules are applied correctly for both Create and Edit operations.

     • Always provide meaningful error messages to help users correct their input.

     • Keep the structure flexible by adding new validation rules as needed.

     • You will found this code this dynamic_form.dart & edit_dynamic_form.dart

     • If You want to Static value then Define as "Static-{Your Value}"

     • If You want from Record value then Define as "Record-{Your Value}"

     • If You want from Form value then Define as "Form-{Your Value}"