Function mapArtificialXLinkRole

Maps artificial xlink:role according to given pre-processors.

What are artificial xlink:role attributes?

Despite for xlink:show="other" the attribute xlink:role is expected to be unset, when it comes to representing the attributes as target attribute in view layers of CKEditor 5.

Thus, if xlink:show is different to "other", but xlink:role is set, this attribute is denoted as being artificial.

What happens to an artificial xlink:role attribute by default?

By default, such an attribute is encoded into the target attribute in a bijective manner, which is, that from the given target attribute value in view layers, the corresponding xlink:show and xlink:role values can still be determined.

When to use mapArtificialXLinkRole?

As the CoreMedia Rich Text 1.0 DTD does not define an artificial xlink:role as invalid, it is perfectly fine, if xlink:role is used to hold data unrelated to the target behavior.

Creating a rule configuration by this factory method and applying it to your custom rules configuration provides the opportunity to store such xlink:role in a different attribute.

How to deal with toData processing?

If you stored the role in a different attribute, you should restore its value here and return it.

Caveat:

Editors may trigger the default mapping to handle xlink:role even for xlink:show states different to other, for example, if setting target in view layers to _embed_someRole. In these cases, the default processing will override any xlink:role created by the mapping generated here.

This is assumed to be a very rare corner-case, though.

The all defaults scenario:

If you just invoke mapArtificialXLinkRole() it will, by default, create a rule configuration that strips any artificial roles in toView mapping and of course does not apply any xlink:role in its toData mapping.

Example: Store in class attribute:

The following example demonstrates how to possibly store an artificial role within the class attribute of the anchor element:

mapArtificialXLinkRole({
  toView: (element, role) => {
    // Class token must not contain spaces.
    const sanitizedRole = role.replaceAll(/\s/g, "_");
    element.classList.add(`role_${sanitizedRole}`);
  },
  toData: (element) => {
    const matcher = /^role_(\S*)$/;
    const matchedClasses: string[] = [];
    let role: string | undefined;
    for (const cls of element.classList) {
      const match = cls.match(matcher);
      if (match) {
        const [matchedCls, matchedRole] = match;
        // The last matched role will win.
        role = matchedRole;
        // Used to clean any class, that represents a role.
        matchedClasses.push(matchedCls);
      }
    }
    // Clean-up any matched classes and possibly left-over `class=""`.
    element.classList.remove(...matchedClasses);
    if (element.classList.length === 0) {
      element.removeAttribute("class");
    }
    // If falsy, `xlink:role` will not be added.
    return role;
  },
})
Copy

Note for Custom Attributes:

For any other attribute you have chosen to store the role in, ensure, to register it as belonging to a link, so that, for example, removing the link will also clean up the role-representing attribute.