Experience Fragments experience-fragments

The Basics the-basics

An Experience Fragment is a group of one or more components including content and layout that can be referenced within pages.

An Experience Fragment Master, or Variant, or both, uses:

Because there is no /libs/cq/experience-fragments/components/xfpage/xfpage.html, it reverts to

The Plain HTML Rendition the-plain-html-rendition

Using the .plain. selector in the URL, you can access the plain HTML rendition.

This rendition is available from the browser. However, its primary purpose is to allow other applications (for example, third-party web apps, custom mobile implementations) to access the content of the Experience Fragment directly, using only the URL.

The plain HTML rendition adds the protocol, host, and context path to paths that are:

For example:

.../brooklyn-coat/master.plain.html

The plain rendition selector uses a transformer as opposed to additional scripts. The Sling Rewriter is used as the transformer. This transformer is configured at the following:

Configuring the HTML rendition generation configuring-html-rendition-generation

The HTML rendition is generated using the Sling Rewriter Pipelines. The pipeline is defined at /libs/experience-fragments/config/rewriter/experiencefragments. The HTML Transformer supports the following options:

Adobe recommends configuring the rewriter using an overlay. See Overlays in AEM as a Cloud Service.

Templates for Experience Fragments templates-for-experience-fragments

When developing a new template for Experience Fragments, you can follow the standard practices for an editable template.

To create an Experience Fragment template that is detected by the Create Experience Fragment wizard, you must follow one of these rule sets:

Components for Experience Fragments components-for-experience-fragments

Developing components for use with/in Experience Fragments follow standard practices.

The only additional configuration is to ensure that the components are allowed on the template. This allowance is achieved with the Content Policy.

The Experience Fragment Link Rewriter Provider - HTML the-experience-fragment-link-rewriter-provider-html

In AEM, you have the possibility to create Experience Fragments. An Experience Fragment:

One of the use cases for such groups is for embedding content in third-party touchpoints, such as Adobe Target.

Default Link Rewriting default-link-rewriting

Using the Export to Target feature, you can:

This feature can be enabled on an author instance of AEM. It requires a valid Adobe Target Configuration, and configurations for the Link Externalizer.

The Link Externalizer is used to determine the correct URLs needed when creating the HTML version of the Target Offer, which is then sent to Adobe Target. This process is necessary as Adobe Target requires that all links inside the Target HTML Offer can be publicly accessed. It means that any resources the links reference, and the Experience Fragment itself, must be published before they can be used.

By default, when you construct a Target HTML Offer, a request is sent to a custom Sling selector in AEM. This selector is called .nocloudconfigs.html. As its name implies, it creates a plain HTML rendering of an Experience Fragment, but does not include cloud configurations (which would be superfluous information).

After you generate the HTML page, the Sling Rewriter pipeline is modified to the output:

When using an out-of-the-box implementation, the process described above should be sufficient to generate the Target Offer from the Experience Fragment and then export it to Adobe Target. However, there are some use cases that are not accounted for in this process. Some of these cases that are not account for include the following:

For these use cases, AEM provides the Link Rewriter Provider Interface.

Link Rewriter Provider Interface link-rewriter-provider-interface

For more complicated cases, not covered by the default, AEM offers the Link Rewriter Provider Interface. This interface is a ConsumerType interface that you can implement in your bundles, as a service. It bypasses the modifications AEM performs on internal links of an HTML offer as rendered from an Experience Fragment. This interface lets you customize the process of rewriting internal HTML links to align with your business needs.

Examples of use cases for implementing this interface as a service include:

The Link Rewriter Provider Interface ( ExperienceFragmentLinkRewriterProvider) is as follows:

public interface ExperienceFragmentLinkRewriterProvider {

    String rewriteLink(String link, String tag, String attribute);

    boolean shouldRewrite(ExperienceFragmentVariation experienceFragment);

    int getPriority();

}

How to use the Link Rewriter Provider Interface how-to-use-the-link-rewriter-provider-interface

