# Layouts As a plugin developer, you customize the new/edit plugin instance screens with a layout JSON file. You can group properties into categories and choose the type of field representing each of them. A plugin layout is bound to a [plugin version](https://developer.mediarithmics.io/advanced-usages/plugins/..#versions). It is optional, except for [audience segment feeds](https://developer.mediarithmics.io/advanced-usages/audiences/audience-segment-feed). A default layout is used to show all properties of a plugin version (Note that there is no layout file associated with this default layout). A plugin layout is composed of: 1. A layout JSON file 2. A non-empty list of translation CSV files ## Layout JSON file This file declares the different elements of the configuration UI. ![](https://4196284719-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MMuoqM-5hJ5JY0WnAKL%2F-MP4mc6Gy9qEFRtrpQBx%2F-MP4oqvFfQ3IfhgoLSUi%2Fimage.png?alt=media\&token=9bf42e72-502e-49a6-8207-ccfde6b81096) This file is composed of the version, the [sections](#sections) to display and the [metadata](#metadata). ### Example ```json { "version": "V202005", "sections": [ { "title": "{{section_title}}", "sub_title": "{{section_subtitle}}", "fields": [ { "property_technical_name": "property_1", "field_type": "INPUT", "label": "{{property_1_label}}", "tooltip": "{{property_1_tooltip}}", "placeholder": "{{property_1_placeholder}}", "required": true }, { "property_technical_name": "property_2", "field_type": "DYNAMIC_SELECT", "label": "{{property_2_label}}", "tooltip": "{{property_2_tooltip}}", "placeholder": "{{property_2_placeholder}}", "enum": null, "required": true }, { "property_technical_name": "property_3", "field_type": "MULTI_SELECT", "label": "{{property_3_label}}", "tooltip": "{{property_3_tooltip}}", "placeholder": "{{property_3_placeholder}}", "enum": [ { "value": "category_1", "label": "{{CAT_1_label}}" }, { "value": "category_2", "label": "{{CAT_2_label}}" }, { "value": "category_3", "label": "{{CAT_3_label}}" } ], "required": true } ], "advanced_fields": [ { "property_technical_name": "segment_name", "field_type": "INPUT", "label": "{{segment_name_label}}", "tooltip": "{{segment_name_tooltip}}", "placeholder": "{{segment_name_placeholder}}", "required": false }, { "property_technical_name": "segment_description", "field_type": "INPUT", "label": "{{segment_description_label}}", "tooltip": "{{segment_description_tooltip}}", "required": false }, { "property_technical_name": "customer_user_identifier", "field_type": "INPUT", "label": "{{customer_user_identifier_label}}", "tooltip": "{{customer_user_identifier_tooltip}}", "required": false }, { "property_technical_name": "continent", "field_type": "SELECT", "label": "{{continent_label}}", "tooltip": "{{continent_tooltip}}", "enum": [ { "value": "NAM", "label": "NAM" }, { "value": "EMEA", "label": "EMEA" }, { "value": "APAC", "label": "APAC" } ], "required": false } ] } ], "metadata": { "large_icon_asset_id": "13636", "small_icon_asset_id": "13636", "display_name": "{{section_title}", "description": "{{section_subtitle}}" } } ``` ### Schema validation
Here is the JSON schema. You can validate your files with it in your favorite JSON validation tool. ```javascript { "$schema": "http://json-schema.org/schema#", "definitions": { "PluginLayoutMetadataResource": { "type": "object", "properties": { "large_icon_asset_id": {"type": "string"}, "small_icon_asset_id": {"type": "string"}, "large_icon_asset_url": {"type": ["string", "null"]}, "small_icon_asset_url": {"type": ["string", "null"]}, "tooltip": {"type": ["string", "null"]}, "display_name": {"type": "string"}, "description": {"type": "string"} }, "required": ["large_icon_asset_id", "small_icon_asset_id", "display_name", "description"] }, "PluginLayoutEnumResource": { "type": "object", "properties": { "value": {"type": "string"}, "label": {"type": "string"} }, "required": ["value", "label"] }, "PluginLayoutFieldResource": { "type": "object", "properties": { "property_technical_name": {"type": "string"}, "field_type": {"type": "string"}, "label": {"type": "string"}, "tooltip": {"type": ["string", "null"]}, "enum": {"type": ["array", "null"], "items": { "$ref": "#/definitions/PluginLayoutEnumResource" } }, "max_length": {"type": ["integer", "null"]}, "required": {"type": ["boolean", "null"]} }, "required": ["property_technical_name", "field_type", "label"] }, "PluginLayoutSectionResource": { "type": "object", "properties": { "title": {"type": "string"}, "sub_title": {"type": "string"}, "fields": {"type": "array", "items": { "$ref": "#/definitions/PluginLayoutFieldResource" } }, "advanced_fields": {"type": "array", "items": { "$ref": "#/definitions/PluginLayoutFieldResource" } } }, "required": ["title", "sub_title", "fields", "advanced_fields"] } }, "type": "object", "properties": { "version": {"type": "string"}, "sections": {"type": "array", "items": { "$ref": "#/definitions/PluginLayoutSectionResource" } }, "metadata": {"$ref": "#/definitions/PluginLayoutMetadataResource"} }, "required": ["version", "sections", "metadata"] } ```
#### Root | Attribute | Type | Description | | --------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version | a string | the version of the layout | | sections | a list of [Sections](#sections) | it defines the form's sections (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#sectionDefinition)) | | metadata | a [Metadata](#metadata-resource-type) resource | it defines metadata concerning the form (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#metadataDefinition)) | #### Sections You can display multiple sections, each composed of multiple fields and an advanced field section. | Attribute | Type | Description | | ---------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | title | a string | the section title | | sub\_title | a string | the section subtitle | | fields | a list of [Fields](#fields) | it defines the fields of the section (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#fieldDefinition)) | | advanced\_fields | a list of [Fields](#fields) | it defines the advanced fields of the section, which can be graphically expanded or not (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#fieldDefinition)) | #### Fields | Attribute | Type | Description | | ------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | property\_technical\_name | a string | the technical name of the property represented by the field | | field\_type | a field type string enum | the type of the input form field (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#fieldTypeDefinition)) | | label | a string | the label preceding the field type, on its left in the form | | placeholder | a string |

