Adding custom code to portal engine page templates

The most direct way to insert custom code into a portal engine-based website is using standard ASCX user controls.

Example - Current time

This example demonstrates how to create a simple user control that displays the current time, and integrate it into a portal engine website.

Creating the user control

  1. Open your web project in Visual Studio.

  2. Right-click the web project in the Solution Explorer and click Add -> New Folder.

  3. Name the folder according to the code name of your site.

    • This ensures that the system exports the folder along with your website when you deploy it to another instance of Kentico.

  4. Create a Web User Control in the new folder and set its name to GetTime.ascx.

  5. Drag the following ASP.NET controls onto the page from the toolbox and set their properties:


    • Button control:

      • ID: Button1

      • Text: Show current time

    • Label control:

      • ID: Label1

      • Text: <clear the value>

  6. Switch to the Design view and double-click the Show current time button.
    • The user control's code behind file opens and creates the Button1_Click method.

  7. Enter the following code into the Button1_Click method:

    Label1.Text = DateTime.Now.ToString();
  8. Save the user control's files.

The control is now ready — it displays the current time when a user clicks the Show current time button. You do not need to compile the project — the system compiles user controls dynamically at run time.

 

Adding user controls onto portal pages

Log in to the Kentico administration interface and open the Pages application. Select the target page in the content tree and open the Design tab. There are two basic ways to integrate user controls:

The User control web part

  1. Add the User control web part onto the page template.
  2. Enter the relative path of your user control into the User control virtual path property.
    • For this example, type: ~/CorporateSite/GetTime.ascx
    • The ~ character represents the root of your web application.

  3. Click OK.

Directly in the markup of ASCX page layouts

Note: You can only add user controls to ASCX page layouts. This is not supported for HTML layouts.

  1. On the Design tab, right-click the green template header and select Edit layout in the menu.
  2. Register your user control at the start of the layout code:

    <%@ Register src="~/CorporateSite/GetTime.ascx" tagname="GetTime" tagprefix="custom" %> 
  3. Place the user control anywhere in the layout code:

    <custom:GetTime id="GetTime1" runat="server" />
  4. Click Save & Close.

If you now view the page on the live site, you can see the user control on the page. When you click the Show current time button, the page displays the current date and time next to the button.

Output of a custom user control on the live site

This example shows how to add custom code to portal engine websites through ASCX user controls built in Visual Studio. This user controls can contain any .NET controls, third-party controls or ADO.NET code that retrieves data from an external database.

User controls versus web parts

You can also insert custom code onto portal pages by creating your own web parts. Web parts are very similar to user controls, but with a built-in portal engine configuration interface. We recommend building web parts if you need easily re-usable and configurable user controls.

See: Developing web parts