---
title: Working with web part properties
related:
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-the-administration-using-portal-engine/using-and-configuring-web-parts.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-web-parts/creating-new-web-parts.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-web-parts/customizing-web-parts.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/assigning-form-controls-to-fields.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/reference-field-editor.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Properties allow [web parts](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-web-parts.md) 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](#handling-properties-in-web-part-code) of the web parts in their code.
3. [Configure the values of the properties](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-the-administration-using-portal-engine/using-and-configuring-web-parts.md) 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/reference-field-editor.md).
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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-the-administration-using-portal-engine/using-and-configuring-web-parts.md) 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/assigning-form-controls-to-fields.md) to learn more.
> **Note:** **Using web part properties with SQL values**
>
> Web part properties _WhereCondition_, _Columns_ and _OrderBy_ are reserved by the system and should only be used to input SQL code. When developing custom web parts with these properties, we strongly recommend using the predefined **Where condition**, **Order by** or **Columns** form controls (instead of a standard text box). These form control provide protection against the possibility of [privilege escalation](https://en.wikipedia.org/wiki/Privilege_escalation).
### 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](https://docs.kentico.com/13/macro-expressions.md), 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.
> **Info:** **Note**
>
> The **Resolve default value** check box only applies to macros added through the **Edit value** () dialog, and does not affect macros placed directly into the default values of text fields.
## Handling properties in web part code
Every web part is based on a user control [code file](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-web-parts/creating-new-web-parts.md). 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**.
```csharp title="Loading property values"
GetValue("FieldName");
```
```csharp title="Setting property values"
SetValue("FieldName", value);
```
> **Note:** **Note**
>
> The **SetValue** method does _not_ permanently assign a value into the property configuration of web part instances. It only affects the functionality of the web part within the context of the processed web request.
> **Tip:** **Best practice**
>
> A good way to handle web part properties is to wrap them into public properties of the user control class that implements the web part. This approach:
>
> - Makes it easier to work with the value of the property in other parts of the code.
> - Allows developers to easily access the property if they add the web part user control into other components.
>
> For example:
>
> ```csharp
>
> 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.
> **Note:** **Note**
>
> The following code only works for web part instances and zones that are placed **on the same** **[page template](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-the-administration-using-portal-engine/creating-portal-engine-templates.md)** as the web part whose code you are editing.
```csharp
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:
```csharp
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");
```
> **Tip:** **Tip**
>
> Create web part properties for storing the _Web part control IDs_ of connected web parts. This allows you to specify the related web parts for individual instances.
## 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.
> **Tip:** **Tip**
>
> Click **Reset field** to revert all settings of a modified property back to the original state.
### 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.
| Default | |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web part control ID | Serves as an identifier for the web part. This ID must be unique within the context of each page template. The value may only contain alphanumeric characters and the underscore character ( \_ ).
**Note**: It is recommended to keep the IDs of web part instances short to minimize the overall size of the page output code.
The _Web part control ID_ is a critical system field and you cannot modify it on the **System properties** tab of the web part editing interface. |
| Web part title | Title that the system displays for the web part on the **Administration interface -> Page templates -> Design** tab. If empty, the web part uses the _Web part control ID_ for this purpose. |
| Visibility | |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Visible | If disabled, the web part does not display any content on the page or perform any functionality. |
| Display to roles | Determines which roles are allowed to see the web part. You can use this property to implement pages with specific functionality for different types of users.
Specify the roles as a list of code names separated by semicolons (;) or click _Select roles_. If empty, the web part is displayed to all users. |
| HTML Envelope | |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Content before | HTML content placed before the web part. Allows you to display a header or add encapsulating code, such as __ or __ elements. |
| Content after | HTML content placed after the web part. Allows you to display a footer or close tags from the _Content before_ property. |
| AJAX | |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use update panel | If enabled, the system wraps the content of the web part into an AJAX [UpdatePanel control](https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.updatepanel). |
| Time zones | |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time zone | Specifies the type of [time zone](https://docs.kentico.com/13/configuring-xperience/configuring-time-zones.md) that the web part uses for its content. The following types are available:
**Server** – uses the server time zone settings.
**Website** – uses the site time zone settings.
**User** – uses the time zone settings of individual users.
**Custom** – uses the time zone selected in the _Custom time zone_ property. |
| Custom time zone | Assigns a custom time zone specifically for the content of the web part. The web part uses the selected time zone regardless of the time zone settings of the website or user viewing the page. |
| Performance | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Disable view state | Indicates if [view state](http://msdn.microsoft.com/en-us/library/bb386448%28v=vs.100%29.aspx) is disabled for the web part. |
| Disable macros | If checked, the web part does not resolve [macros](https://docs.kentico.com/13/macro-expressions.md) entered into the values of properties. |