---
title: Adding custom code to portal engine page templates
related:
  - https://docs.kentico.com/k11/developing-websites/developing-websites-using-the-portal-engine.md
  - https://docs.kentico.com/k11/custom-development/developing-web-parts.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).

The most direct way to insert custom code into a [portal engine-based website](https://docs.kentico.com/k11/developing-websites/developing-websites-using-the-portal-engine.md) 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](https://docs.kentico.com/k11/deploying-websites.md) 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**: 
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:

   ```csharp

   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](https://docs.kentico.com/k11/developing-websites/developing-websites-using-the-portal-engine/using-and-configuring-web-parts.md) 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:** **Note**: You can only add user controls to **ASCX** [page layouts](https://docs.kentico.com/k11/developing-websites/developing-websites-using-the-portal-engine/editing-page-layouts.md). 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:

   ```html

   <%@ Register src="~/CorporateSite/GetTime.ascx" tagname="GetTime" tagprefix="custom" %> 

   ```
3. Place the user control anywhere in the layout code:

   ```html

   <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](https://docs.kentico.com/docsassets/k11/adding-custom-code-to-portal-engine-page-templates/image.png "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.

> **Tip:** **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](https://docs.kentico.com/k11/custom-development/developing-web-parts.md)