Skip to content

3.11.0

Choose a tag to compare

@plutext plutext released this 28 Oct 00:30
· 7 commits to master since this release

A caller can now declare the type of an element a wildcard holds, when reading and when saving. It is one per-call option, the same on both factories, and unset by default:

var options = {
  wildcardTypeInfo: function (name, parent, propertyInfo, classInfo, elementOrValue) { /* return a type info, or undefined */ }
};
context.createUnmarshaller(options);
context.createMarshaller(options);

What it does. A wildcard (an anyElement property, such as the content of mc:Choice or mc:Fallback) types each element it holds by the element's declaration: the class's scope first, then the global one. Where an element's type depends on where it appears, the global declaration wins. In WordprocessingML the global w:sdt is block level, so a run-level content control in a paragraph's mc:Choice read as SdtBlock, with everything below it. An SdtRun in the same place was saved with xsi:type. wildcardTypeInfo is asked before that lookup:

  • name is the element's name.
  • parent is the element the wildcard's class is reading or writing: in the source document when reading, and the open element in the output document when saving.
  • propertyInfo is the wildcard property, and classInfo is its class.
  • The last argument is the element itself when reading, and the value when saving.

Because parent means the same on both sides, one function that decides by name and ancestry can go in one options object to both factories.

A returned type info is the element's declared type. When reading, it decides the class and every list below it, and it can type an element the context doesn't declare. When saving, xsi:type is written only where the value's class differs from the answer. Answer with a type info from the context in use, because the comparison is by identity. With supportXsiType off, the value is marshalled by the answer. undefined or null keeps the lookup by name, and anything else throws.

When reading, it is asked at the element's start, before its onElement. It is not asked when supportXsiType is on and the element's xsi:type names a known type, which still comes first, nor for a DOM-only wildcard. A throw is located, for example w:sdt (line 3): .... When saving, it is asked for each typed value before omitElement and before the element is written. It is never asked for mixed text or DOM content. The typings add wildcardTypeInfo? to UnmarshalCallbacks and MarshalCallbacks.

Why. @docx4j/generated-objects-ts types a content control in a kept mc:Choice or mc:Fallback at its host's level: run, row, cell or block (its CR-018), which is what docx4j does. The level is known only from the ancestors, so it has to be decided where the runtime picks the type, before the element is read.

Cost. On 3,000 paragraphs, each with a run-level control in an mc:Choice (6,000 elements in wildcards, objects' 104 modules), reading and saving are within noise of 3.10.0, unset and set. objects checked the candidate:

  • all 341 of its fidelity hashes are identical to 3.10.0's, unset and set;
  • its CR-018 forms read at their host's level, with no xsi:type;
  • their saves are byte-identical to 3.10.0's.

What a consumer must do. Nothing. Unset, nothing is called and nothing changes. The runtime's jsonix-factory.js in this release is byte-identical to the bytes objects tested (sha256 906bc9f2a9b4254c58975a42aac38c6f76b1867db6c926b24ccfdc36ebc7061d, commit ce4db33).

Change request: docs/change-requests/jsonix-CR-014-declare-wildcard-element-types.md