Settings

It’s possible to define a settings window for your integration app where users can customize the integration flow.

To define the settings window, you need to implement the getConfiguration method in your integration configuration file.

index.js

configuration.projectIntegration.getConfiguration = (
  projectId,
  crowdinClient,
  integrationCredentials
) => {
  return [
    // Configuration Options
  ]
}

You can also specify whether to auto-reload the integration settings when the user changes them:

index.js

configuration.projectIntegration.reloadOnConfigSave = true;

Configuration Options

The configuration options are defined as an array of objects. Each object represents a single configuration option.

Label

{
  label: 'GENERAL'
}

Label HTML

{
  labelHtml: 'This is <b>labelHtml</b> <i>example</i>'
}

Checkbox

{
  key: 'flag',
  label: 'Checkbox',
  type: 'checkbox'
}

Text input

{
  key: 'text',
  label: 'Text input',
  type: 'text'
}

Select

{
  key: 'option',
  label: 'Select',
  type: 'select',
  defaultValue: '12',
  isSearchable: true,
  isMulti: true,
  options: [
    {
      value: '12',
      label: 'Option'
    }
  ]
}

Configuration options:

• isSearchable - Allow to search for option(s), default is false.
• isMulti - Allow to select multiple options, default is false.

Textarea

{
  key: 'textarea',
  label: 'Textarea',
  type: 'textarea'
}

Notice

{
  key: 'alert',
  type: 'notice',
  noticeType: 'info',
  noIcon: false,
  label: 'Some message title'
}

Help Text

You can add a help text to any field by using the helpText or helpTextHtml property:

{
  key: 'text',
  label: 'Text input',
  type: 'text',
  helpText: 'Help text',
  helpTextHtml: 'Help text <b>HTML</b>'
}

Field Dependencies

It’s possible to show or hide fields based on the value of another field. To define field dependencies, you need to use the dependencySettings property.

For example, to show the field only if the flag field is checked:

{
  key: 'text',
  label: 'Text input',
  type: 'text',
  dependencySettings: JSON.stringify([
    { '#flag': { type: 'equal', value: true } }
  ]),
}

Examples

• Alias of empty type: 'empty', 'blank'
• Alias of not empty type: '!empty', 'notEmpty', 'not-empty', 'notempty'
• Alias of equal type: 'equal', '=', '==', '==='
• Alias of not equal type: '!equal', '!=', '!==', '!===', 'notEqual', 'not-equal', 'notequal'

Show field if dependsOn field value is empty

JSON.stringify([ { 'input[name=test]': { type: 'empty' } } ])

Show field if dependsOn field value is equal to given value

JSON.stringify([ { 'input[name=test]': { type: 'equal', value: 'lorem' } } ])
JSON.stringify([ { 'input[name=test]': { type: 'equal', value: ['lorem', 'ipsum'] } } ])

normalizeSettings Function

This method allows you to modify saved integration settings without needing to migrate the database. You can change existing settings, such as altering field types or adjusting values based on other parameters.

index.js

configuration.projectIntegration = {
  getConfiguration: (projectId, crowdinClient, integrationCredentials) => {
    return [
      /*
      {
        key: 'publish',
        label: 'Set Publish Status',
        type: 'checkbox',
      },
      */
      {
        key: 'publishStatus',
        label: 'Set Publish Status',
        type: 'select',
        defaultValue: 'draft',
        options: [
          {
            value: 'draft',
            label: 'Draft',
          },
          {
            value: 'publish',
            label: 'Publish',
          },
          {
            value: 'match',
            label: 'Match Source',
          },
        ],
      }
    ];
  },
  normalizeSettings: ({ appSettings, apiCredentials, client }) => {
    if (appSettings?.publish === true) {
      appSettings.publishStatus = 'publish';
    }
    return appSettings;
  },
};

Validate settings

You can validate settings before they are saved by implementing the validateSettings method in your projectIntegration configuration. This method allows you to check if the provided settings are valid and return appropriate error messages.

index.js

configuration.projectIntegration.validateSettings = ({ client, credentials, appSettings }) => {
  const errors = {};

  if (appSettings.string_keys) {
    const keys = appSettings.string_keys.split(',').map(key => key.trim());
    const hasInvalidKey = keys.some(key => /\s/.test(key));

    if (hasInvalidKey) {
      errors.string_keys = 'String keys cannot contain spaces. Example of valid keys: postBody,body,html,title,foobar';
    }
  }

  // Return validation errors as key-value pairs where key is the field name and value is the error message
  return Object.keys(errors).length ? errors : null;
};