Element Toolbar Power-Ups

Developer
1

What are Power-Ups?

Power-Ups are custom buttons that can be added to an element toolbar to send traits subscription events with an optional payload to a server to handle custom actions.

Currently, Power-Ups can only be added programmatically by API, and a server application must be running to subscribe to UpdateTraitsCommand to handle the button event. However, you can create Power-Up buttons on elements and then create a custom template that would retain all traits data, including your custom buttons.

For example, a Custom Power-Ups template category:

Power-Up template category
Power-Up template category1988×866 43 KB

Power-Ups can be added to any element, and they can be used to perform custom actions by the server that is listening to the update traits subscription event. The server can use a unique identifier to determine which button the user pressed and take the appropriate action.

For example:

Create a new image from seed Power-up Button
Create a new image from seed Power-up Button1354×1294 140 KB

Creating a Power-Up

Custom buttons are specialized elements JSON-LD traits that will be shown in the element UI toolbar.

Note: If there are existing Power-Up buttons already on an element, they are overwritten when setting new ones.

The JSON-LD context must be:

context: "http://bluescape.dev/ns/adaptivecards.jsonld"

You can specify the Power-UP button name and other parameters in the content actions array, as follows:

Actions Required? Description
title Required The name of your custom button that appears in the UI
id Required The unique ID that the server uses to identify what button was pressed
data Optional data payload object

For example, define two Power-up custom buttons on an existing element:

mutation updateTraitsCustomButton($workspace: String! $elementId:String!){
    updateTraits( id:$elementId, workspaceId: $workspace, input: {
        context: "http://bluescape.dev/ns/adaptivecards.jsonld"
        content: {
            actions: [ {
               title: "Power-Up display name 1"
               id: "uniquePowerUPactionID-1"
               data: { mySampleButton: true}
        },
        {
               title: "Power-Up display name 2"
               id: "uniquePowerUPactionID-2"
               data: { mySampleButton: true}
        }]
    }}) 
}

The resulting Power-Up results in attaching the custom button to the element, in this case a canvas:

Attaching the custom button to a canvas
Attaching the custom button to a canvas1894×1256 54 KB

Handling Button Event

Once the button has been added to the object toolbar, a server must subscribe to an update traits subscription event to get the action ID and the optional data payload.

When a user presses the Power-Up custom button, an UpdateTraitsCommand is sent as a graphQL subscription event.

Example Server Subscription:

subscription handleButtonAction($workspaceId: String!) {
    commands(workspaceId: $workspaceId) {
      ... on UpdateTraitsCommand{
        elementId
        elementType
        traits
      }
    }
  }

Response from “Power-Up display name 1”

{
  data: {
    commands: {
      elementId: '6543bf592f72aa90d9895a53',
      elementType: 'Canvas',
      traits: {
        'http://bluescape.dev/ws/ac/mostRecentActionRequest': {
          '@type': 'http://bluescape.dev/ac/Action.Execute',
          '@id': 'uniquePowerUPactionID-1',
          'http://bluescape.dev/ac/Extendable.Action/data': { '@value': { mySampleButton: true }, '@type': '@json' }
        }
      }
    }
  }
}

Once your server gets the event, you can read the @id and take the appropriate action. This can either be to send the data to an external server or to trigger Bluescape APIs to manage content in a workspace.

For Example:

const observer = {
  error(e) {
    console.log('Observer.error');
  },
  next(eventData) {
    console.log('Observer.next');
    console.dir(eventData, {depth: null});
    let idValue = eventData.data.commands.traits["http://bluescape.dev/ws/ac/mostRecentActionRequest"]["@id"];
    let elementType = eventData.data.commands.elementType;
    let elementId = eventData.data.commands.elementId;
    // Here, you can inspect and process the incoming eventData to take specific actions based on incoming  mostRecentActionRequest @id
  },
  complete() {
    console.log('Observer.complete');
  }
}

Deleting a Power-Up

If you want to delete a custom Power-Up button on an element, you can use updateTraits mutation for the specific elementId with content: {actions: null}

For Example:

mutation deleteTraitsCustomButton($workspace: String! $elementId:String!){
      updateTraits(
    id: $elementId    
    workspaceId: $workspace    
    input: {
      context: "http://bluescape.dev/ns/adaptivecards.jsonld"      
      content: {actions: null}
    }
  )
}
4 Likes