Sidebar Contributions

What is the Sidebar?

The sidebar is a quickly accessible part of the interface, useful for many different, often used functions. Some of the built-in functionalities you will find in the sidebar, include the ability to jog the robot, see information about global variables and navigate the program tree while setting up your program.

The API to contribute a sidebar item means that your URCap will be able to provide quick access to various functions of your software, be that opening and closing a gripper, quickly reconfiguring a pallet or providing guidance to programmers or operators.

Creating a sidebar item is very similar to the process of creating any other URCap contribution in Polyscope X, so if you have already created a program node, application node or smart skill, the following instructions should feel quite familiar.

How to add a Sidebar Item to a Front-end Contribution?

If you have a URCap that does not contain a sidebar item you can add one by following these steps:

1. Add the Folders and Files

Add a folder to your frontend where you store your sidebar item(s), and add the sidebar item behavior worker TS file to that folder. In our example we call our folder gripper-sidebar-item and likewise for the behavior worker (it is not required that the folder and the behavior worker are named the same):

└─ src
   ├─ app
   │  ├─ app.module.ts
   │  └─ components
   │     ├─ gripper-program-node
   │     │  ├─ gripper-program-node.behavior.worker.ts
   │     │  ├─ gripper-program-node.component.html
   │     │  ├─ gripper-program-node.component.ts
   │     │  └─ gripper-program-node.node.ts
   │     └─ gripper-sidebar-item
   │        └─ gripper-sidebar-item.behavior.worker.ts
   ├─ assets
   │  ├─ i18n
   │  └─ icons
   ├─ contribution.json
   ├─ index.html
   ├─ main.ts
   └─ styles.scss

2. Add the Behavior

Add the default behavior to the empty gripper-sidebar-item.behavior.worker.ts file:

import { registerSidebarBehavior, SidebarItemBehaviors } from '@universal-robots/contribution-api';

const behaviors: SidebarItemBehaviors = {
    // factory is required
    factory: () => {
        return { type: 'gripper-sidebar-item', version: '1.0.0' };
    },
};

registerSidebarBehavior(behaviors);

3. Add the sidebar item to the app.module.ts:

registerWorkersWithWebPack() {
    ...
    new Worker(new URL('./components/gripper-sidebar-item/gripper-sidebar-item.behavior.worker.ts' /* webpackChunkName: "gripper-sidebar-item.worker" */, import.meta.url), {
        name: 'gripper-sidebar-item',
        type: 'module',
    });
}

4. Add the translations for your new sidebar item in the en.json:

{
  "sidebar-items": {
    "gripper-sidebar-item": { //Note that this _MUST_ match the componentTagName found in contribution.json
      "title": "Gripper"
    }
  }
}

5. Add the webcomponent files

Add the *.html, *ts and optionally the *.scss styles file.

└─ gripper-sidebar-item
   ├─ gripper-sidebar-item.behavior.worker.ts
   ├─ gripper-sidebar-item.component.html
   ├─ gripper-sidebar-item.component.scss
   └─ gripper-sidebar-item.component.ts

6. Add the contents to gripper-sidebar-item.component.ts

import { ChangeDetectionStrategy, Component, Input } from '@angular/core';
import { SidebarItem, SidebarItemPresenter, SidebarPresenterAPI } from '@universal-robots/contribution-api';

@Component({
    templateUrl: './gripper.component.html',
    styleUrls: ['./gripper.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GripperComponentSidebarItem implements SidebarItemPresenter {
    @Input()
    instance: SidebarItem;

    @Input()
    presenterAPI: SidebarPresenterAPI;
}

7. Add the presenter to the App

In the app.module.ts add the creation of the web-component:

ngDoBootstrap() {

    ...

    customElements.define(
        'gripper-component-sidebar-item',
        createCustomElement(GripperComponentSidebarItem, { injector: this.injector })
    );
}

8. Edit the contribution.json file to include the sidebar item:

{
    "sidebar": [
        {
            "name": "gripper-sidebar-item",
            "iconURI": "assets/icons/gripper-icon.svg",
            "presenterURI": "main.js",
            "behaviorURI": "gripper-sidebar-item-behavior-worker.js",
            "translationPath": "assets/i18n/",
            "componentTagName": "gripper-sidebar-item",
            "size": "large"
        }
    ]
}

Rebuild and reinstall the URCap with the new sidebar item presenter and look for the Gripper icon in the sidebar!