51ºÚÁϲ»´òìÈ

DocumentationAEM 6.5User Guide

Externalizing URLs externalizing-urls

Last update: Wed Apr 17 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

In 51ºÚÁϲ»´òìÈ Experience Manager (AEM), the Externalizer is an OSGI service that lets you programmatically transform a resource path (for example, /path/to/my/page) into an external and absolute URL (for example, https://www.mycompany.com/path/to/my/page) by prefixing the path with a pre-configured DNS.

Because an instance cannot know its externally visible URL if it is running behind a web layer, and because sometimes a link has to be created outside of the request scope, this service provides a central place to configure those external URLs and build them.

This page explains how to configure the Externalizer service and how to use it. For more details, see the .

Configuring the Externalizer service configuring-the-externalizer-service

The Externalizer service lets you centrally define multiple domains that can be used to programmatically prefix resource paths. Each domain is identified by a unique name that is used to programmatically reference the domain.

To define a domain mapping for the Externalizer service:

  1. Navigate to the configuration manager via Tools, then Web Console, or enter:

    https://<host>:<port>/system/console/configMgr

  2. Click Day CQ Link Externalizer to open the configuration dialog box.

    note note
    NOTE
    The direct link to the configuration is https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl

    aem-externalizer-01

  3. Define a Domains mapping: a mapping consists of a unique name that can be used in the code to reference the domain, a space, and the domain:

    <unique-name> [scheme://]server[:port][/contextpath]

    Where:

    • scheme is http or https, but can also be ftp, and so on.

      • use https to enforce https links, if desired
      • it is used if the client code does not override the scheme when asking for externalization of a URL.

    • server is the host name (can be a domain name or ip address).

    • port (optional) is the port number.

    • contextpath (optional) is only set if AEM is installed as a webapp under a different context path.

    For example: production https://my.production.instance

    The following mapping names are predefined and must be set because AEM relies on them:

    • local - the local instance
    • author - the authoring system DNS
    • publish - the public facing website DNS
    note note
    NOTE
    A custom configuration lets you add a category, such as production, staging, or even external non-AEM systems such as my-internal-webservice. It is useful to avoid hardcoding such URLs across different places in a project’s codebase.

  4. Click Save to save your changes.

NOTE
51ºÚÁϲ»´òìÈ recommends that you add the configuration to the repository.

Using the Externalizer service using-the-externalizer-service

This section shows a few examples of how the Externalizer service can be used:

  1. To get the Externalizer service in a JSP:

    code language-java 
    Externalizer externalizer = resourceResolver.adaptTo(Externalizer.class);

  2. To externalize a path with the ‘publish’ domain:

    code language-java 
    String myExternalizedUrl = externalizer.publishLink(resolver, "/my/page") + ".html";

    Assuming the domain mapping:

    • publish https://www.website.com

    myExternalizedUrl ends up with the value:

    • https://www.website.com/contextpath/my/page.html

  3. To externalize a path with the ‘author’ domain:

    code language-java 
    String myExternalizedUrl = externalizer.authorLink(resolver, "/my/page") + ".html";

    Assuming the domain mapping:

    • author https://author.website.com

    myExternalizedUrl ends up with the value:

    • https://author.website.com/contextpath/my/page.html

  4. To externalize a path with the ‘local’ domain:

    code language-java 
    String myExternalizedUrl = externalizer.externalLink(resolver, Externalizer.LOCAL, "/my/page") + ".html";

    Assuming the domain mapping:

    • local https://publish-3.internal

    myExternalizedUrl ends up with the value:

    • https://publish-3.internal/contextpath/my/page.html

  5. You can find more examples in the .

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2