To use the interface, you first must create a bundle containing a new service component that implements the Link Rewriter Provider interface.

This service is used to plug into the Experience Fragment Export to Target rewriting so it can have access to the various links.

For example, ComponentService:

import com.adobe.cq.xf.ExperienceFragmentLinkRewriterProvider;
import com.adobe.cq.xf.ExperienceFragmentVariation;
import org.osgi.service.component.annotations.Service;
import org.osgi.service.component.annotations.Component;

@Component
@Service
public class GeneralLinkRewriter implements ExperienceFragmentLinkRewriterProvider {

    @Override
    public String rewriteLink(String link, String tag, String attribute) {
        return null;
    }

    @Override
    public boolean shouldRewrite(ExperienceFragmentVariation experienceFragment) {
        return false;
    }

    @Override
    public int getPriority() {
        return 0;
    }

}

For the service to work, there are now three methods that must be implemented inside the service:

shouldRewrite shouldrewrite

Indicate to the system whether it must rewrite the links when a call is made for Export to Target on a certain Experience Fragment variation. You can implement the following method:

shouldRewrite(ExperienceFragmentVariation experienceFragment);

For example:

@Override
public boolean shouldRewrite(ExperienceFragmentVariation experienceFragment) {
    return experienceFragment.getPath().equals("/content/experience-fragment/master");
}

This method receives, as a parameter, the Experience Fragment Variation that the Export to Target system is rewriting.

In the example above, you want to rewrite:

Any other Experience Fragments that pass through the Export to Target system are ignored and not affected by changes implemented in this Service.

rewriteLink rewritelink

For the Experience Fragment variation impacted by the rewriting process, it then proceeds to let the service handle the link rewriting. Every time a link is encountered in the internal HTML, the following method is invoked:

rewriteLink(String link, String tag, String attribute)

As input, the method receives the parameters:

For example, if the Export to Target system is processing this element, you can define CSSInclude as:

<link rel="stylesheet" href="/etc.clientlibs/foundation/clientlibs/main.css" type="text/css">

The call to the rewriteLink() method is done using these parameters:

rewriteLink(link="/etc.clientlibs/foundation/clientlibs/main.css", tag="link", attribute="href" )

When you create the service, your decisions are based on the given input, and then rewrite the link accordingly.

For the example, you want to remove the /etc.clientlibs part of the URL and add the appropriate external domain. To keep things simple, consider that you have access to a Resource Resolver for your service, as in rewriteLinkExample2:

private ResourceResolver resolver;

private Externalizer externalizer;

@Override
public String rewriteLink(String link, String tag, String attribute) {

    // get the externalizer service
    externalizer = resolver.adaptTo(Externalizer.class);
    if(externalizer == null) {
        // if there was an error, then we do not modify the link
        return null;
    }

    // remove leading /etc.clientlibs from resource link before externalizing
    link = link.replaceAll("/etc.clientlibs", "");

    // considering that we configured our publish domain, we directly apply the publishLink() method
    link = externalizer.publishLink(resolver, link);

    return link;
}

Priorities - getPriority priorities-getpriority

It is not uncommon to need several services to cater for different kinds of Experience Fragments, or even to have a Generic Service that handles externalizing and mapping for all Experience Fragments. In these cases, conflicts about which service to use might arise, so AEM provides the possibility to define Priorities for different services. The priorities are specified by using the method:

This method allows the use of several services where the shouldRewrite() method returns true for the same Experience Fragment. The service that returns the highest number from its getPriority()method is the service that handles the Experience Fragment Variation.

As an example, you can have a GenericLinkRewriterProvider that handles the basic mapping for all Experience Fragments and when the shouldRewrite() method returns true for all Experience Fragment Variations. For several specific Experience Fragments, you may want special handling, so in this case, you can provide a SpecificLinkRewriterProvider for which the shouldRewrite() method returns true only for some Experience Fragment Variations. To make sure that SpecificLinkRewriterProvider is chosen to handle those Experience Fragment Variations, it must return in its getPriority() method a higher number than GenericLinkRewriterProvider.