Support a Mechanism for Specifying Index/Position of Template Insertion

[KetanReddy]

Related to #540, for cases where a template is being expanded into a property with existing assets. It would be a good feature to specify where the insertion actually happened. In the most simple case, we could support a prepend/append, property on the template object. However, if there are multiple existing assets we wouldn't be able to insert the expanded template in between the two elements so we may need to support expansion based on index? This also opens the door for conflicts in insertion from multiple templates because the order in which the templates are expanded is also not controllable via content so that is another parameter that might need to get added.

TODO:

• Determine scope of how to allow templates to specify where they should be expanded to
• Determine scope of how to allow templates to specify what order they should be executed in

[KetanReddy]

After some internal discussion. The following is the proposed design:

Support For a More Declarative Template API

The purpose of this change is to allow for content authors to have more explicit control over how template are expanded at runtime in Core Player. As Player uses JSON as a transport format, key order is not guaranteed to be preserved during serialization and de-serialization. This can result in problems with Template expansion at runtime as currently, the position of the template key relative to the attribute its being expanded into determines if the templated elements will be appended or prepended to any existing value. This may cause different behaviors of Player depending on the platform or any integration logic around Player. In order to alleviate this, a more explicit API is required to indicate where the template should be expanded at runtime.

Proposed Approach

The core idea of this solution is to maximize authoring and implementation simplicity. More robust solutions were considered but ultimately not perused due to too much complexity in one factor. For example, instead of the approach described below, an API around index based expansion would lead to problems around having to have forward knowledge of how many instanced would be expanded at runtime and thus requiring the content author maintain a complex mental model of data.

Changes to the Template API

Template elements would have a new property (to be decided during implementation) that would take information on whether the expanded data from the template should be appended (added to the end of the any existing elements) or prepended (added before any existing elements) in the location its being expanded to. Because the order of elements in an array is persevered and easy to ascertain at a glance, it is possible for content authors to accurately predict the order of multiple templates being expanded into the same slot with the same expansion behavior (e.g if there are two templates both set to append, the first template will be expanded followed by the second template).

Changes to Template Processing

During template expansion in the TemplatePlugin, the newly added field should be used to determine how the expanded template nodes should be inserted to the tree during parsing. In order to not break existing behavior, if no value is specified for how the template should be expanded the existing logic should be followed. As part of this change, we should introduce a warning message that a value was not specified to allow Player to require explicitly setting this at a later date.

DSL Enhancements

At the most basic level, the Template DSL component should be able to take this new property as a property and serialize it accordingly.
For a nicer authoring experience, it should also be able to infer if it should be appended or prepended to the existing property on the asset based on the order of the JSX elements in the content. This is similar to how we are currently manipulating where the template property gets serialized to in the object with relation to the property it will be expanded to.

[KetanReddy]

Closing as the design is done. Will open up issues for implementation