Let's get started on combining the schema for your modal. The main gist is that the Embedded action consists of a modal combined from components which are Blocks and Action buttons.
On this page, we'll cover all Block types, how to add the Blocks, and possible relationships between different Blocks that can be used for the embedded app actions.
You can see how all Block types and Action buttons will look like when added to the modal in the following image.
The structure of the modal
Blocks are smaller UI elements that can be customized for your app and its use cases. The Blocks are displayed inside the modal component, and each modal can have a maximum of 10 Blocks. In the limitation of 10, the primary and secondary Action buttons, as well as the modal header, are not included.
To combine the modal from Blocks and define its behavior, you'll need to add a JSON schema to Marketplace Manager. For the whole schema structure, see Embedded app actions.
To add a Block to the modal, first, you'll need to add the appropriate Block key and type. Block key should be unique to the Block and it'll be used to map out all relationships between Blocks and requests' data payloads. Block type needs to be added to the schema as $ref property from the list of available definitions:
#/definitions/element-text#/definitions/element-input#/definitions/element-select#/definitions/element-datepicker#/definitions/element-radio-group#/definitions/element-checkbox-group#/definitions/element-separator#/definitions/element-textarea
This is how your modal will look like with just one input block defined where the block key is "block_key_1" and it is followed by the block type "$ref": "#/definitions/element-input":
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_1":{
"$ref":"#/definitions/element-input",
"options":{
"type":"text",
"placeholder":"Name",
"label":"Name",
"value":"John",
"allowClear":true,
"isRequired":true,
"visibleOn":{
"block_key_2":{
"equals":"task"
}
}
}
}
}
}
}
}Commonly available options for the block
visibleOn
This option allows the modal to change its appearance - layout and default values of Blocks - depending on the choice a user has made with one Block. visibleOn option is available for all Blocks except the separator Block. visibleOn can control the visibility of a Block depending on another item’s value or the visibility of a whole Block. visibleOn can be added to the options of a Block, the item of a Block and Action buttons.
When visibleOn is added to be dependent on item values inside other Blocks, it supports 3 rules: not_empty, equals, and includes. These rules have to be used together with the Block key, where the rule has to be applied. For example, when visibleOn is added to an Input Block with the following criteria seen in the code sample below, the Input Block will become visible only when the "block_key_checkbox" value is exactly equal to "vanilla".
"block_key": "not_empty"expects any value in a Block, available for Blocks requiring inputs."block_key": {"equals": "on"}expects very specific value on to be selected, available for Blocks with toggle items."block_key": {"includes": "example"}expects text and inputs in Block value to contain a certain text.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_checkbox":{
"$ref":"#/definitions/element-checkbox-group",
"options":{
"label":"Flavors",
"value":[
"vanilla"
],
"items":[
{
"value":"vanilla",
"label":"Vanilla"
},
{
"value":"chocolate",
"label":"Chocolate"
}
]
}
},
"block_key_input":{
"$ref":"#/definitions/element-input",
"options":{
"type":"text",
"placeholder":"Insert size",
"label":"Cake size",
"value":"S",
"allowClear":true,
"isRequired":true,
"visibleOn":{
"block_key_checkbox":{
"equals":"vanilla"
}
}
}
}
}
}
}
}visibleOn supports two extra rules for when there is a need to control the entire visibility of the entire Block. These rules specify if the Block should never be visible to the user or is always visible to the user. The Block’s value will be sent on action data submission after the click on Action button.
visibleOn: “never“ - the never rule can be used to hide a Block from the modal.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_input":{
"$ref":"#/definitions/element-input",
"options":{
"label":"Hidden",
"value":"my hidden value",
"visibleOn":"never"
}
}
}
}
}
}visibleOn: “always“ - the always rule can be used in case there is a need to reset previously set rules. In this sample, the Input Block will be displayed only when the Radio Block’s value is equal to yes.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_input":{
"$ref":"#/definitions/element-input",
"options":{
"label":"Visible",
"value":"some visiblity value",
"visibleOn":{
"block_key_radio":{
"equals":"yes"
}
}
}
},
"block_key_radio":{
"$ref":"#/definitions/element-radio-group",
"options":{
"label":"Wrap as a gift?",
"value":"wrapping",
"items":[
{
"value":"yes",
"label":"Yes"
},
{
"value":"no",
"label":"No"
}
]
}
}
}
}
}
}Response from the API endpoint
Allows overriding set values in the schema with the data in the response structure.
{
"data":{
"blocks":{
"block_key_input":{
"visibleOn":"always"
}
},
"actions":{
}
}
}fetchOnChange
This option allows the modal to re-fetch data when the user has made a choice or an action. In general fetchOnChange is useful when a base value change needs to accommodate different values (or any other Block options) in other Blocks. fetchOnChange option is available for all Blocks, except the Text Block and Separator Block and can be added to Block together with other options.
In this example, when the date field’s value is changed, only one value for the delivery is provided.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_datepicker":{
"$ref":"#/definitions/element-datepicker",
"options":{
"label":"Delivery date",
"value":"2021-03-17",
"message":"Cakes will be ready by 12:00 on selected date",
"placeholder":"Date",
"allowClear":true,
"isRequired":true,
"fetchOnChange":true
}
},
"block_key_select":{
"$ref":"#/definitions/element-select",
"options":{
"label":"Delivery method",
"message":"Please, specify how the delivery will be done.",
"placeholder":"Select method",
"isRequired":true
}
}
}
}
}
}Response from the API endpoint
The response sets what value of the Select Block will be available for the set date by changing the available item options. The response can also be the same as for the initial request.
{
"data":{
"blocks":{
"block_key_select":{
"items":[
{
"label":"Standard",
"value":1
}
]
}
},
"actions":{
}
}
}After the user changes the value in the Datepicker Block, it will make the same request as the initial request to fetch data for action. And it will include additional query params:
formserialized JSON with current form stateinvokerkey of changed block
This is how the URL will look like when additional parameters are added:https://example.org?resource=deal&view=details&...&form=%7B%22block?key?select%22%3A%22label%22%2C%22standard%22%3value%221%22%7D&invoker=datepicker
Text
Text Block allows displaying contextual messages or explanations inside the modal.
Options for adding a Text Block:
value
REQUIRED
string
Thank you for using the cake ordering app!
markdown
boolean
Supported markdown types:heading (# text),paragraph,strong (** text **),link ([text](url)),blockquote ( > text),list (1. text),bullets (-)
For the heading type, only one format of headings is supported. All other formats will be displayed the same way.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_text":{
"$ref":"#/definitions/element-text",
"options":{
"markdown":true,
"value":"# Contact info \n For any other info regarding **your order** contact us through our [website](https://cake-demo-app.vercel.app/).\nOur help desk is working: \n 1. Monday - Friday 9am-4pm \n 2. Saturdays 10am-2pm \n\nOur stores are in: \n - Siberia\n - Malibu beach \n > Enjoy your cake!"
}
}
}
}
}
}
Input Block with an error message
Input Block with a set value
Options for adding an Input Block:
label
REQUIRED
string
Label is displayed above the input field. It should be used to specify what type of input is expected to be inserted by the user.
Cake size
type
string
The type of the input that should be added by the user.
Type needs to be one of "text", "email", "number", "password", "search", "url")
password formats user input in a hidden bulleted list.
search allows user to enter search queries into. These fields are functionally identical to text inputs, but are styled differently.
URL requires a URL as the value of the input.
value
string
The value displayed in the input box. Can be either set as a default value by the app or a new one added by the user.
M
placeholder
string
The placeholder text displayed when no input value has been added
Insert size
message
string
An additional message placed below the input in a text format.
Cake size can be either S, L or M.
allowClear
boolean
Allows clearing the input. To clear the input field, the user will have to click the "x" at the end of the input box.
true, false
isRequired
boolean
Makes the field mandatory to be filled by the user.
true, false
Input Block can also display an error message when the data inserted by the user doesn't match a set criteria. See the expected error page on how to set this up.
Example schema for the Input Block
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_input":{
"$ref":"#/definitions/element-input",
"options":{
"type":"text",
"placeholder":"Insert size",
"label":"Cake size",
"value":"M",
"message":"Cake size can be either S, M or L",
"allowClear":true,
"isRequired":true
}
}
}
}
}
}Select
Select Block can be used to show the user multiple options from a dropdown list from which they can choose one item.
Options for adding a Select Block:
label
REQUIRED
string
Label is displayed above the Select Block's options. It should be used to specify what the user is selecting.
Delivery method
value
string/boolean/number or array of string/boolean/number
Value can be used to set an already chosen default item or a value chosen by the user.
Dependent on the chosen type.
message
string
An additional guiding message in a text format.
Please, specify how the delivery will be done.
placeholder
string
The placeholder text displayed when no input value has been added
Select method
allowClear
boolean
Allows clearing the selected option. To clear the field, the user will have to click the "x" at the end of the input box.
true, false
isRequired
boolean
Makes the field mandatory to be filled by the user.
true, false
filter
boolean
Allows to filter available items in the dropdown by term.
true, false
items
array of objects
See the following table
See the following table
Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.
label
REQUIRED
string
The naming of the item.
Standard
value
REQUIRED
string/boolean/number
Uniquely set value for an item.
Dependent on the chosen type.
isDisabled
boolean
Disables the item from being selected.
true, false
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_select":{
"$ref":"#/definitions/element-select",
"options":{
"label":"Delivery method",
"message":"Please, specify how the delivery will be done.",
"placeholder":"Select method",
"isRequired":true,
"items":[
{
"label":"Standard",
"value":1
},
{
"label":"Accelerated",
"value":2
}
]
}
}
}
}
}
}DatePicker
DatePicker allows users to select a set date from the calendar view.
Options for adding a DatePicker Block:
label
REQUIRED
string
Label is displayed above the Datepicker Block. It should be used to specify what date should be selected.
Delivery date
value
string
The value of the datepicker. It can be sent as a default date or the one selected by the user.
The format should be YYYY-MM-DD
Example: 2021-02-17
message
string
An additional guiding message in a text format.
Cakes will be ready by 12:00 on the selected date.
error
string
An error message displayed under the Datepicker box. See Expected error handling on how to set it up.
Please select a non-holiday date.
allowClear
boolean
Allows clearing the selected date. To clear the box, the user will have to click the "x" at the end of the box.
true, false
isRequired
boolean
Makes the field mandatory to be filled by the user.
true, false
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_datepicker":{
"$ref":"#/definitions/element-datepicker",
"options":{
"label":"Delivery date",
"value":"2021-02-17",
"message":"Cakes will be ready by 12:00 on selected date",
"placeholder":"Date",
"allowClear":true,
"isRequired":true
}
}
}
}
}
}Radio Group
Allows selecting one item from a displayed bulleted list.
Options for adding a Radio Group Block:
label
REQUIRED
string
Label is displayed above the Radio Group Block. It should be used to specify what should be selected by the user.
Wrap as a gift?
value
string
The value of the radio group.
yes
items
array of objects
See the following table
See the following table
isRequired
boolean
Makes the field mandatory to be filled by the user.
true,false
message
string
An additional guiding message in a text format.
error
string
An error message displayed under the radio group box. See Expected errors on how to set it up.
Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.
label
REQUIRED
string
The naming of the item.
Yes, No
value
REQUIRED
string
Uniquely set value for an item.
Dependent on the chosen type.
isDisabled
boolean
Disables the item from being selected.
true, false
Example schema for Radio Group Block
In this example, we have also shown how to add the visibleOn common option. In this case, the Radio group Block will not display the maybe option item to the user as they have previously selected the cake to be a vanilla cake, as the fictional store we use doesn't offer gift wrapping for cakes made of vanilla (let's go with this for the sake of the example, in the real world, it'd be awesome if all cakes could always be wrapped as gifts!).
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_radio":{
"$ref":"#/definitions/element-radio-group",
"options":{
"label":"Wrap as a gift?",
"value":"wrapping",
"items":[
{
"value":"yes",
"label":"Yes"
},
{
"value":"no",
"label":"No"
},
{
"value":"hidden",
"label":"Maybe",
"visibleOn":{
"block_key_checkbox":{
"equals":"vanilla"
}
}
}
]
}
}
}
}
}
}Checkbox Group
Blue checkboxes allow selecting items in a list view. All items or none can also be selected.
Options for adding a Checkbox Group Block:
label
string
The label is displayed above the Checkbox Group Block. It should be used to specify what should be selected by the user.
Flavors
value
array of string
The value of the Checkbox group.
items
array of objects
See the following table
See the following table
isRequired
boolean
Makes the field mandatory to be filled by the user.
true, false
message
string
An additional guiding message in a text format.
Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.
label
REQUIRED
string
The naming of the item.
Vanilla
value
REQUIRED
array of string
Uniquely set value for an item.
Dependent on the chosen type.
isDisabled
boolean
Disables the item from being selected.
true, false
Example schema for the Checkbox Group Block
In this example, we provide three items to be selected in the Checkbox Group Block. From those three, the possibility to choose the chocolate-flavored cake is disabled. If the input, aka the cake size in this example, includes "L", the checkbox option item hidden_option value will be hidden.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_checkbox":{
"$ref":"#/definitions/element-checkbox-group",
"options":{
"label":"Flavors",
"value":[
"cranberry"
],
"items":[
{
"value":"vanilla",
"label":"Vanilla"
},
{
"value":"chocolate",
"label":"Chocolate",
"isDisabled":true
},
{
"value":"cranberry",
"label":"Cranberry"
},
{
"value":"hidden_option",
"label":"Not visible",
"visibleOn":{
"block_key_input":{
"includes":"L"
}
}
}
]
}
}
}
}
}
}Separator
Separator Block allows displaying a thin grey line between other Blocks to visually separate the modal into sections.
For adding the Separator Block, add the following code to your schema (for a larger schema, start from the "type" parameter that is after the "blocks" parameter).
Example schema for the Separator Block
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_separator":{
"$ref":"#/definitions/element-separator"
}
}
}
}
}Textarea
Allows adding a text area for larger comments and texts.
Options for adding a Textarea Block:
label
REQUIRED
string
Label is displayed above the Textarea box. It should be used to specify what type of input is expected to be inserted by the user.
Additional instructions
value
string
The value displayed in the textarea box.
placeholder
string
The placeholder text displayed when no text has been added. This can be used to give a hint to users on what info they need to add.
Write "Happy birthday!" on the cake
message
string
An additional message placed below the textarea box in a text format.
What would you like to have on your cake?
resize
boolean
Allows to resize the Textarea field.
true, false
isRequired
boolean
Makes the field mandatory to be filled by the user.
true, false
error
string
An error message displayed under the textarea. See Expected errors on how to set it up.
An error message displayed under the textarea. See Expected errors on how to set it up.
{
"type":"object",
"properties":{
"blocks":{
"type":"object",
"properties":{
"block_key_textarea":{
"$ref":"#/definitions/element-textarea",
"options":{
"placeholder":"Write Happy birthday! on the cake",
"label":"Additional instructions",
"value":"Long text",
"message":"What would you like to have on your cake?",
"resize":true,
"isRequired":true
}
}
}
}
}
}Action buttons are displayed in the modal footer of an Embedded app action. They are clickable and will trigger saving, resetting, or cancellations of the modal. Each modal has to have a minimum of one and a maximum of two action buttons. Available action buttons have two types - primary and secondary actions. The primary action will be displayed as a green UI button and secondary as a grey UI button.
Adding an action button is similar to adding a Block. First, you'll need to add the action key and action type as a $ref property from the following two:
#/definitions/action-primary#/definitions/action-secondary
Primary Action button
The primary action button will be activated once all required Blocks are filled and depending on the handler option will:
- send a
POST HTTPrequest with form data that the user filled in the action modal as body payload ("handler": "request"); - open a new browser tab with data that the user filled in action modal as serialized JSON in form of query parameters (
"handler": "open-url").
By default URL link will be used as the destination endpoint for all requests, but it can be also overwritten with the URL option by uploading schema with it.
Options for primary Action button
label
REQUIRED
string
Descriptive name of the action button, showcasing what will happen on button click.
e.g. submit or Create in app"
handler
REQUIRED
string
Option value will determine what the button will do when user clicks it.
one of "request", "open-url".
url
string
Must be added only when "handler": "open-url" and there is a need to direct the user out of Pipedrive to see the outcome of the embedded action inside the app.
If "handler": "open-url" is selected but url is not added to the schema, default URL for the app (the one added in Marketplace Manager for Embedded action) will be used.
{
"type":"object",
"properties":{
"actions":{
"type":"object",
"properties":{
"submit":{
"$ref":"#/definitions/action-primary",
"options":{
"label":"Submit",
"handler":"request"
}
}
}
}
}
}Open a new tab with action modal
{
"type":"object",
"properties":{
"actions":{
"type":"object",
"properties":{
"create":{
"$ref":"#/definitions/action-primary",
"options":{
"label":"Create in Asana",
"handler":"open-url"
}
}
}
}
}
}Open new tab with custom URL
{
"type":"object",
"properties":{
"actions":{
"type":"object",
"properties":{
"create":{
"$ref":"#/definitions/action-primary",
"options":{
"label":"Create in app",
"handler":"open-url",
"url":"https://www.exampleURLtoapp.com"
}
}
}
}
}
}Secondary Action button
The secondary action button allows the user to either reset all the contents of the modal to the original ones defined in the schema (added in the Marketplace Manager) or cancel and close the modal, therefore canceling the whole embedded app action.
For adding the secondary action button you'll need to add the following options to the schema:
label
REQUIRED
string
Descriptive name of the action button, showcasing what will happen on button click.
"Reset", "Cancel and Close"
handler
REQUIRED
string
Option value will determine what the button will do when user clicks it.
One of "reset" or "cancel"
{
"type":"object",
"properties":{
"actions":{
"type":"object",
"properties":{
"action_reset":{
"$ref":"#/definitions/action-secondary",
"options":{
"label":"Reset",
"handler":"reset"
}
}
}
}
}
}Cancel and close modal
When the user clicks this action, the modal will be closed, and the action canceled.
{
"type":"object",
"properties":{
"actions":{
"type":"object",
"properties":{
"action_cancel":{
"$ref":"#/definitions/action-secondary",
"options":{
"label":"Cancel and close",
"handler":"cancel"
}
}
}
}
}
}
Updated 3 months ago
Further reading
| User interaction handling |
| Embedded app actions |