Property Pages

Most widgets require configuration to function correctly. The widget configuration panels are exposed in the API, and can be leveraged and/or extended freely. To define a custom property panel, add a config.js file to the custom widget, and use the widget upload tool to bundle it.

The property page configuration file is a JavaScript file which is expected to return an extension on one of the objects in globally scoped object Pages.

Simplest form of the file would just return an existing configuration page (from one of the basic widgets), like so:

// Use the property page of Result List widget
return Pages.Search;

Extending the property page is done in same fashion as extending the base widget views.

The extended property page can implement any (or both) of two properties, customNormal and customAdvanced - depending which configuration section should be extended.

Each of the two properties is an array of objects, one per defined property. The objects are expected to contain the properties 'view' and 'config', The 'config' property should contain at minimum, 'inputName' and 'infoText', plus can define additional options, available for selected properties only.

• view
  • Specifies the type of property and is represented in the type of property view used. The properties available are exposed under the globally scoped 'Properties' object:
    • Properties.Bool
      • Defines a checkbox.
      • Serializes to a boolean model property type.
    • Properties.Color
      • Defines a colorpicker.
      • Serializes to a string model property type containing the color hashcode.
    • Properties.DateFormat
      • Defines a control allowing to customize the format of a data.
      • Serializes to a string model property containing the date formatting string.
    • Properties.Dictionary
      • Defines a dynamic key/value pair picker control.
      • Serializes to an object model property containing the chosen values.
    • Properties.Facet
      • Defines a multi-facet selector control, which allows selecting one of the facets defined in the system.
      • Serializes to an array of strings model property, corresponding to the names of facets chosen.
      • Property specific options:
        • min
          • Defines how many facets minimum should the property allow to configure and serialize under one model property.
        • max
          • Defines how many facets maximum should the property allow to configure and serialize under one model property.
        • colorPicker
          • Whether the control should allow choosing a color for each facet, by integrating a colorpicker control.
        • typeRestriction
          • Restricts type of facets which should appear in the control.
        • aggregate
          • Whether to provide aggregation options for the facet.
        • aggregateFunctions
          • Which mathematical functions to allow aggregation over. By default, min, max, sum and avg (average) are exposed.
    • Properties.Language
      • Defines a language control, which allows selecting a language from all languages list.
      • Serializes to a string model property containing the language identifier.
    • Properties.MultilineText
      • Defines a multiline text input control.
      • Serializes to a string model property containing the text.
      • Property specific options:
        • maxLines
          • Defines how many lines of text should the control allow.
    • Properties.Multiselect
      • Defines a radio control.
      • Serializes to a string model property containing the selected value.
      • Property specific options:
        • options
          • Defines the options for the radio control
          • Is an array of objects, each containing at least string properties label and value, as well as optionally boolean property default.
      • Example

        return Pages.Base.extend({
            customNormal: [
                {
                    view: Properties.Multiselect,
                    config: {
                        inputName: 'report',
                        infoText: Report',
                        options: [
                            { label: 'Income Statement', value: 'income', default: true },
                            { label: 'Balance Sheet', value: 'balance' },
                            { label: 'Cash Flow Statement', value: 'cashflow' }
                        ]
                    }
                }
            ]
        });

    • Properties.Number
      • Defines a number input control.
      • Serializes to an integer model property containing the selected number.
      • Property specific options:
        • min
          • Defines the minimum number that can be selected
        • max
          • Defines the maximum number that can be selected
    • Properties.Percentage
      • Defines a percentage slider control.
      • Serializes to an integer model property containing the selected percentage.
    • Properties.Text
      • Defines a singleline text input control.
      • Serializes to a string model property containing the text.
    • Properties.Trend
      • Defines a trend entity picker control.
      • Serializes to a string containing the trend entity id.
    • Properties.URL
      • Defines a URL input control.
      • Serializes to a string containing the URL.
      • Property specific options:
        • hideDocs
          • Hides the section explaining the usage of URLs within Squirro widgets
• inputName
  • Specifies the name of model property to which the value should be serialized.
  • Can be accessed in the custom widget code by this.model.get(inputName).
• infoText
  • Specifies the information text (title) that is displayed just above the property, providing additional instructions or description of the parameter to the user.

Additional options all properties support:

• defaultValue
  • Specifies the default value the property should use (for example when widget has been freshly added to the dashboard and thus not configured yet).
  • Value type depending on the property type.
• denyValidate
  • Allows to skip validation on fields. By default basic form validation is performed, depending on the property type.

// Use the base (empty) property page and extend it with new fields
return Pages.Base.extend({
	customNormal: [
		{
			view: Properties.Number,
			config: {
				inputName: 'myNumber',
				infoText: 'Select a number from 3 to 7',
				min: 3,
				max: 7,
				defaultValue: 5,
			},
		},
	],
});