Add a new Settings page in the Client side section

[gremlation]

The sample code provided on the Examples page uses a deprecated way of adding settings and is missing a lot of details.

The new page shows the new way of doing things and explains the different data types, options, and events.

[christian-byrne]

New Settings API

// Register a new setting
app.registerExtension({
  name: 'TestExtension1',
  settings: [
    {
      id: 'TestSetting',
      name: 'Test Setting',
      type: 'text',
      defaultValue: 'Hello, world!'
    }
  ]
})

// Get the value of a setting
const value = app.extensionManager.setting.get('TestSetting')

// Set the value of a setting
app.extensionManager.setting.set('TestSetting', 'Hello, universe!')

[christian-byrne]

Setting Type

export interface SettingParams extends FormItem {
  id: keyof Settings
  defaultValue: any | (() => any)
  onChange?: (newValue: any, oldValue?: any) => void
  // By default category is id.split('.'). However, changing id to assign
  // new category has poor backward compatibility. Use this field to overwrite
  // default category from id.
  // Note: Like id, category value need to be unique.
  category?: string[]
  experimental?: boolean
  deprecated?: boolean
  // Deprecated values are mapped to new values.
  migrateDeprecatedValue?: (value: any) => any
  // Version of the setting when it was added
  versionAdded?: string
  // Version of the setting when it was last modified
  versionModified?: string
}

/**
 * The base form item for rendering in a form.
 */
export interface FormItem {
  name: string
  type: SettingInputType | SettingCustomRenderer
  tooltip?: string
  attrs?: Record<string, any>
  options?: Array<string | SettingOption>
}

[christian-byrne]

There's also colorpicker and file upload components.

You can bind properties to the components with attrs. There is full documentation on all the components in Primevue docs.

For example This is the default number:

app.registerExtension({
  name: 'TestExtension4',
  settings: [
    {
      id: 'TestSetting222222',
      category: ['Test2','d'],
      name: 'Test Settingd',
      type: 'number',
      defaultValue: 22,
    }
  ]
})

You can look at InputNumber documentation to find props you want to use and then apply them:

app.registerExtension({
  name: 'TestExtension4',
  settings: [
    {
      id: 'TestSetting222222',
      category: ['Test2','d'],
      name: 'Test Settingd',
      type: 'number',
      defaultValue: 22,
      attrs: {showButtons: true, prefix: '$'}
    }
  ]
})

Btw, your explanations and writing are very good on these docs.

[gremlation]

Thanks for the information @christian-byrne! I added references to the relevant components and updated some of the information that was incorrect, so it explains how to support floating point numbers in number inputs for example.

I wasn't able to figure out how to add a color picker or file input - are these definitely supported for settings, or are these only supported as widgets inside nodes? Do you have a working example?

[christian-byrne]

Nice work, it's looking good.

Re: color and file picker components, I forgot to mention that they were added in this PR which is not in the stable build of the frontend yet. While it's waiting to be added, you can test it by following these instructions

[gremlation]

Ah, got it. Thanks, I'll follow up with another PR to add those docs when it's in stable then.

[christian-byrne]

Sounds good. Were you able to try using app.extensionManager.setting.get instead of app.ui.settings.getSettingValue? The later is marked as deprecated.

[gremlation]

Sorry, I didn't see that the first time around. It was marked as deprecated five days ago, my working copy didn't have those changes in. I've updated it now.

[gremlation]

I added documentation for the color and image upload setting types. I couldn't get the default value to work for the image upload. I tried an HTTPS URL and a data URL.

[christian-byrne]

It looks good to me! I just did console test with all the examples and they all work. Just one missing comma here.

You could also consider documenting how the onChange callback is invoked immediately after registration. Someone on Disc specifically asked for it to be documented a while ago. Up to you!

[gremlation]

Thanks! Fixed the comma and added a note about the change event.

[robinjhuang]

Thanks for adding this!