CustomFieldContextConfig

The CustomFieldContextConfig component is returned from a function defined in the contextConfig property in the app manifest. When the component is returned, a view of the custom field type configuration details for a context are rendered.

This component can be used in Jira Work Management, Jira Software, and Jira Service Management to render a configured view of the field in a custom field context.

Usage

1
2
import ForgeUI, { CustomFieldContextConfig } from "@forge/ui";

Props

Name	Type	Required	Description
`children`	`Array<ForgeComponent>`	Yes	A container for displaying multiple components. Can contain any component except for `Form`, `ConfigForm`, `MacroConfig`, and all extension-specific components.
`onSubmit`	`(formData: FormData) => Promise<any> \| any`	Yes	An event handler that can be asynchronous. The argument, `formData`, is an object of input field keys and their values (see the following example). The return value is either an object which can contain the field configuration and schema (only for custom field object type) or a promise that’s resolved with the returned object.

Object type

Object type custom fields can have the schema property in the return object of the onSubmit method. The schema property contains the JSON schema that is used to validate values stored in the field. Here is an example:

1
2
const onSubmit = (formData) => ({
  schema: {
    properties: {
        value: formData.value,
        currency: formData.currency
    }
  }
});

Example

This example shows how configuration details defining the maximum and minimum values for a slider component type can be retrieved, displayed, and saved. The example uses the useProductContext hook to extract the extensionContext that stores the configuration. Any modified configuration is then saved with the onSubmit method of the component.

1
2
import ForgeUI, {
  render,
  useProductContext,
  CustomFieldContextConfig,
  TextField,
} from "@forge/ui";

const ContextConfig = () => {
  const {extensionContext: {configuration = {}}} = useProductContext();
  
  const onSubmit = (formData) => ({
      configuration: {
          minValue: +formData.minValue || 0, 
          maxValue: +formData.maxValue || 100,
      }
  });

  return (
    <CustomFieldContextConfig onSubmit={onSubmit}>
      <TextField name="minValue" label="Minimum value" defaultValue={configuration.minValue}/>
      <TextField name="maxValue" label="Maximum value" defaultValue={configuration.maxValue}/>
    </CustomFieldContextConfig>
  );
};

export const runContextConfig = render(<ContextConfig />);

Preview

This screenshot shows the slider component's custom field context configuration page in edit mode.

Example of a custom field type context configuration page in edit mode, based on the preceding example code.