Skip to main content

XTM Connect – Adobe Experience Manager 2.10

Configuring preview filters for Visual mode in AEM 6.5

Note

If you are using AEM as a Cloud Service (AEMaaCS), see Configuring preview filters for Visual mode in AEMaaCS.

A problem can occur in Visual mode if a source content page contains in-line references to files that should not be sent to XTM Cloud with that source content page, and used for generating a preview. Sometimes, It is also necessary to be prevent certain types of source content file from being sent to XTM Cloud for translation.

Example

A source content page contains a reference to a nested REACT application that relies on dynamic data pulled from a REST API. This prevents the preview from being displayed. In such a case, you might need to filter out the scripts that break the page rendering.

Excluding unwanted file types or files

To resolve problems of this kind, you can define reference filters to exclude specific file types, or files in specific locations, so they are not sent to XTM Cloud with or as translatable content. To do so, use regular expressions (also known as "regex").

Important

We strongly recommend that you use OSGi configuration files to define these reference filters, instead of manual configuration, whenever possible. For details, see OSGi Configuration with configuration files (Adobe Inc. AEM 6.5 online help).

The next procedure nevertheless describes the manual procedure anyway, for completeness.

Note

Escaping reserved characters in regex strings

In any OSGi Preview mode configuration file that you create, ensure that you escape reserved characters correctly.

Example: the $ sign is a reserved character and must be escaped with a backslash, like this: \$.

Regex patterns are very powerful and can be very greedy too. When you define them, ensure that they are strict enough and do not select too many items. We strongly advise that you work on Preview Configuration in a localhost environment, to ensure a swift development phase. Working with regex can mean a lot of trial and error.

To configure preview filters for Visual mode manually:
  1. On your localhost, in your instance of Adobe Experience Manager 6.5, open the OSGi Console ((access /system/console/bundles) path).

  2. Select Configuration Manager (system/console/configMgr path). The Configuration Manager is displayed in the Configuration tab screen.

  3. To find the XTM Preview Configuration section, search for service PID "com.xtm.aem.services.translation.preview.XtmPreviewConfig". Then select it, to edit the configuration values in it. You can make five different sets of settings, described in the table below:

    • Replacement match patterns: use this setting to define replacement match patterns with which to identify content that is to be changed in preview files, when they are received in XTM Cloud.

    • Replacement strings: this setting works with the previous setting: use this setting to define strings to replace the match patterns defined in the previous setting with specific content, in preview files that have been received in XTM Cloud.

    • Reference filters: to ensure that only relevant reference files are sent to XTM Cloud, use this setting to filter in-line references to other files, in source content files. For details, see the Reference filter Preview filter type in the table below.

    • Custom HTML reference patterns: use these patterns to define custom regular expressions that extend a preview package by including additional assets. You can specify asset types and locations to be included. For details, see the Custom HTML reference pattern Preview filter type in the table below.

    • Force include client library categories: use this setting to specify whether particular client libraries should always be included in preview packages. For details, see the Force include client library categories Preview filter type in the table below.

Preview filter settings

Warning

In some of the settings described below, you can enter regular expressions (regexs). If you define an invalid regular expression, it will not be taken into account. For troubleshooting, you will find a WARN message about it in the logs.

Make these settings, if required:

Entry field

OSGI field name

Description

Examples

Replacement match patterns

replacement.match.patterns

  1. In the Replacement match patterns field, enter regular expressions (regex) to identify particular content strings, received in a file that will be used for Visual mode. These strings will be replaced by the corresponding Replacement strings, specified in the next setting.

    If you enter more than one regular expression, separate them with a blank space.

  2. Select Save.

    Result: any preview filter regular expressions you have entered are saved and will now be applied whenever Translation requesters send source content pages to XTM Cloud, for translation. When they do so, the contents of preview files will be adjusted in accordance with the regular expressions specified in this setting and the Replacement strings specified in the next setting, below.

See XTM Workbench Path variable customization for Visual mode.

Replacement strings

replacement.strings

  1. In the Replacement strings field, enter the required text strings.

    If you enter more than one string, separate them with a blank space. A string cannot contain blank spaces.

  2. The strings will be used to replace the existing strings, in content in fetched preview files, that have been specified in the Replacement match patterns setting described above.

See XTM Workbench Path variable customization for Visual mode.

Reference filters

reference.filters

  1. In the Reference filters field, enter the required regular expressions.

    If you enter more than one regular expression, separate them with a blank space.

    They will be used to filter in-line references to other files, in source content files, and ensure that only relevant reference files are sent to XTM Cloud. You can exclude these files by type and/or location.

  2. Select Save.

    Result: any preview filter regular expressions you have entered are saved and will now be applied whenever Translation requesters send source content pages to XTM Cloud, for translation. When they do so, a preview package containing only relevant reference files is generated and sent with the appropriate source content pages.

Reference filter examples
  • To exclude all reference files located in a folder called /c-etc/, use the regular expression .+\/c-etc\/.+. Note that this deliberately has a full stop at the start, but does not end with a full stop. (Ignore the seecond full stop, which is not in bold text, at the end of the sentence.)

  • To exclude all JavaScript files, no matter where they are located, use the regular expression +\.js. This regular expression uses the file extension (.js) to identify JavaScript files.

Custom HTML reference patterns

custom.html.reference.patterns

  1. In the Custom HTML reference patterns field, enter the required regular expressions.

    If you enter more than one regular expression, separate them with a blank space.

    They will be used to filter source content files and ensure that only the relevant source content files are sent to XTM Cloud. You can include these files by type and/or location.

  2. Select Save.

    Result: any custom HTML reference pattern regular expressions you have entered are saved and will now be applied whenever Translation requesters send source content pages to XTM Cloud, for translation. When they do so, a project package containing only the relevant source files is generated and sent to XTM Cloud.

Custom HTML reference pattern filter example

  • To include graphic files with a particular format, located in the jcr_content folder, use the regular expression jcr_content/.+?\.(jpeg|jpg|png).

    Note how the graphic file extensions have been listed alphabetically and then separated by a pipe character (|).

Force inclusion of specific client library categories

force.include.client.library.categories

Client libraries are grouped in categories. To specify that the libraries in a particular category must always be included in preview packages, enter their names in this setting. They will then be included, regardless of whether they are referenced in the markup or not.

/

Applying the preview filter settings

To activate the settings described above, enter the following line in the relevant OSGI file for XTM preview settings:

Service PID: com.xtm.aem.services.translation.preview.XtmPreviewConfig

Note

For details of other Visual mode-related topics, see Configuring Visual mode in AEM 6.5.