---
title: Define macro fields
related:
  - https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions/macro-syntax.md
  - https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions/macro-resolvers.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).

Macro fields need to be defined per [macro resolver](https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions/macro-resolvers.md). Resolvers  are system components that ensure the processing of macros. By adding fields into specific resolvers, you make them available for the functionality handled by that particular resolver.

You can register macro fields into resolvers:

- [globally](#definemacrofields-global) – makes the fields available everywhere the particular resolver is used (see the [resolver reference](https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions/macro-resolvers.md) for details)
- [per administration UI page](#definemacrofields-perpage) – makes the fields resolve only within specific [administration UI pages](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-pages.md).

### Global registration 

Global registration makes the macro field available everywhere the particular resolver is used.

Register global fields during application startup:

1. Create a [custom module class](https://docs.kentico.com/documentation/developers-and-admins/customization/run-code-on-application-startup.md).
   - See [Integrate custom code](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md) for best practices related to adding custom code to Xperience.
2. Override the module's `OnInit` method.
3. Obtain an instance of the register that corresponds to the macro resolver you want to extend (e.g., `UIFormMacroSourceRegister` for the resolver responsible for the UI forms of [object types](https://docs.kentico.com/documentation/developers-and-admins/customization/object-types.md)).
   - See the [macro resolvers reference](https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions/macro-resolvers.md) to see which registration classes belong to specific resolvers.

```csharp
public class MacroFieldsRegistrationModule : Module
{
    ...

    // Contains initialization code that is executed when the application starts
    protected override void OnInit()
    {
        base.OnInit();

        // Gets an instance of UIFormMacroSourceRegister
        var macroRegister = UIFormMacroSourceRegister.Instance;
    }
}
```

4. Call `RegisterMacroField` on the macro register instance. The method takes a `MacroField` object which requires the following parameters:
   - **name** – used to access the field from within macro expressions. For example: `{% MyMacroField %}`
   - **valueEvaluator** – a lambda expression with the logic to execute when the field is evaluated. Must return a value supported by macro expressions (scalars, [object types](https://docs.kentico.com/documentation/developers-and-admins/customization/object-types.md), collections based on `IEnumerable`).

```csharp
protected override void OnInit()
{
    base.OnInit();

    // Gets an instance of UIFormMacroSourceRegister
    var macroRegister = UIFormMacroSourceRegister.Instance;

    // Registers a new "DefaultAdministrator" macro field that returns a UserInfo object that corresponds to the default 'administrator' account
    macroRegister.RegisterMacroField(new MacroField("DefaultAdministrator", () => UserInfo.Provider.Get("administrator")));
}
```

The macro field is now registered and available everywhere the extended resolver is used.

```ksharp title="Example usage"
{% DefaultAdministrator.FirstName %}
```

### UI page registration 

UI page-specific field registration makes macro fields available only for specific pages in the administration interface.

The registration is done using [UI page extenders](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-pages/ui-page-extenders.md) and the dedicated `RegisterMacroField` method.

1. Create a new page extender and override the `ConfigurePage` method.
2. Within the override, call `RegisterMacroField`. The method takes a `MacroField` object which requires the following parameters:
   - **name**  – used to access the field from within macro expressions. For example: `{% MyMacroField %}`
   - **valueEvaluator** – a lambda expression with the logic to execute when the field is evaluated. Must return a value supported by macro expressions (scalars, [object types](https://docs.kentico.com/documentation/developers-and-admins/customization/object-types.md), collections based on `IEnumerable`).

```csharp
public override Task ConfigurePage()
{
    // Registers a new 'DefaultAdministrator' field that is only resolvable on the extended page
    Page.RegisterMacroField(new CMS.MacroEngine.MacroField("DefaultAdministrator", () => UserInfo.Provider.Get("administrator")));

    return base.ConfigurePage();
}
```

The macro field is now registered and available for fields on the given page in the administration.

```ksharp title="Example usage"
{% DefaultAdministrator.FirstName %}
```