Components:Additional entities - bettyblocks/cli GitHub Wiki

Besides component options, you can create actions and variables from a prefab. Those are called entities. If you want to make your entities dynamic based on user input we recommend using the beforeCreate. Entities can be linked to each other by references. If you are not familiar with references we recommended reading this first.

Contents

• Actions

  • Required fields
  • Example
  • Suppored event kinds
  • Configuring event options

• Variables

  • Required fields
  • Supported variable kinds
  • Example

Actions

You can define actions at the root level of your prefab. This actions entity can be used to create actions that can be executed via a component in runtime.

Required fields

The action entity comprises the following fields:

Fields	Required?	Type
name	true	string
useNewRuntime	true	boolean
id	false	uuid
endpointId	false	uuid
events	false	array

Example

You can add an actions array to our prefab like this:

(() => ({
  name: 'CreateForm',
  icon: 'FormIcon',
  category: 'FORM',
  actions: [
    {
      name: 'Create form action',
      ref: {
        id: '#actionId',             // Will be replaced by a uuid
        endpointId: '#endpointId',   // Will be replaced by a uuid
      },
      useNewRuntime: false,
      events: [
        {
          kind: 'create',
          options: {
            modelId: '', // can be set via beforeCreate
            assign: [], // can be set via beforeCreate
          }
        },
        {
          kind: 'update',
          options: {
            ref: {
              object: '#objectVariableId',
            },
            assign: [], // can be set via beforeCreate
          },
        },
      ],
    },
  ],
}))()

As you can see in the example above, we added an endpointId to the action entity. This is required to execute the action in runtime. If the endpointId is supplied an endpoint will be created and connected to the created action.

Each action can have an event array where you can define one or multiple events, it is only possible to add events to the root level of your action. We have set a maximum of 50 events per action.

Supported event kinds

We currently support the following events:

type EventKind =
  | "create"
  | "update"
  | "action"
  | "authenticate_user"

Configuring event options

In the example below, we listed some configured events.

{
  kind: 'update',
  options: {
    ref: {
      object: '#objectVariableId',
    },
    assign: [
      {
        leftHandSide: '#propertyId', // can be set via beforeCreate
        path: ['#customModelId', '#customModelAttribute'], // can be set via beforeCreate
      }
    ],
  },
}

{
  kind: 'create',
  options: {
    modelId: '', // can be set via beforeCreate
    assign: [
      {
        leftHandSide: '#propertyId', // can be set via beforeCreate
        path: ['#customModelId', '#customModelAttribute'], // can be set via beforeCreate
      }
    ],
  },
}

{
  kind: 'action',
  options: {
    assign: [], // can be set via beforeCreate
    ref: {
      modelAction: '#loginActionId',
      resultAs: '#actionResult',     // automatically creates a variable using this id
    },
  },
}

{
  kind: 'authenticate_user',
  options: {
    authenticationProfileId: '', // can be set via beforeCreate
    ref: {
      username: '#usernameVariableId',
      password: '#passwordVariableId',
      jwtAs: '#jwt',    // automatically creates a variable using this id
    },
  },
}

To set the value dynamically for the assign you can use something like this in the beforeCreate

prefab.actions[0].events[0].options.assign = properties.map(
  property => ({
    leftHandSide: property.id[0],
    ref: {
      path: [
        '#customModelVariableId',
        `#attribute_${property.id[0]}`,
      ],
    },
  }),
);

Variables

You can define variables at the root level of your prefab. This variable entity can be used to create variables that you can connect to an action.

Required fields

The variable entity comprises the following fields:

Fields	Required?	Type
name	true	string
kind	true	string
id	false	uuid
endpointId	false	uuid
actionId	false	uuid

Supported variable kinds

We currently support the following variable kinds:

type VariableKind =
  | "construct" // Custom model
  | "object"
  | "string"

Example

The variable entity with the actions entity can look like the example below.

(() => ({
  name: 'CreateForm',
  icon: 'FormIcon',
  category: 'FORM',
  actions: [
    {
      name: 'Update form action',
      ref: {
        id: '#actionId',
        endpointId: '#endpointId',
      },
      useNewRuntime: false,
      events: [
        {
          kind: 'update',
          options: {
            ref: {
              object: '#objectVariableId',
            },
            assign: [], // can be set via beforeCreate
          },
        },
      ],
    },
  ],
  variables: [
    {
      name: 'form_data',
      kind: 'construct',
      ref: {
        id: '#customModelVariableId',
        endpointId: '#endpointId',
      },
      options: {
        modelId: '', // can be set via beforeCreate
        ref: {
          customModelId: '#customModelId',
        },
      },
    },
    {
      kind: 'object',
      name: 'form_object',
      ref: {
        id: '#objectVariableId',
        endpointId: '#endpointId',
      },
      options: {
        modelId: '', // can be set via beforeCreate
      },
    },
    {
      kind: 'string',
      name: 'randomStringVar',
      ref: {
        id: '#randomStringVariable',
        endpointId: '#endpointId',
      },
    },
  ],
}))();

You can define multiple variables in your prefab up to a max of 20. The construct variable will create the actual variable and the custom model itself that's why you need to provide a customModelId.