Migrating legacy to boolean feedbacks

Why

Most feedbacks should now be defined as 'boolean' feedbacks. The idea is to gradually convert them across over time, as they give the user more flexibility and will end up with a more consistent interface.

Previously, it was up to the module author to decide what properties a feedback should change. This means that most feedbacks are only able to change both the background and text colour. But what if the user wants to change a png, or the text? They could ask for that to be possible, but that would likely require the module author to duplicate the feedback with different style options.

With boolean feedbacks, the module author simply has to make the feedback be a true or false value, and the user can decide what style properties that should change.

A benefit of this, is that these boolean feedbacks can be used as conditions in the trigges system. We hope to allow for more complex behaviours with these feedbacks, but before that is worth doing we neeed more modules to be utilising the new type of feedback

Steps

The process to migrate feedbacks across does involve a bit of work, but it is pretty straightforward.

1. Update feedback definitions

The feedback definitions need updating to the new style.
From:

feedbacks['set_source'] = {
    type: 'advanced',
    name: 'Brief description of the feedback here',
    description: 'Longer description of the feedback',
    options: [{
        type: 'colorpicker',
        label: 'Foreground color',
        id: 'fg',
        default: combineRgb(0, 0, 0)
    }, {
        type: 'colorpicker',
        label: 'Background color',
        id: 'bg',
        default: combineRgb(255, 0, 0)
    }, {
        type: 'number',
        label: 'Source'
        id: 'source',
        default: 1
    }],
    callback: (feedback) => {
        if (this.currentSource == feedback.options.source) {
            return {
                bgcolor: feedback.options.bg,
                color: feedback.options.fg,
            }
        }
    },
}

To:

feedbacks['set_source'] = {
    type: 'boolean', // Change this
    label: 'Brief description of the feedback here',
    description: 'Longer description of the feedback',
    defaultStyle: {
        // Move the values from options to here
        color: combineRgb(0, 0, 0),
        bgcolor: combineRgb(255, 0, 0)
    }
    // remove the old style properties from options
    options: [{
        type: 'number',
        label: 'Source'
        id: 'source',
        default: 1
    }]
    callback: (feedback) => {
        // Update this to return the boolean value you used to use to decide to return the style object
        return this.currentSource == feedback.options.source
    },
}

2. Update presets

Any presets defined in the module will need to be updated to match the changes in the definition

From:

{
    type: 'press',
    category: `Category description`,
    name: `Button description`,
    style: {
        ...
    },
    feedbacks: [
        {
            feedbackId: 'set_source',
            options: {
                bg: combineRgb(0, 255, 0),
                fg: combineRgb(255, 255, 255),
                input: src.id,
                mixeffect: me,
            },
        },
    ],
    actions: [
       ...
    ],
}

To:

{
    type: 'press',
    category: `Category description`,
    name: `Button description`,
    style: {
        ...
    },
    feedbacks: [
        {
            feedbackId: 'set_source',
            options: {
                input: src.id,
                mixeffect: me,
            },
            style: {
                bgcolor: combineRgb(0, 255, 0),
                color: combineRgb(255, 255, 255),
            }
        },
    ],
    actions: [
       ...
    ],
}

4. Add an upgrade script

Users will have feedbacks assigned to buttons already, and these will all need updating to the new format. A helper has been added to help with self.

Quick tip: The script will only be run once, if you want to force it to be run again locally, (Pending, this step has changed) to force all the upgrade scripts to be rerun. Make sure to not commit that line

const upgradeToBooleanFeedbacks = instance_skel.CreateConvertToBooleanFeedbackUpgradeScript({
	set_source: true,
	set_output: true,
	// List as many feedback types as you like
})

runEntrypoint(MyInstance, [myOtherUpgradeScript, upgradeToBooleanFeedbacks])

This script will handle moving the options properties across to the style object for you. It handles the most common cases of property naming, which may not match what your module does.
If this is the case, you can customise the behaviour by providing more details:

CreateConvertToBooleanFeedbackUpgradeScript({
	set_source: {
		bg: 'bgcolor',
		fg: 'fgcolor',
	},
})

5. Test it

Make sure to test it all thoroughly, then you are done!

Feel free to ask on slack if you have any questions, or anything here doesn't make sense.

Further Reading

• Upgrade Scripts
• Feedbacks