Working with web part properties

Properties allow web parts to cover a wide range of use cases and preferences. By using flexible web parts with properties, you do not need to create separate web parts for every specialized scenario.

The basic principle is the following:

1. Define a set of properties that affect the web part’s behavior.
2. Handle the properties of the web parts in their code.
3. Configure the values of the properties for individual instances of the web part.

Defining properties for web parts

To set up the properties of a web part:

1. Open the Administration interface application and switch to the Web parts tab.
2. Select the web part in the tree.
3. Switch to the Properties tab.

Each property is represented by a field with its own name, data type, default value, and other settings. You can place the properties into categories. Categories make orientation easier when configuring web parts with a large number of properties. Each category includes the properties that are positioned below it in the field editor.

Users can set the values of properties for individual web part instances in the Web part properties dialog, which opens when adding or configuring web parts on the Design tab in Administration interface -> Page templates.

• Only properties whose Display field in the editing form box is checked are visible in the configuration dialog.
• The editing interface of each visible property is provided by the selected Form control. Form controls allow you to choose from a large variety of built‑in field types, and provide almost unlimited customization options. See Assigning form controls to fields to learn more.

Inserting macros into the default values of properties

Properties use the Default value when users create new instances of the web part. If you wish to set a dynamic default value through macro expressions, you have two options:

Macros resolved when the page is displayed

• For text-based properties, place the macro directly into the default value.
  – OR –
• Click Edit value () next to the Default value, write the macro in the dialog, and leave the Resolve default value option disabled for the property.

When users add instances of the web part, the macro remains unresolved in the web part properties dialog. If the user leaves the expression in the property’s value, the system resolves the macro when displaying the administration page containing the web part instance.

Macros resolved in the properties dialog

Click Edit value () next to the Default value, write the macro in the dialog, and enable the Resolve default value option for the property.

The system resolves the macro directly when opening the web part properties dialog.

Handling properties in web part code

Every web part is based on a user control code file. Properties only affect the functionality of a web part if the code works with the property values.

Use the following methods to access the values of the web part’s properties. These methods, along with others, are inherited from the CMSAbstractWebPart base class. The first parameter (“FieldName”) must match the Field name of the property in Web parts -> Properties.

GetValue("FieldName");

SetValue("FieldName", value);

using CMS.Helpers;

...

// Public property that accesses the 'Path' web part property
public string Path
{
    get
    {
        return DataHelper.GetNotEmpty(GetValue("Path"), null);
    }
    set
    {
        SetValue("Path", value);

        // Assigns the value to an internal control inside the web part
        repeaterControl.Path = value;
    }
}

Accessing the properties of other web parts

You can use the API to create web parts that automatically adjust their behavior according to the configuration of other web parts or web part zones.

using CMS.PortalEngine.Web.UI;

...

// Gets an object representing the specified web part instance
// The FindWebPart method accepts a string parameter containing the 'Web part control ID' of the required web part instance
CMSAbstractWebPart webpart = PagePlaceholder.FindWebPart("webPartId");

// Gets an object representing the specified web part zone
// The FindZone method accepts a string parameter containing the ZoneID of the required web part zone. You can find the IDs of zones in the template's page layout code.
CMSWebPartZone zone = PagePlaceholder.FindZone(zoneId);

Call the GetValue or SetValue methods of the CMSAbstractWebPart object to work with the properties of the retrieved web parts. The same applies to web part zones and CMSWebPartZone objects.

For example, the following code sets the value of the Web part title property based on the configuration of another web part:

using CMS.Helpers;

...

// Gets instances of two other web parts (from the same page template)
CMSAbstractWebPart webpart1 = PagePlaceholder.FindWebPart("WebPart1");
CMSAbstractWebPart webpart2 = PagePlaceholder.FindWebPart("WebPart2");

// Gets the value of the Web part title property of 'WebPart1'
string wp1Title = ValidationHelper.GetString(webpart1.GetValue("WebPartTitle"), "");

// Sets the Web part title property of the current web part
this.SetValue("WebPartTitle", wp1Title + " 2");

// Sets the Web part title property of 'Webpart2'
webpart2.SetValue("WebPartTitle", wp1Title + " 3");

Modifying the system properties of web parts

You can modify the settings of the System properties for individual web parts:

1. Open the Administration interface application and switch to the Web parts tab.
2. Edit () a web part.
3. Switch to the System properties tab.

Reference - Web part system properties

The following tables describe the system properties of web parts. Some of the properties may not be available, depending on the Type of the web part. Additionally, the System properties tab does not contain properties that the web part overrides on the Properties tab.