Declarative Transformations API

[arumsey]

Description

Introduce a higher-level Importer API that provides a declarative approach to transformations

• offer a clearer API for developers to access that follows a consistent pattern
• define a no-code configuration for most common transformation phases
• allow for block-level transformation extensions
• provide default metadata handling to avoid code duplication
• opens the door for easier transformation automation
• separates block transformations into their own modules

Related Issue

Fixes: #355

Dependent on: https://github.com/adobe/helix-importer/pull/351

Motivation and Context

The AEM Importer import scripts are a powerful tool for manipulating a DOM into an Edge Delivery compatible format. These scripts however need to be written by developers with a high degree of knowledge of DOM APIs. The addition of a declarative transformation API on top of the existing low-level import script opens mor doors for less technical users to begin importing content by simply defining a collection of CSS selectors. Additionally, a no-code approach to defining import rules also allows them to be more easily created by automation and for them to be POSTED to a service to enable long running imports.

This feature does not introduce any breaking changes to the AEM Importer. The import script however can now be a JSON file or a JS object. This JSON structure (the ruleset) can then be passed to a createImporter factory that generates a valid import script. The Transformer class is able to consume a ruleset and runs through a series of phases to clean up the DOM and then generate any desired blocks through the use of CSS selector logic.

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• [x] I have signed the Adobe Open Source CLA.
• [ ] My code follows the code style of this project.
• [x] My change requires a change to the documentation.
• [ ] I have updated the documentation accordingly.
• [ ] I have read the CONTRIBUTING document.
• [ ] I have added tests to cover my changes.
• [ ] All new and existing tests passed.

[arumsey]

Import Ruleset Example

{
  "root": "main",
  "cleanup": {
    "start": [
      ".cookie-status-message",
      ".breadcrumbs",
      ".messages",
      ".sidebar",
      "h1 + ul.instruments-menu",
      "h1"
    ]
  },
  "blocks": [
    {
      "type": "metadata",
      "target": "append",
      "params": {
        "metadata": {
          "keywords": "[name=\"keywords\"]",
          "Publication Date": "[property=\"og:article:published_time\"]",
          "category": [
            [":scope:has(.is-blog .post-list) .webinar-speaker-img", "Webinars"],
            [":scope:has(.is-blog .post-list)", ""]
          ],
          "series": [
            [":has(.is-blog .post-list) .webinar-speaker-img", ""]
          ],
          "eventDate": [
            [":has(.is-blog .post-list) .webinar-speaker-img", ""]
          ],
          "speakers": [
            [":has(.is-blog .post-list) .webinar-speaker-img", ".webinar-speaker-img + strong"]
          ]
        }
      }
    },
    {
      "type": "overview",
      "selectors": [
        ".entry div:has(div > p > img)",
        ".entry > div > div:first-of-type:has(div > img)"
      ],
      "params": {
        "cells": [
          ["div:has(p > img)", ":scope > div:last-child"]
        ]
      }
    },
    {
      "type": "columns",
      "selectors": [
        ".entry > .about-content",
        ".desc-img-wrapper:has(> :nth-child(2):last-child)"
      ]
    }
  ]
}