Powerups

Powerups are tags that you can add to Rem which also add new functionality. Chances are you are already familiar with using powerups like the Todo powerup, and Edit Later powerup. Now with the RemNote plugin API, you can make the powerup system even more powerful by creating your own custom powerups!

Interacting with Built In Powerups

You can get the Rem representing a powerup using the getPowerupByCode method:

await plugin.powerup.getPowerupByCode(BuiltInPowerupCodes.Link);

You can get the data stored in a particular powerup slot by using the getPowerupProperty method:

await plugin.powerup.getPowerupProperty(BuiltInPowerupCodes.Link, 'URL');

Registering Custom Powerups

Here's an example of how to register a custom powerup:

await plugin.app.registerPowerup(
  'Custom Edit Later', // human-readable name
  'customEditLater', // powerup code used to uniquely identify the powerup
  'A Custom Edit Later powerup', // description
  {
    slots: [
      {
        // slot code used to uniquely identify the powerup slot
        code: 'message',
        // human readable slot code name
        name: 'Message',
        // (optional: false by default)
        // only allow the slot to be modified programatically
        onlyProgrammaticModifying: true,
        // (optional: false by default)
        // hide the slot - don't show it in the editor
        hidden: true,
      },
    ],
  },
);

Slots allow you to store custom data fields on Rem which are tagged with your custom powerup. In the example above, we added a slot called "Message". Later on we will see how to save data and retrieve data from this slot.

Tagging Rem with Powerups

When you register a powerup, this will create a powerup Rem with the name you specified in the user's knowledgebase. You can apply a powerup to another Rem by tagging that Rem with the powerup Rem:

const anotherRem = await plugin.rem.createRem();
// pass the powerup code we used to register the powerup
const editLaterPowerup = await plugin.powerup.getPowerupByCode(
  'customEditLater',
);
await anotherRem.addTag(powerup.id);

This is essentially the same as typing "##" followed by the name of a powerup and pressing enter in RemNote.

Of course, you aren't limited to using your custom powerup inside plugins, users will also be able to use exactly the same workflows as with core powerups.

Getting Rem Tagged with Your Powerup

You can easily get a list of all the Rem tagged with your powerup by using the .taggedRem() method on the powerup Rem object.

const editLaterPowerup = await plugin.powerup.getPowerupByCode(
  'customEditLater',
);
const editLaters = await editLaterPowerup.taggedRem();

Slots

As mentioned above, slots are a data storage mechanism - they allow you to store key-value pairs on Rem tagged with the powerup.

Setting Data in Slots

Here's an example of how to set the "message" slot on our Custom Edit Later powerup to "Hello World".

const anotherRem = await plugin.rem.createRem();
const editLaterPowerup = await plugin.powerup.getPowerupByCode(
  'customEditLater',
);
await anotherRem.addTag(powerup.id);
await anotherRem.setPowerupProperty(
  'customEditLater', // powerup code
  'message', // slot code
  ['Hello World'], // value (RichTextInterface)
);

Note that powerup slot values are stored as RichTextInterface values, rather than as strings or some other data format.

Since users can interact with your custom registered powerups like normal core powerups, they can also add slots manually by adding children to the tagged Rem and using the slot Omnibar command.

Getting Data from Slots

To get the value of a slot from a Rem tagged with a powerup, call the .getPowerupProperty() method:

const value = await anotherRem.getPowerupProperty(
  'customEditLater', // powerup code
  'message', // slot code
);