Building Blocks

Apps-Engine’s UIKit framework contains blocks, block elements, and objects that you can use to create UI surfaces and interactions for your apps. The components are built using structured JSON. These UI elements need to be triggered by an action or condition, such as sending a message, using slash commands, or using action buttons.

Let’s look at each of these components in detail.

Blocks

Blocks are the components you will use to create the base of the UI layout. Within blocks, you can add block elements and objects.

section

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `section`.
text	Object	Yes	The text that is to be displayed on the button. The value can either be `plain_text` or `mrkdwn`.
accessory	Object	No	A section can contain many block elements, for example, text, images, actions, etc.

Example

{
  type: 'section',
  blockId: 'section_1',
  text: {
      type: 'plain_text',
      text: 'lorem ipsum 🚀',
      emoji: true,
    }
  accessory: { /* define any of the block elements in this object */ } ,
}

For examples on how to use section blocks, see the topics Using UIKit Blocks, Create Contextual Bar, Create Modal, and Create Action Buttons.

divider

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `divider`.

Example

{
  type: 'divider',
  blockId: 'divider_1',
}

See how to use the divider block in the Using UIKit Blocks and Create Modal topics.

image

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `image`.
imageUrl	String	Yes	The URL of the image.
altText	String	Yes	A text describing the image being displayed.
title	Object	No	The text to be displayed as the image's title. The value can either be `plain_text` or `mrkdwn`.

Example

{
  type: 'image',
  blockId: 'image_1',
  imageUrl: 'https://picsum.photos/200/300',
  altText: 'An image',
  title: {
      type: 'plain_text',
      text: 'lorem ipsum 🚀',
      emoji: true,
    }
}

See how to use the image blocks in the Using UIKit Blocks and Create Contextual Bar topics.

actions

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `actions`.
elements	Array	Yes	A list of interactive block elements.

Example

{
  type: 'actions',
  blockId: 'actions_1',
  elements: [ /* block elements */ ]
}

Learn how to use the action block in the Create Modal topic.

context

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `context`.
elements	Array	Yes	A list of block elements. Allowed elements are `plain text object` and `image element`.

Example

{
  type: 'context',
  blockId: 'context_1',
  elements: [ /* block elements */ ]
}

input

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `input`.
element	Object	Yes	The input element, that can be `plain text input`, `static select menu`, and `multi static select menu`.
label	Object	Yes	The label for the block.

Example

{
  type: 'input',
  blockId: 'input_1',
  label: {
          type: 'plain_text',
          text: 'Input block',
        }
  element: { /* input block element */ }
}

See how you can add an input block in the Create Modal topic.

preview

Field	Type	Required?	Description
blockId	String	No	A unique identifier for the block.
type	String	Yes	The type of the block, in this case, `preview`
description	Array	Yes	Enter the type and text for the preview description.
title	Array	Yes	Enter the type and text for the preview title.

Example

{
  type: 'preview',
  description: [
      {
           type: 'plain_text',
           text: 'Description of preview'
       }],
  title: [
  {
    type: 'plain_text',
    text: 'Title of preview'
   }
]}

Block elements

Block elements are components that you can add to the blocks to enhance user interaction.

button

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case,`button`.
text	Object	Yes	The text that is to be displayed on the menu. The value can either be `plain_text` or `mrkdwn`.
value	String	No	A value sent along with the button information when an action is made upon the element.
url	String	No	A URL that the button points to.
style	String	No	The style of the button. The value can either be `primary` or `danger`.
actionId	String	Yes	A unique identifier for an action made upon the element.

Example

{
  type: 'button',
  text: {
      type: 'plain_text',
      text: 'danger❗',
      emoji: true,
    },
  actionId: 'button_1_danger',
  style: 'danger',
}

For an example on how to use buttons, see the Using UIKit Blocks topic.

image

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case, `image`.
imageUrl	String	Yes	The URL of the image.
altText	String	Yes	The text describing the image being displayed.

Example

{
  type: 'image',
  imageUrl: 'https://picsum.photos/200/300',
  altText: 'An image',
}

overflow menu

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case, `overflow`.
options	Array	Yes	An array with the possible options (the `options` object).
actionId	String	Yes	A unique identifier for an action made upon the element.

Example

