Definitions app

The Definitions app is the single place to find all definitions loaded by Magnolia through the Registry API. The app displays active definitions from all sources (YAML, JCR config workspace, Code, and in-memory) and origins (classpath, file system, and JCR resources workspace).

Light development introduced an additional configuration source in Magnolia and the app provides an overview of both JCR and file-based definitions. At a glance, back and front-end developers can see the definition sources.

In the Definitions app users can:

The app also shows definition decorations and configuration errors.

Definition types

The app includes all definitions that are bound to info.magnolia.config.registry.Registry (for example, info.magnolia.rendering.template.registry.TemplateDefinitionRegistry).

List of definition types

Searching and filtering definitions

The in-app search field and filters allow you to quickly find what you are looking for.

In-app search in the Definitions app is case-sensitive.

The search field searches through parent node names in the Title column. In addition, the following filters are available:

Results are presented in a tree view display. This is to ensure you can understand in which folder the item you’ve searched for is located.

Viewing definitions

You can expand any definition node to view a representation of the full configuration.

Accessing definitions

Dedicated actions allow you to access a definition for editing in either the Resource files or Configuration app:

  • Show in Resources app displays for file-based definitions. The action opens the file in read only mode in the Resource files app. You can choose to hotfix the definition in the app or edit it on the file system.

  • Show in Configuration app displays for JCR-based definitions. The action opens the definition in the Configuration app where you can edit the definition in the JCR.

All YAML definitions display in the Origin column as file. The origin of these definitions could be the file system or the classpath. You can see each origin in the Resource Files app.

Using the Registry API

The Definitions app provides a visual interface to explore definitions. You can also access these definitions programmatically through the Registry API in your Java code.

Basic usage pattern

All definition registries follow the same pattern: get the registry component and call getAllDefinitions() to retrieve an iterator.

// Generic pattern for accessing any registry
Iterator<DefinitionType> iterator = Components.getComponent(DefinitionTypeRegistry.class).getAllDefinitions().iterator();
while (iterator.hasNext()) {
    DefinitionType definition = iterator.next();
    // Work with the definition
}

Common registry examples

Templates

import info.magnolia.rendering.template.registry.TemplateDefinitionRegistry;
import info.magnolia.rendering.template.TemplateDefinition;

Iterator<TemplateDefinition> templateDefinitionIterator =
    Components.getComponent(TemplateDefinitionRegistry.class).getAllDefinitions().iterator();
while (templateDefinitionIterator.hasNext()) {
    TemplateDefinition template = templateDefinitionIterator.next();
    System.out.println("Template: " + template.getName());
}

Dialogs

import info.magnolia.ui.dialog.registry.DialogDefinitionRegistry;
import info.magnolia.ui.dialog.DialogDefinition;

Iterator<DialogDefinition> dialogDefinitionIterator =
    Components.getComponent(DialogDefinitionRegistry.class).getAllDefinitions().iterator();
while (dialogDefinitionIterator.hasNext()) {
    DialogDefinition dialog = dialogDefinitionIterator.next();
    System.out.println("Dialog: " + dialog.getName());
}

Apps

import info.magnolia.registry.AppRegistry;
import info.magnolia.ui.api.app.AppDescriptor;

Iterator<AppDescriptor> appIterator =
    Components.getComponent(AppRegistry.class).getAllDefinitions().iterator();
while (appIterator.hasNext()) {
    AppDescriptor app = appIterator.next();
    System.out.println("App: " + app.getName());
}

Sites

import info.magnolia.module.site.registry.SiteDefinitionRegistry;
import info.magnolia.module.site.SiteDefinition;

Iterator<SiteDefinition> siteIterator =
    Components.getComponent(SiteDefinitionRegistry.class).getAllDefinitions().iterator();
while (siteIterator.hasNext()) {
    SiteDefinition site = siteIterator.next();
    System.out.println("Site: " + site.getName());
}

Common registry classes

The following table lists the most commonly used registry classes and their corresponding definition types:

Registry class Definition type Use case

