The "diff" array. Alias mechanism

General Information

The Alias mechanism – provides partial backward compatibility when user interface is changed in the new versions of the product. In the process of developing new versions, sometimes it becomes necessary to move page elements to new areas. In case the users have customized the page, the changes could lead to unpredictable consequences. The Alias mechanism helps to avoid this by interacting with the json-applier class which is diff array builder. This class merges all the parameters of the base and custom replacing schemas.

Diff – an array of objects, responsible for displaying schema elements. It can have containers, controls, modules and fields. For more information about the diff array, see the "The "diff" array” article.

Details

The alias property contains information about the previous element name. This information is taken into account when building a diff array of modifications, and informs that both the elements with a new name, and the elements with the name specified in alias must be considered. The alias is a configuration object that links two different elements – the new one and the old one. When building a diff array the alias configuration object can be used to exclude application of certain properties and operations to the element in which the alias is declared. The alias object can be added to any element in diff array.

Alias object structure

The alias object contains three custom properties:

• name – the name associated with the new element. This name will be used to locate the elements in the replaced schemas and connect them with the new element.

• excludeProperties – array of properties of the values object of the diff modification array element. These properties will not be used when generating diff.
• excludeOperations – array of operations that should not be applied to this element when the diff modification array is generated.

Usage example of the alias object :

// diff. array
diff: /**SCHEMA_DIFF*/ [
  {
    // The operation with the element.
    "operation": "insert",
    // Element new name.
    "name": "NewElementName",
    // Element values.
    "values": {
      // ...
    },
    // Alias configuration object.
    "alias": {
      //  Element previous name.
      "name": "OldElementName",
      // Exclude properties array.
      "excludeProperties": [ "layout", "visible", "bindTo" ],
      // Exclude operations array.
      "excludeOperations": [ "remove", "move", "merge" ]
    }
  },
  ///...
]

An example of the Alias mechanism usage for multiple schema replacement

There is an initial element of the diff array with the name "Name" and a set of properties. The element is located in the Header container. This schema was replaced several times and each time the “Name” element is moved and modified in every possible way.

Diff property of the base schema

diff: /**SCHEMA_DIFF*/ [
  {
    // Insert operation.
    "operation": "insert",
    // The name of the parent element to insert into.
    "parentName": "Header",
    // The name of the parent element with which operation is performed.
    "propertyName": "items",
    // Element name.
    "name": "Name",
    // Element property values object.
    "values": {
      // Layout.
      "layout": {
        // Column number.
        "column": 0,
        // Row number.
        "row": 1,
        // Number of joined columns.
        "colSpan": 24
      }
    }
  }
] /**SCHEMA_DIFF*/

Diff property after first replacement of the base schema:

diff: /**SCHEMA_DIFF*/ [
  {
    // Merging properties of the two elements.
    "operation": "merge",
    "name": "Name",
    "values": {
      "layout": {
        "column": 0,
        // Row number. The element is moved.
        "row": 8,
        "colSpan": 24
      }
    }
  }
] /**SCHEMA_DIFF*/

Diff property after second replacement of the base schema:

diff: /**SCHEMA_DIFF*/ [
  {
    //Moving the element.
    "operation": "move",
    "name": "Name",
    //The name of the parent element where the element is moved.
    "parentName": "SomeContainer"
  }
] /**SCHEMA_DIFF*/

In the new version, the "Name" element was moved from the SomeContainer element to the ProfileContainer element and must remain there regardless of the client customization. For this, the element gets a new name "NewName" and an alias configuration object is added to it.

diff: /**SCHEMA_DIFF*/ [
  {
    // Insert operation.
    "operation": "insert",
    // The name of the parent element in which insert is carried out.
    "parentName": "ProfileContainer",
    // The name of the parent element property with which operation is performed.
    "propertyName": "items",
    // Element new name.
    "name": "NewName",
    // Object with element property values.
    "values": {
      // Binding to a property value or a function
      "bindTo": "Name",
      // Layout.
      "layout": {
        // Column number.
        "column": 0,
        // Row number.
        "row": 0,
        // Number of joined columns.
        "colSpan": 12
      }
    },

    // Alias configuration object.
    "alias": {
      // Element previous name.
      "name": "Name",
      // Array of excluded properties.
      "excludeProperties": [ "layout" ],
      // Array of ignored operations.
      "excludeOperations": [ "remove", "move" ]
    }
  }
] /**SCHEMA_DIFF*/

Alias has been added in the new element. The parent element and its location on the edit page also has been changed. The excludeProperties property stores a set of properties that will be ignored when the difference is applied. The excludeOperations property stores a set of operations that will not be applied to the element from replacements.

In this example layout properties of all “Name” element inheritors are excluded and remove and move operations are not allowed. This indicates that the "NewName” element will only contain a root layout property and all of the "Name" element properties from replacements except Layout. Same applies to operations.

The result for the diff array builder will be:

diff: /**SCHEMA_DIFF*/ [
  {
    // Insert operation.
    "operation": "insert",
    // The name of the parent element in which insert is carried out.
    "parentName": "ProfileContainer",
    // The name of the parent element property with which operation is performed.
    "propertyName": "items",
    // Element new name.
    "name": "NewName",
    //Object with element property values.
    "values": {
      // Bind to a property value or a function
      "bindTo": "Name",
      // Layout.
      "layout": {
        // Column number.
        "column": 0,
        // Row number.
        "row": 0,
        //  Number of joined columns.
        "colSpan": 12
      },
    }
  },
] /**SCHEMA_DIFF*/