Skip to main content

XTM Connect – Adobe Experience Manager 2.10

XTM Workbench Path variable customization for Visual mode

XTM Visual mode can be used to generate a preview of source and target file content, in XTM Workbench. This is only useful for certain types of content, such as graphics with texts on them, so Visual mode is not used by every Linguist (or Project manager).

Note

Visual mode is not available by default: it must be enabled by XTM International Support.

To request support, see Contacting XTM Support (AEM 6.5).

This topic describes an issue that can occur when a preview package is received in XTM Cloud, as part of a translation project (and suggests ways to resolve the issue):

  • The resources that the preview package contains (contents such as image files) are extracted to a folder which is stored on the XTM Cloud server.

  • (Translatable) content source files in the project contain paths to the resources mentioned above.

  • When the preview package contents are extracted to a folder on the XTM Cloud server, these paths are modified automatically, so they are sometimes (but not always) no longer valid.

  • To resolve this issue, when it occurs, the XTM Workbench Path variable, $WORKBENCH_PATH, can be used to specify the location of the folder that contains the resources mentioned above. This folder is on the XTM Cloud server. When a Preview is generated for a project, in XTM Workbench, the resources can then be accessed and displayed correctly.

  • The XTM Workbench Path variable, $WORKBENCH_PATH, can be set in the OSGi configuration file for XTM Workbench Visual mode, in your AEM as a Cloud Service instance.

Below, you will find details of when and how to set the $WORKBENCH_PATH variable. This is not always necessary, as the first example below shows. The second example describes a case in which a customer might need to set the $WORKBENCH_PATH variable.

Example: resource path updated correctly on extraction to folder on the XTM Cloud server

This example shows what should happen, in a normal case. This involves an ordinary page which does not contain any dynamic elements such as image that are loaded in an asynchronous way: the path for a resource is rendered on the backend. Consequently, the file-processing mechanism that handles the preview package, when it is received, is able to update the path to point to XTM Workbench.

In the code below, taken from a fictitious file called "index.html", there is a resource (image file) called "example.png":

<html>
...
<body>
  <img src="/content/dam/wknd/en/example.png"/>
</body>
</html>

When the "index.html" is saved to the XTM Cloud server, the path to the "example.png" file is updated:

<html>
...
<body>
  <img src="/workbench/web/preview-file?_s=41cbc94c65e34d09ac837d8361e3daad&fileName=content%2Fdam%2Fwknd%2Fem%2Fexample.png"/>
</body>
</html>

Example: resource path cannot be updated on extraction to folder on the XTM Cloud server

The example below shows what will happen if no path (= "src") is specified for a resource such as "Example.png" (specified in the "img" entry in line 4.). Then, the resource cannot be rendered on the backend and the file-processing mechanism that handles the preview package, when it is received, is unable to update the path to point to XTM Workbench.

<html>
...
<body>
  <img id="img"/>
  <script>
    document.querySelector('#img').setAttribute('src', '/content/dam/wknd/en/example.png')
  </script>
</body>
</html>

There are two issues that prevent the "Example.png" image file from being displayed in Preview mode, in XTM Workbench:

  1. The image path in the JS code ("'/content/dam/wknd/en/example.png')") will not be recognized by the default reference provider.

    To resolve this, a Custom HTML reference patterns regex setting could be used to include resources on this path in the Preview display. See Custom HTML reference patterns in Configuring preview filters for Visual mode in AEM 6.5.

  2. The image path in the JS code, (as already mentioned, "'/content/dam/wknd/en/example.png')"), needs to be modified to the following, to enable the "Example.png" image file to be displayed in Preview mode, in XTM Workbench:

     /workbench/web/preview-file?_s=41cbc94c65e34d09ac837d8361e3daad&fileName=content%2Fdam%2Fwknd%2Fem%2Fexample.png

    In the image path above, we see that a prefix containing an XTM Workbench resource endpoint has been added to the original path. The path itself is part of a query parameter correlated with the user session.

    However, given that the example code injects the path via JS, this is bound to fail. The path will not be processed and rewritten. To resolve this, a special custom variable called $WORKBENCH_PATH can be used. For details, see Setting the $WORKBENCH_PATH variable, below.

Setting the $WORKBENCH_PATH variable

A pair of preview filter regex settings could be added to the OSGi Preview mode configuration file to adjust the image path above, so that resources on that path are included in the Preview display.

The path (in this case) needs to be changed from:

replacement.match.patterns=('src', ')(.+)

to:

replacement.strings=$1\${WORKBENCH_PATH}$2

For details, see Replacement match patterns and Replacement strings in Configuring preview filters for Visual mode in AEM 6.5.

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: \$.

If you configure the preview filter regex settings described above, and they are applied when a preview package is received in XTM Cloud, the resource paths should be adjusted to ensure the resources can be displayed in XTM Workbench, in Preview mode.

In that case, the preview file should contain markup like this:

<html>
...
<body>
  <img id="img"/>
  <script>
    document.querySelector('#img').setAttribute('src', '$WORKBENCH_PATH/content/dam/wknd/en/example.png')
  </script>
</body>
</html>

Result: imported resources in preview packages will be displayed correctly in XTM Workbench,