Adding parameters to gadgets
You can add parameters to a new or existing gadget so an administrator can set them from the gadget settings window in admin view. For example, you might want an administrator to set the maximum height of your gadget.
There are two files in the gadget folder responsible for managing the gadget parameters: Settings.cfg and SettingsLayout.cfg. The SettingsLayout.cfg file controls which options appear in admin view.
Let's take a look at the SettingsLayout.cfg file for the slideshow gadget.
Let's look at how this file is structured.
Defining parameter sections
The top level is the root placeholder.
The levels below define individual parameter sections.
You can make your section collapsible by adding a isCollapsible attribute.
If you want your collapsible section to be collapsed by default, add the isCollapsed attribute as well:
A control is the endpoint setting for a gadget layout. Controls reside in sections. Some of controls are gadget-specific and hardcoded into the gadget logic, but most of them are easily modifiable and configurable.
Let's take a look at the content of the first ("General") section:
You can see some control entities inside the section. They define what controls you'll see, but not their data types.
For user-defined control references, you also should define a name which describes the control, to be shown near it, for example:
Defining control data types
The Settings.cfg file is where you define control data types. Each control entity describes one element of following types:
- string input
- number input
- size (in CSS-compatible format)
- offset (in CSS-compatible format)
- background (in CSS-compatible format)
- list of pre-defined values
- common built-in control types
- gadget-specific built-in control types
The basic syntax for describing control behavior is:
Where name property is the same as settingName in SettingsLayout.cfg.
For radio buttons and dropdown lists, the syntax is slightly different:
For full set of parameters, see Gadget setting attributes.
Using parameters in gadget templates
To use parameters in your gadget, add a reference to <$Model.SettingName$> in your GadgetTemplate.tpl (where SettingName is the name of the setting).
Using built-in controls
There are some predefined controls that you can reference in SettingsLayout.cfg without describing them Settings.cfg.
The following are built-in controls:
|CustomClassName||Gadget class name|
|InlineStyle||Inline CSS style|
|Style||Renders the Style dropdown|
The first control in the SettingsLayout.cfg file for the slideshow gadget asks for the image source.
There is no definition for this parameter in the Settings.cfg file, but it is not a built-in control. Instead, it is a gadget-specific control that is rendered and processed by the gadget server code. Since it is a gadget-specific control, it has a special settingName – ImageSource – that is recognized and processed by Wild Apricot.