Using custom web part layouts

✖
Copy to clipboard

Web part layouts are custom skins that replace the HTML code and ASPX markup of a web part. Layouts allow you to customize the appearance of components that are based on the web part:

To manage the layouts of web parts, navigate to Administration interface -> Web parts, edit a web part and select the Layouts tab.

Requirement

The Control declaration in the markup of the web part’s user control file must contain the full relative path to the code behind file in the CodeBehind attribute. For example:




<%@ Control Language="C#" AutoEventWireup="true" Inherits="CMSWebParts_Navigation_cmslistmenu" CodeBehind="~/CMSWebParts/Navigation/cmslistmenu.ascx.cs" %>

We do not recommend calling any inline code in the web part layout file itself. Such custom code can be hard to maintain across different versions of Xperience if the code of the underlying web part changes. Only use the web part layout to extend or reorganize the web part’s markup or HTML.

If you need to call custom code, create a custom web part based on the original.

Do not remove controls from the layout

Keep all of the default controls inside the code of web part layouts to ensure that web parts work correctly. If you need to hide any of the controls, add the Visible=“False” attribute.

Note: Your custom web part layouts may not work after upgrading to a new version of Xperience (if the controls in the web part’s markup changed). Please test your website carefully after upgrading, and update your custom layouts according to the controls in the default layout if necessary.

Assigning layouts to dashboard widgets

To select the layout for a dashboard widget:

  1. Open the Administration interface application and select the Widgets tab.
  2. Select a widget based on the web part for which you have created the custom layout.
  3. On the General tab, choose the Layout.
    • The (Default) layout uses the markup of the web part’s source file.
  4. Click Save.

The appearance and content of the dashboard widget is now based on the assigned layout.

Setting default layouts for inherited web parts

 You can prepare specialized versions of web parts that use a specific layout by default:

  1. Open the Administration interface application and switch to the Web parts tab.
  2. Create an inherited web part based on the web part you want to modify.
  3. On the Layouts tab of the inherited web part, define the required custom layout.
  4. Enable the Is default option of the given layout.
    • An inherited web part cannot have more than one default layout at a given time.
    • If there is no default layout, the inherited web part uses the default markup of the parent web part.

The system automatically assigns the selected layout to new instances of the inherited web part.