Using Properties in Code

Please read the Adding Configurable Panel Properties guide before continuing, if you haven't already done so.

Getting a Property's Value

After you have declared the properties, it's time to use them in the panel's script - otherwise, they don't mean anything! To get the value of a property in the script, all you've got to do is:

var value = config.GetSetting("propertyName");

As you can see, we call the GetSetting function of the global config object to get the value of a property. The GetSetting function returns the value of a property. Remember, if the user hasn't changed the property yet, the default value is returned.

When you use this code in your panel, don't forget to replace "propertyName" with the actual name of the property, as it is defined in the <property> element's name attribute (see Adding Configurable Panel Properties).

Now that you know how to get the value of a property, you can change the behavior of the panel according to the configurations made in the Panel Properties dialog box.

Reloading When the Settings Change

When a user changes some settings in the Panel Properties dialog box and click OK, Desktop Sidebar notifies your panel so you can reload the settings and update the panel. To get notified when the settings change, add a function called onSettingsChanged to your script. For example:

function onSettingsChanged() { //Set our Text Output's text to "Checking Mail" if the user has chosen to check mail //or to "Not Checking Mail" if the user has unchecked that property in Panel Properties. if(config.GetSettings("checkForNewMail") == -1) GetControl("myTextOutput").SetText("Checking Mail"); else GetControl("myTextOutput").SetText("Not Checking Mail"); }

In this example, we check whether the "checkForNewMail" property is checked and change the text accordingly. Notice the use of if(.... == -1) to find out if the property is checked, because as the Property Types page says, -1 represents the checked state. Visit the Property Types page for a reminder of the different property types and their values.