App parameters

Table of contents

• What are parameters?
• Parameter definition
• Installation parameters
  • Installation parameters use
  • Installation parameter definition
• Instance parameters
  • Instance parameters use
  • Instance parameter definition
• Set and read parameter values

What are parameters?

It's important to achieve separation of the code that forms your custom app and the configuration that is used by it. This way it can be shared, reused and reconfigured without any code changes.

Below are some examples of the use cases for parameters:

• Default values.
• Project, category or entity identifiers when loading data from external APIs.
• Slack channel name to post messages to.
• Content types to process (e.g. for publishing content trees).
• Kinds of validation to apply.

There are the following types of configuration parameters that can be set up:

• Installation parameters — Are set during installation in a space environment and which can be modified in subsequent configuration updates. Their values are available across all usages of the app in the environment.
• Instance parameters — Are set when a space member with access to the content model assigns an app to a location. Values provided are available only in the specific location and content type where they were entered.

Parameter definition

Parameter definition is an object constructed as described in the table below.

Installation parameters

Installation parameters use

Installation parameters are set during the installation of an app in an environment and can be modified in subsequent configuration updates. Their values are available across all locations of the app in the environment.

Installation parameters are used to customize an app depending on the environment it is installed in. Installation parameters are commonly used to set default values, to reference content types, or to configure the interaction of the app with third party services.

Installation parameter definition

Installation parameters are a free-form object, with a limit of 32kB, and don't have to be defined.

Instance parameters

Instance parameters use

Instance parameters can be used to access user-provided values inside of app code. They are configurable per field where the app is installed.

For instance parameters to be used in an app, the following prerequisites must be met:

1. Developers must enable the use of instance parameters by configuring the AppDefinition to define what types of values are to be expected.
2. Users configuring the app must provide the values of these parameters.

To give an example of how instance parameters work, let’s take a look at a list item app that is built to have the name of the list change based on what a user sets for that field. In the screenshot below, we are updating the content model for a specific content type. In this content type, the "List" field has an app called "List App" which is being used as the appearance. Instance parameters show up below the selected app and allow the user to input a custom value, in this case, the name of a list.

To learn more about using instance parameters, watch our video on how instance parameters can be set up for a simple app.

Instance parameter definition

Up to 8 instance parameters can be defined as a part the AppDefinition entity:

{
    "name": "My parametrized editor app",
    "src": "https://myeditor.contentful.com",
    "locations": [{"location": "entry-editor"}],
    "parameters": {
      "instance": [
        {
          "id": "helpText",
          "type": "Symbol",
          "name": "Help text",
          "description": "Help text for a user to help them understand the editor"
        },
        {
          "id": "theme",
          "type": "Enum",
          "name": "Theme",
          "options": [{"light": "Solarized light"}, {"dark": "Solarized dark"}],
          "default": "light",
          "required": true
        }
      ]
    }
}

You can define instance parameters for your app when editing the AppDefinition in the web app:

Set and read parameter values

Instance parameters are set in the Editor Interface entity. Installation parameters are provided as a top-level parameters property of the Extension entity:

{
  "parameters": {
    "devMode": true,
    "retries": 10
  }
}

Values, for both instance and installation parameters, can be read with the App SDK:

init((sdk) => {
  console.log(sdk.parameters.instance);
  console.log(sdk.parameters.installation);
});