[Feat] Preset text fields

[thedist]

Is this a feature relevant to companion itself, and not a module?

• I believe this to be a feature for companion, not a module

Is there an existing issue for this?

• I have searched the existing issues

Describe the feature

Currently presets are defined by module developers as an array of CompanionButtonPresetDefinition's. What I'm proposing is for there to be an alternative structure to allow for more functionality while still being backwards compatible by allowing the existing structure to work without modification.

As an example of the sort of thing I had in mind

// companion-module-base src/module-api/preset.ts
export interface CompanionPresetAdvancedDefinitions  {
  text: string
  categories: {
    [id: string]: CompanionPresetDefinitions []
  }
}

export interface CompanionTextPresetDefinition {
  type: 'static-text'
  value: string
}

export interface CompanionPresetDefinitions {
  [id: string]: CompanionButtonPresetDefinition | CompanionTextPresetDefinition | undefined
}

// A modules function for returning presets
function getPresets(instance: Instance): CompanionPresetAdvancedDefinitions {
  return {
    text: 'Some lines of text that appear above the category buttons',
    categories: {
      'Category 1': CompanionPresetDefinitions []
      'Category 2': CompanionPresetDefinitions [].
      'Category 3': CompanionPresetDefinitions [].
      ...
    }
  }
}

In this example, there would be a line of text that can be rendered by the web-ui above the preset categories. Additionally, inside the preset categories there would either by the button type, which would be displayed as they currently are, or a new static-text type which could cause the web-ui to create a line break and some text.

On Companions side there would need to be a check when a modules instance sends the presets as to if they are an array of presets, or an object with the categories property for example, as this would allow for full backwards compatibility. Implementing this feature request could also be done in stages too, where initially the structure remains unchanged but a 'static-text' type is created, as there is already a 'type' field but it's limited to 'button', and then at some point in time later adjust the structure to allow for text on the categories page.

Usecases

The use case for this is that much like config options, it can be be a better user experience to have some short simple instructions on how the presets are intended to be used, maybe including a link to some documentation on github, mentioning what custom-variables may need to be created/used, and for future upgrades to the preset system this could also be utilized for instructions on things like mass copying of presets to a page should that ever be thing.

[dnmeid]

I've been thinking for a while of a tree like hierarchy, which I think we could use for a lot of UI elements.
The presets alltogether would then be one node on that tree and all connections issuing presets are at the next level. All categories of presets are again the next level, sub-categories the next level...
So a module could have a nested structure of preset categories.
The solution I had in mind was that the value of category in the preset definition, which now is a string with the category name, could also be an array of strings.
This would also be backwards compatible when category: 'examples' gives the same result as category: ['examples'].
category: ['examples', 'funny examples'] would render that preset in the category "funny examples", which is a sub-category of "examples".
That way each node in the tree can hold presets and other categories as well and to me it seems quite easy to implement and intuitive to use. When tree nodes can be collapsed in the UI the user can just unfold the interesting presets and also can have several presets of different categories or even different connections visible at the same time.

[Julusian]

I agree that a tree structure would be good going forward, and allow more options for grouping.

I am envisioning this to be something like:

class InstanceBase {
    /**
     * Old method
     * @deprecated Use `setPresetDefinitionsTree` instead
     */
	setPresetDefinitions(presets: CompanionPresetDefinitions): void 

    /**
     * New method
     */
    setPresetDefinitionsTree(presets: CompanionPresetDefinitionsTree): void
}

interface CompanionPresetDefinitionsTree {
    categories: CompanionPresetDefinitionsTree[]

    sections?: CompanionPresetDefinitionsSection[]

    presets: CompanionPresetDefinition[]
}

interface CompanionPresetDefinitionsSection {
    /** The name of this preset */
    name: string
    /** The text to display */
    text: string

    presets: CompanionPresetDefinition[]
}

with this, the CompanionTextPresetDefinition would probably not be supported in this structure, as it would be handled by the sections.

Any input on this? I am not 100% certain, but I think it should be possible to translate existing presets into this new structure (perhaps utilising sections with no name&title)
I suspect we might want to think about reducing the load on ipc for transporting presets, perhaps we can do this more lazily or in a more rpc on-demand approach? (I am considering a larger shift in IPC approach for the module 2.0 api too)