the placeholder displayed in an empty form field that hints at the expected format or an example value
(displayed only for TEXTAREA and any \*SELECT input types)
(if no placeholder is provided, the technical\_name is used in PascalCase)

| | tooltip | a string (**optional**) | the help text displayed in the tooltip following the field type, on its right in the form | | enum | a list of [Enum](#enum-resource-type) resources (**optional**) | an enum describing the possible values of the field (used by some field types : SELECT, MULTI\_SELECT, SWITCH, RADIO, CHECKBOX) (see below for the [Definition](https://developer.mediarithmics.com/guides/plugins/plugin-layout/#enumDefinition)) | | max\_length | an integer (**optional**) | a maximum length of the text in the field type; used only in the case TEXTAREA | | required | a boolean (**optional**) | it defines whether the field is mandatory or not; if the value is not specified, then it isn't (the default value is false) | The possible **field types** are the following: * TEXTAREA * URL * DATA\_FILE * HTML * NUMBER * SELECT * MULTI\_SELECT * DYNAMIC\_SELECT (requires the [corresponding dynamic property to be developed in the plugin code](https://developer.mediarithmics.io/advanced-usages/plugins/creation/audience-segment-external-feed-methods?q=dynamic+properties#dynamic-properties)) * IMAGE * INPUT * INPUT\_NUMBER * SWITCH * RADIO * CHECKBOX * DATE * DATE\_RANGE ### Field format #### Enum | Attribute | Type | Description | | --------- | -------- | ------------------------------------------------------------- | | value | a string | the value of the enum, which will be affected to the property | | label | a string | the label of the enum, which will be displayed in the field | #### Metadata | Attribute | Type | Description | | ---------------------- | ---------- | ------------------------------------------------------------------------------------- | | large\_icon\_asset\_id | an integer | the asset id of the large icon representing the plugin layout | | small\_icon\_asset\_id | an integer | the asset id of the small icon representing the plugin layout | | display\_name | a string | the plugin version's name (visible in the plugin listing and the form page) | | description | a string | a description of the plugin version (visible in the plugin listing and the form page) | Note that the assets must belong to the same organisation than the plugin. ## Translation files Translation csv files are used to support localization. Given a layout json file, for each locale, a translation csv file can be provided. The plugin developer can refer to a value in the layout json file by surrounding the value name with double curly brackets (hence, referring to value val is done with `{{val}}` in the json file). Those values can be found anywhere in the layout json file. For example, an excerpt of a layout json file, referring to the value val when defining a label in a field, looks like: ``` { "property_technical_name":"name", "field_type":"TEXTAREA", "label":"{{val}}" } ``` \ A translation csv is composed of two comma-separated columns. The header of the table is KEY,VALUE. The first column corresponds to the keys, i.e the names of the values (val in the preceding example). The second column corresponds to the values by which the keys will be replaced when the layout is displayed in Navigator. Considering the previous excerpt of a layout json file, a (brief) corresponding US English (en-US locale) translation csv file could be: ``` KEY,VALUE val,"Hello World!" ```
Here is a sample translation file associated with the sample layout.json file in this page ```bbcode KEY,VALUE section_title,"Beeswax Audience Feed" section_subtitle,"Synchronize audiences with Beeswax" buzz_key_label,"Buzz key" buzz_key_tooltip,"Your buzz key as provided by Beeswax. Warning : valid credentials should be set into mediarithmics for this buzz key. If an authentication error is displayed when saving, contact your account manager." identifiers_to_send_label,"Types of user identifiers sent" identifiers_to_send_tooltip,"" BEESWAX_label,"Cookie ids" CUSTOMER_label,"Customer ids" IDFA_label,"IOS ids" AD_ID_label,"Android ids" segment_name_label,"Segment name" segment_name_tooltip,"The name of the segment that will be populated in Beeswax. Default to mediarithmics segment name." segment_description_label,"Segment description" segment_description_tooltip,"The description of the segment that will be populated in Beeswax. Default to mediarithmics segment description." advertiser_id_label,"Advertiser ID", advertiser_id_tooltip,"If segment should not belong to the overall beeswax account but to a specific advertiser, please enter its ID.", customer_user_identifier_label,"Customer identifier" customer_user_identifier_tooltip,"Path to the customer identifier property when sending customer ids. Examples : USER_EMAIL:hash | USER_AGENT:mappings[0].user_agent_id" continent_label,"Continent" continent_tooltip,"The destination continent data centers to upload the data. Only one continent may be specified per upload." ```
## Managing layouts ## Get a layout In the computing console, choose your plugin, select a plugin version, and open the section Layout in the menu. You should get at least two files in the list, the properties layout and the en-US translation. Click on the file options and select Edit to display the content. If you don't have those files, you can create them by clicking on *Add a properties layout* and *Add a local* to create a translation. You can also use our API to manage your layouts: `GET` `https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout` Retrieves the already uploaded layout JSON file for a plugin version. You can retrieve the layout.json file with translation tokens or with translation values. #### Path Parameters | Name | Type | Description | | ----------- | ------- | --------------------- | | plugin\_id | integer | The ID of the plugin | | version\_id | integer | The ID of the version | #### Query Parameters | Name | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------------------ | | locale | string |

Replaces all translation tokens with values in the specified locale
Example: locale=en-US

| ## Upload a layout `PUT` `https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout` Updates the layout JSON file for a plugin version #### Path Parameters | Name | Type | Description | | ----------- | ------- | --------------------- | | plugin\_id | integer | The ID of the plugin | | version\_id | integer | The ID of the version | #### Request Body | Name | Type | Description | | ---- | ------ | ---------------------------- | | body | string | The layout.json file content | In case of `JSON not structured as expected` error, you can use [Schema](#schema) to validate your file. ## Get a translation file `GET` `https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=:locale` Retrieves the translation file of a plugin version in the specified locale #### Path Parameters | Name | Type | Description | | ----------- | ------- | --------------------------------------------- | | locale | string | The locale in which to retrieve the CSV file. | | plugin\_id | integer | The ID of the plugin. | | version\_id | string | The ID of the version. | ## Upload a translation file `PUT` `https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=en-US` Retrieves the translation file of a plugin version in the specified locale #### Path Parameters | Name | Type | Description | | ----------- | ------- | --------------------------------------------- | | locale | string | The locale in which to retrieve the CSV file. | | plugin\_id | integer | The ID of the plugin | | version\_id | integer | The ID of the version | #### Request Body | Name | Type | Description | | ---- | ------ | ----------------------- | | body | string | The content of the file |