Creating new web parts

If you are creating custom content in the Xperience administration interface using the Portal Engine, and the web parts included by default do not meet your requirements, you can create your own web. This allows you to add any type of content or functionality. Developing new web parts consists of two basic steps:

1. Create the web part’s code files in your web project.
2. Register the web part in the system.

Writing web part code

Implement web parts as user controls (.ascx files) that inherit from the CMSAbstractWebPart base class (available in the CMS.PortalEngine.Web.UI namespace).

To ensure that your custom web parts work correctly:

1. Edit the markup of the user control that implements the web part.
2. In the Control declaration, enter the full relative path of the code behind file into the CodeBehind attribute.

For example:

<%@ Control Language="C#" AutoEventWireup="true" Inherits="CMSWebParts_Custom_WebPart" CodeBehind="\~/CMSWebParts/Custom/webpart.ascx.cs" %>

You can add any required content into the web part’s markup and write custom code behind logic.

Tips:

• See Working with web part properties to learn how to access the values of web part properties in the code.

• To disable web parts in your code, set the StopProcessing property to true. All web parts inherit this property from the CMSAbstractWebPart base class.

• You can implement web parts that have special behavior or additional content when viewed on the Design tab of the Administration interface -> Page templates tab. Use the following code to check whether the web part is being rendered in the Design mode:

  Copy

  
  
  
    using CMS.PortalEngine.Web.UI;
  
    if (PortalContext.IsDesignMode(this.PagePlaceholder.ViewMode))
    {
        ...
    }
  
  
    

Setting the properties of controls in web parts

If you use Xperience controls inside your web parts, it is recommended to set/initialize the control properties using a combination of the OnContentLoaded and SetupControl methods.

For standard .NET or third party controls, you can set the properties in the handler of the web part control’s Load event (OnLoad method).

Storing files related to web parts

If your web part consists of multiple files (such as other ASCX controls, images, JS scripts), place these files in a sub‑folder under the directory containing the main web part’s files. The name of the sub-folder must match the code name of the web part with _file appended. For example, if the web part’s code name is WebPart, the sub‑folder must be WebPart_files.

This ensures that the system includes the additional files in the web part’s export package when you deploy the website or distribute the web part to other developers.

Managing web parts in the system

Registering web parts

Before you can use your user controls as web parts, you need to register them as objects in Xperience. The system sorts web parts into categories, organized in a tree structure.

1. Open the Administration interface application and switch to the Web parts tab.
2. Select the category where you want to place the web part.
3. Click New web part.
4. Type a Display name for the web part.
5. Select Use existing file as the Code files option.
6. Specify the path of the user control in the File path field.
7. Click Save.
8. Define the properties of the web part. See Working with web part properties for more information.

You can now place instances of the web part onto portal engine page templates on the Design tab of the Administration interface -> Page templates interface.

Configuring web parts

To edit the settings of a web part, open the Administration interface application, switch to the Web parts tab, and select the web part in the category tree. When editing web parts, you can configure the following on the General tab of the edited web part:

Example - Creating a new web part

The following example guides you through the process of creating a simple “Hello world” web part that displays a label and a button. When a user clicks the button, the label displays the current time.

Creating the web part code files

1. Open your Xperience project in Visual Studio using the WebApp.sln file.

2. Right-click the CMSWebParts folder in the Solution Explorer window and click Add -> New Folder.

3. Name the sub-folder MyWebParts.

4. Create a Web User Control named HelloWorld.ascx in the MyWebParts folder.

5. In the Control declaration, enter the full relative path of the control’s code behind file into the CodeBehind attribute.

   Copy

   
   
   
    <%@ Control Language="C#" AutoEventWireup="true" CodeBehind="\~/CMSWebParts/MyWebParts/HelloWorld.ascx.cs" Inherits="CMSWebParts_MyWebParts_HelloWorld" %>
   
   
    

6. Add a Button and Label control into the control’s markup.

   Copy

   
   
   
    <asp:Button ID="Button1" runat="server" Text="Button" /><br />
    <asp:Label ID="Label1" runat="server" Text="Label" />
   
   
    

7. Set the Visible property of the Label control to False.

8. Switch to Design mode and double-click the Button control.

   • Visual Studio opens the control’s code behind file and creates a handler method for the button click event.

9. Add the following code into the Button1_Click method:

   Copy

   
   
   
    Label1.Text = DateTime.Now.ToString();
    Label1.Visible = true;
   
   
    

10. Add the following using statements to the beginning of the control’s code behind:

    Copy

    
    
    
    using CMS.PortalEngine.Web.UI;
    using CMS.Helpers;
    
    
    

11. Modify the control’s class declaration so that it inherits from CMSAbstractWebPart:

    Copy

    
    
    
    public partial class CMSWebParts_MyWebParts_HelloWorld : CMSAbstractWebPart
    
    
    

12. Add the following code to the Page_Load method:

    Copy

    
    
    
    Button1.Text = DataHelper.GetNotEmpty(GetValue("ButtonText"), "Show time");
    
    
    

13. Save the user control’s files.

14. Rebuild the solution.

The web part’s source files are now ready.

Registering the web part in the system

1. Sign in to the Xperience administration interface, open the Administration interface application and switch to the Web parts tab.

2. Select the one of the root categories in the tree, click … next to the New web part button and select New category.

3. Type My web parts into the Category display name field and click Save.

4. Select the new category and click New web part.

5. Specify the following values:

   • Web part: Create a new
   • Display name: Hello world
   • Code files: Use existing file
   • File path: ~/CMSWebParts/MyWebParts/HelloWorld.ascx

6. Click Save.

7. Switch to the Properties tab and click New field to create a web part property:

   • Field name: ButtonText
   • Data type: Text
   • Size: 100
   • Field caption: Button text
   • Form control: Text box

8. Click Save.

You can now add the web part to a Portal Engine template through the Page templates tab of the Administration interface application.