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.

<SettingsLayout>
    <Section title="General">    
        <Control settingName="ImageSource" />   
        <Control settingName="GalleryLayout">
            <ControlItem value="FixedHeight">
                <Control settingName="LayoutFixedHeight" postfix="px" controlContainerDisplayType="fixed" />
            </ControlItem>                                                             
        </Control>
        <Control settingName="FitImage" />
    </Section>  
    <Section title="Slideshow controls">  
        <Control settingName="DisplayImage" title="Display image for:" titlePosition="Left" titleWidth="120" postfix="sec" controlContainerDisplayType="fixed" />
        <Control settingName="TransitionTime" title="Transition time:" titlePosition="Left" titleWidth="120" postfix="ms" controlContainerDisplayType="fixed" />
        <Control settingName="TransitionEffect" type="DropDownList" title="Transition effect:" titlePosition="Left" titleWidth="120" />    
        <Control settingName="AllowUserManuallyNavigate" />
    </Section>
    <Section title="Appearance">
        <Style>
            <Margin />
        </Style>
    </Section>
    <Section title="Advanced" isCollapsible="true" isCollapsed="true">
        <UnencodedText>Use CSS to fine-tune appearance and behavior.
            &lt;a href=&quot;http://help.wildapricot.com/display/DOC/Gadgets#Gadgets-HTMLandCSSparameters/
                 ?utm_source=contexthelp&amp;utm_medium=site&amp;utm_campaign=contexthelp&quot; target=&quot;_blank&quot; &gt;Learn more&lt;/a&gt;
        </UnencodedText>
        <Control settingName="ClientId"/>
        <Control settingName="CustomClassName"/>
        <Control settingName="InlineStyle"/>
    </Section>
</SettingsLayout>

Let's look at how this file is structured.

Defining parameter sections

The top level is the root placeholder.

<SettingsLayout>
...
</SettingsLayout>

The levels below define individual parameter sections.

<Section>
...
</Section>

You can make your section collapsible by adding a isCollapsible attribute.

<Section title="Section Title" isCollapsible="true">

If you want your collapsible section to be collapsed by default, add the isCollapsed attribute as well:

<Section title="Section Title" isCollapsible="true" isCollapsed="true">

Controls referencing

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:

<Section title="General">
		<Control settingName="ImageSource" />
		<Control settingName="GalleryLayout" />
		<Control settingName="FitImage" />
</Section>

You can see some control entities inside the section. They define what controls you'll see, but not their data types.

Generally, we place controls in desired order in SettingsLayout.cfg and define their behavior, values, and properties in Settings.cfg.

For user-defined control references, you also should define a name which describes the control, to be shown near it, for example:

<Control settingName="MySetting" title="Check to enable extra coolness" />

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
• Boolean
• 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:

<Setting name="SettingName" type="[string | boolean | number | cssSize | cssoffset | background ]" />

Where name property is the same as settingName in SettingsLayout.cfg.

For radio buttons and dropdown lists, the syntax is slightly different:

<Setting name="SettingName" type="list">

    <Item value="val1" title="Value 1" />
    <Item value="val2" title="This is Value 2" />

    ...
</Setting>

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).

Here's example from the slideshow gadget's GadgetTemplate.tpl. It uses gadget settings to initialize the slideshow's JavaScript with parameters from the gadget:

<script language="javascript">
	jq$(function(){

		jq$('#camera_wrap_<$Model.ComponentId$>').camera
		(
		  {
			componentId: '<$Model.ComponentId$>',
			thumbnails: true,
			loader: 'pie',
			fx: '<$(Model.Settings.TransitionEffect)$>',
			time: (<$Model.Settings.DisplayImage$>*1000),
			transPeriod: (<$Model.Settings.TransitionTime$>),
			portrait: <$if(Model.Settings.FitImage)$>false<$else$>true<$endif$>,
			playPause: false,
			pauseOnClick: false,
			thumbnails: <$Model.Settings.AllowUserManuallyNavigate$>,
			pagination: <$Model.Settings.AllowUserManuallyNavigate$>,
			navigation: <$Model.Settings.AllowUserManuallyNavigate$>,
			height: <$if (Model.Settings.GalleryLayout=="Landscape")$>'56%'<$endif$>
					<$if (Model.Settings.GalleryLayout=="Portrait")$>'133.3%'<$endif$>
					<$if (Model.Settings.GalleryLayout=="Square")$>'100%'<$endif$>
					<$if (Model.Settings.GalleryLayout=="FixedHeight")$>'<$Model.Settings.LayoutFixedHeight$>px'<$endif$>
		  }
		);
	});
</script>

Using built-in controls

There are some predefined controls that you can reference in SettingsLayout.cfg without describing them Settings.cfg.

If you see a control placeholder in SettingsLayout.cfg, but no corresponding reference in Settings.cfg, it means that it is either a built-in control or a gadget-specific control.

The following are built-in controls:

Gadget-specific controls

The first control in the SettingsLayout.cfg file for the slideshow gadget asks for the image source.

<Control settingName="ImageSource" />

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.