TemplateDefinitionRegistry

TemplateDefinition

Page and component templates

DialogDefinitionRegistry

DialogDefinition

Content editing dialogs

AppRegistry

AppDescriptor

Magnolia apps

SiteDefinitionRegistry

SiteDefinition

Site configurations

ThemeDefinitionRegistry

ThemeDefinition

Frontend themes

FieldTypeDefinitionRegistry

FieldTypeDefinition

Custom field types

RendererDefinitionRegistry

RendererDefinition

Template renderers

VirtualUriMappingRegistry

VirtualUriMappingDefinition

URL mappings

Accessing specific definitions

To get a specific definition instead of all definitions, most registries provide methods to get definitions by name:

// Get a specific template by name
TemplateDefinitionRegistry templateRegistry = Components.getComponent(TemplateDefinitionRegistry.class);
TemplateDefinition specificTemplate = templateRegistry.getDefinition("my-template-name");

// Get a specific dialog by name
DialogDefinitionRegistry dialogRegistry = Components.getComponent(DialogDefinitionRegistry.class);
DialogDefinition specificDialog = dialogRegistry.getDefinition("my-dialog-name");
The getDefinition() methods may return null if the definition doesn’t exist. Always check for null before using the result.

Configuration

The app itself is configured in /definitions-app/apps/definitions-app.yaml. It is NOT advisable to make any changes to this configuration file.

Decorated definitions

Decorated definitions are marked in the Decorated column. The Show definition decorators action opens the Applied definition decorators popup which shows the source file and the decorated path of each decorator.

Interpolated variables

If a definition contains an interpolated variable, its value is hidden in the Definitions app. To find out the variable’s value, you can retrieve it from the About app Config Info tab.

Definition errors

The app makes it easy to find problematic definitions via either the Problem severity column in the browser or the Problems sub app.

The following deprecated definitions are shown:

Deprecations whose origin is in Magnolia code are not displayed in the Problems sub app.

  • Deprecated classes used by any definition.

  • Deprecated or non-existing templates used by block definitions.

  • Deprecated or non-existing page template definitions referenced from site definitions.

  • Deprecated or non-existing theme definitions referenced from site definitions.

  • Template references:

    • Deprecated or non-existing dialogs.

    • Deprecated or non-existing component definitions used in page definitions.

    • Non-existing template script paths.

    • Configured but non-existing renderer.

Filtering project modules

You can configure the app to focus on specific modules. This is useful during migrations or heavy development phases to filter out noise from standard Magnolia modules and view only definitions or problems related to your custom code.

To enable this feature, you must define the list of modules you want to isolate in the configuration file.

  1. Open or create the config.yaml file located at the root of the module: /definitions-app/config.yaml.

  2. Add the projectModules property with a list of your module names.

projectModules:
  - security-app
  - my-custom-app
  - my-mobile-app

Once configured, a Filter project modules checkbox appears in the filter bar of both the Definitions and Problems tabs in the app.

  • Unchecked (default): The app displays definitions and problems from all modules in the system.

  • Checked: The app displays only the items belonging to the modules listed in your config.yaml.

  • Tooltip: Hovering over the checkbox displays the list of currently configured project modules for reference.

Filtering project modules

You can configure the app to focus on specific modules. This is useful during migrations or heavy development phases to filter out noise from standard Magnolia modules and view only definitions or problems related to your custom code.

To enable this feature, you must define the list of modules you want to isolate in the configuration file.

  1. Open or create the config.yaml file located at the root of the module: /definitions-app/config.yaml.

  2. Add the projectModules property with a list of your module names.

projectModules:
  - security-app
  - my-custom-app
  - my-mobile-app

Once configured, a Filter project modules checkbox appears in the filter bar of both the Definitions and Problems tabs in the app.

  • Unchecked (default): The app displays definitions and problems from all modules in the system.

  • Checked: The app displays only the items belonging to the modules listed in your config.yaml.

  • Tooltip: Hovering over the checkbox displays the list of currently configured project modules for reference.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules