Custom Modules

Custom Modules in Zoho Products allow developers to extend the application data model by defining new entities tailored to specific business needs. From an SDK perspective, custom modules behave like first-class modules and can be accessed, manipulated, and extended using widgets.

Note:

Custom module widget locations and event names are dynamic and differ from standard modules.The placeholder name custommodule_api_name used in locations and events must be replaced with your actual custom module API name.

For example, if your custom module API name is cm_bookings:

Widget locations:

• cm_bookings.list.sidebar
• cm_bookings.details.sidebar

Event names:

• ON_cm_bookings_PRE_SAVE
• ON_cm_bookings_PREVIEW

Note:

Always replace the custommodule_api_name name in widget locations and event identifiers with your own custom module’s API name.

Methods

Methods

Get Custommodule Details

Retrieves data related to the current context. This method allows your widget to fetch record details, field values, or metadata required for rendering or processing logic.

Commonly used for :

• Fetch record information
• Read field values
• Access contextual module data

Supported Locations :

`custommodule_api_name`.creation.sidebar`custommodule_api_name`.details.sidebar`custommodule_api_name`.details.button

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('${{custommodule_api_name}}').then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
module_record_id	custommodule_api_name.module_record_id
created_time	custommodule_api_name.created_time
last_modified_time	custommodule_api_name.last_modified_time
record_name	custommodule_api_name.record_name
record_name_formatted	custommodule_api_name.record_name_formatted

Set Custommodule Details

Updates or sets data within the current context. This method allows your widget to modify field values, update state, or pass data back to the host application.

Commonly used for :

• Update field values
• Set widget or module state
• Pass data to the parent application

Supported Locations :

`custommodule_api_name`.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('${{custommodule_api_name}}.name', <value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
module_record_id	custommodule_api_name.module_record_id
created_time	custommodule_api_name.created_time
last_modified_time	custommodule_api_name.last_modified_time
record_name	custommodule_api_name.record_name
record_name_formatted	custommodule_api_name.record_name_formatted

Set Custommodule customfields

Specifically designed to update custom field values within the current context. This method allows your widget to target and modify custom fields without affecting standard fields, ensuring precise data management.

Commonly used for :

• Update custom field values
• Manage user-defined data points
• Ensure targeted updates to specific fields

Supported Locations :

`custommodule_api_name`.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('${{custommodule_api_name}}.<custom_field_api_name>',<value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Events

Events

ON_CUSTOMMODULE_API_NAME_PRE_SAVE

This event is triggered just before the custommodule record is saved in your organization. It allows your widget to validate data, modify field values, or perform custom checks before the save operation is completed.

Supported Locations :

`custommodule_api_name`.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_CUSTOMMODULE_PRE_SAVE').then(async function() {

    var record = await ZFAPPS.get('custommodule');
    record = record?.['custom_fields'];

    if (record.cf_approval_required && !record.cf_approval_notes) {

      await ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'Approval notes are required when Approval Required is selected.'
      });

      return {
        prevent_save: true
      };
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_CUSTOMMODULE_API_NAME_PREVIEW

This event is triggered when the preview of a custommodule record is opened in your organization. It allows your widget to access record data and render contextual information during the preview phase.

Supported Locations :

`custommodule_api_name`.details.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_CUSTOMMODULE_PREVIEW').then(async function() {

    var record = await ZFAPPS.get('custommodule');
    record = record?.['custom_fields'];

    if (record.cf_priority_level === 'High') {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'This record is marked as High Priority.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_CUSTOMMODULE_API_NAME_CHANGE

This event is triggered whenever a supported field value is changed within the custommodule form. The event is fired based on the configured supported keys, allowing your widget to react dynamically to user input.

Supported Locations :

`custommodule_api_name`.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_CUSTOMMODULE_CHANGE').then(async function() {

    var record = await ZFAPPS.get('custommodule');
    record = record?.['custom_fields'];

    if (record.cf_special_flag) {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'success',
        message: 'Special option selected. Please review additional details before saving.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});