{
  type: 'overflow',
  actionId: 'overflow_1',
  options: [
    {
      value: 'option_1',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
    {
      value: 'option_2',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
  ],
}

See the Create Contextual Bar topic for an example on how to add an overflow block element.

plain text input

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case, `plain_text_input`.
actionId	String	Yes	A unique identifier for an action made upon the element.
placeholder	Object	Yes	A placeholder text for the input (`plain text` object).
initialValue	String	No	The initial value of the field.
multiline	Boolean	No	A flag that indicates whether the field should be a single line (default) or a larger text area.

Example

{
  type: 'plain_text_input',
  actionId: 'plain_text_input_1',
  placeholder: {
      type: 'plain_text',
      text: 'Enter name',
      emoji: true,
    },
  initialValue: 'John Doe',
  multiline: false,
}

static select menu

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case, `static_select`.
actionId	String	Yes	A unique identifier for an action made upon the element.
placeholder	Object	Yes	A placeholder text for the input (`plain text` object).
initialValue	String	No	The initial value selected (`value` field from the `options` object).
options	Array	Yes	An array with the possible options (the `options` object).

Example

{
  type: 'static_select',
  actionId: 'overflow_1',
  initialValue: 'option_2',
  options: [
    {
      value: 'option_1',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
    {
      value: 'option_2',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
  ],
  placeholder: {
      type: 'plain_text',
      text: 'Select an item',
    },
}

Learn how to use the static menu block element in the Using UIKit Blocks topic.

multi-static select menu

Field	Type	Required?	Description
type	String	Yes	The type of the block element, in this case, `multi_static_select`.
actionId	String	Yes	A unique identifier for an action made upon the element.
placeholder	Object	Yes	A placeholder text for the input (`plain text` object).
initialValue	Array of strings	No	The initial values selected (`value` field from the `options` object).
options	Array	Yes	An array with the possible options (the `options` object).

Example

{
  type: 'multi_static_select',
  actionId: 'overflow_1',
  initialValue: ['option_1' ,'option_2'],
  options: [
    {
      value: 'option_1',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
    {
      value: 'option_2',
      text: {
          type: 'plain_text',
          text: 'lorem ipsum 🚀',
          emoji: true,
        }
    },
  ],
  placeholder: {
      type: 'plain_text',
      text: 'Select an item',
    },
}

radio button

Field	Type	Required?	Description
blockId	String	Yes	A unique identifier for the block element.
type	String	Yes	The type of the block element, in this case, `radio_button`
actionId	String	Yes	A unique ID for the action element to trigger further interactions.
options	Array	Yes	The options for the radio buttons.

Example

{
   type: 'radio_button',
   actionId: 'radio_button_action_1',
   appId: appId,
   blockId: 'radio_button_action_block_1',
   options: [{
       text: {
           type: 'plain_text',
           text: 'Option 1' },
       value: 'option_1' },
    {
       text: {
            type: 'plain_text',
            text: 'Option 2' },
       value: 'option_2' }
]}

Objects

Text object

Field	Type	Required?	Description
type	String	Yes	The type of text object that you want to add. The available values are `plain_text` and `mrkdwn`.
text	String	Yes	The actual text.
emoji	Boolean	No	Works with the `plain_text` type.

Example

{
  type: 'plain_text',
  text: 'lorem ipsum 🚀',
  emoji: true,
}

Option object

Field	Type	Required?	Description
text	Object	Yes	The text that is to be displayed on the menu. The value can either be `plain_text` or `mrkdwn`.
value	String	Yes	The actual value that the option represents.

Example

{
  value: 'option_1',
  text: {
      type: 'plain_text',
      text: 'lorem ipsum 🚀',
      emoji: true,
    }
}

Parameter details

When you are defining UI elements, you will have to add some common parameters. The parameters are as follows:

blockId: Set a unique ID for each block and element that you define. This ID can be used to determine which block interaction to handle.
actionId: Set a unique ID for each action block and element. This has a similar purpose to blockId as it is used to determine the interaction.
appId: This determines which app is going to receive any potential interaction that might be generated by the user within a block.

Depending on the block and element, any of these parameters may be mandatory or optional.

Now that we have the information on the various UI blocks, let’s see how to use them in our apps in the next topics.