Annotation Helper

The formatter functions can be used in binding expressions and <template:if> instructions for test conditions. The following formatter functions exist:

• format: General purpose method that handles proper escaping and formatting of constant values and provides binding expressions with suitable types:

  • Constant "14.4.11 Expression edm:String": This constant is either turned into fixed text, for example "Width", or into a data binding expression, for example "{/##/dataServices/schema/0/entityType/1/com.sap.vocabularies.UI.v1.FieldGroup#Dimensions/Data/0/Label/String}". If XML template processing has been started with the setting bindTexts : true, data binding expressions are used. The constant is used to reference translatable texts from OData v4 annotations, especially for XML template processing at design time.

  • Dynamic "14.5.3 Expression edm:Apply":

    • "14.5.3.1.1 Function odata.concat": Turned into a data binding expression relative to an entity

    • "14.5.3.1.2 Function odata.fillUriTemplate": Turned into an expression binding to fill the template at runtime

    • "14.5.3.1.3 Function odata.uriEncode": Turned into an expression binding to encode the parameter at runtime; you can embed odata.uriEncode into odata.fillUriTemplate.

  • Dynamic "14.5.12 Expression edm:Path": This dynamic expression is turned into a data binding relative to an entity including type information and constraints as available from metadata, for example "{path : 'Name', type : 'sap.ui.model.odata.type.String', constraints : {'maxLength':'255'}}".

  Note

  Unsupported values are turned into strings, and indicated as such. To ensure that the data binding syntax is not corrupted, proper escaping is used.

  <Text text="{path: 'meta>Value', formatter: 'sap.ui.model.odata.AnnotationHelper.format'}"/>

• getNavigationPath: Special formatter that extracts a data binding expression for the navigation path from a dynamic 14.5.2 Expression edm:AnnotationPath, for example:

  • The input value {AnnotationPath : "ToSupplier/@com.sap.vocabularies.Communication.v1.Address"} returns "{ToSupplier}"
  • The input value {AnnotationPath : "@com.sap.vocabularies.UI.v1.FieldGroup#Dimensions"} returns "{}"
  • The input value {} returns ""

  <template:if test="{path: 'facet>Target', formatter: 'sap.ui.model.odata.AnnotationHelper.getNavigationPath'}">
      <form:SimpleForm binding="{path: 'facet>Target', formatter: 'sap.ui.model.odata.AnnotationHelper.getNavigationPath'}" />
  </template:if>

• isMultiple: Special formatter that knows about the dynamic 14.5.2 Expression edm:AnnotationPath and returns the information whether the navigation path ends with an association end with multiple "*". If the multiple "*" are not the last characters, the formatter returns an error.

  <template:if test="{path: 'facet>Target', formatter: 'sap.ui.model.odata.AnnotationHelper.isMultiple'}">

• simplePath: Specialized method useful for design-time templating in connection with smart fields; it can only return simple binding expressions without type information. This has the advantage that the resulting XML view, which is shown at design-time, looks much simpler and nicer without &quot; escapes.

  Example:

  <mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:sfi="sap.ui.comp.smartfield"
    xmlns:sfo="sap.ui.comp.smartform"
    xmlns:template="http://schemas.sap.com/sapui5/extension/sap.ui.core.template/1">
    <sfo:SmartForm title="{path: 'meta>com.sap.vocabularies.UI.v1.HeaderInfo/TypeName', formatter: 'sap.ui.model.odata.AnnotationHelper.format'}">
      <template:repeat list="{path:'meta>', filters: {path: 'RecordType', operator: 'EQ', value1: 'com.sap.vocabularies.UI.v1.FieldGroupType'}}">
        <sfo:Group label="{path: 'meta>Label', formatter: 'sap.ui.model.odata.AnnotationHelper.format'}">
          <template:repeat list="{meta>Data}">
            <sfo:GroupElement label="{path: 'meta>Label', formatter: 'sap.ui.model.odata.AnnotationHelper.format'}">
              <sfi:SmartField value="{path: 'meta>Value', formatter: 'sap.ui.model.odata.AnnotationHelper.simplePath'}"/>
            </sfo:GroupElement>
          </template:repeat>
        </sfo:Group>
      </template:repeat>
    </sfo:SmartForm>
  </mvc:View>

  Output:

  <mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns:sfi="sap.ui.comp.smartfield" xmlns:sfo="sap.ui.comp.smartform">
    <sfo:SmartForm title="Sales Order">
        <sfo:Group label="Order Note">
            <sfo:GroupElement label="Text">
              <sfi:SmartField value="{Note}"/>
            </sfo:GroupElement>
        </sfo:Group>
    </sfo:SmartForm>
  </mvc:View>

The following helper functions can be used with <template:with>:

• gotoEntityset: Helper function for a with instruction for the entity set with the given name or the entity set that has been determined by the last navigation property of a dynamic 14.5.2 Expression edm:AnnotationPath, depending on how it is called.

  <template:with path="facet>Target" helper="sap.ui.model.odata.AnnotationHelper.gotoEntitySet" var="entitySet" />
  <template:with path="associationSetEnd>entitySet" helper="sap.ui.model.odata.AnnotationHelper.gotoEntitySet" var="entitySet"/>

  The binding context passed to the helper function, as determined by the template:with instruction's path property, must point to a simple string or to an annotation (or annotation property) of type Edm.AnnotationPath, embedded within an entity type; the context's model must be an sap.ui.model.odata.ODataMetaModel.

• gotoEntityType: Helper function for a with instruction that goes to the entity type with the given qualified name. The binding context passed to the helper function, as determined by the template: with instruction's path property, must point to the qualified name of an entity type; the context's model must be an sap.ui.model.odata.ODataMetaModel.

  Example: Assume that entitySet refers to an entity set within an OData meta model; the helper function is then called on the entityType property of that entity set (which holds the qualified name of the entity type) and in turn the path of that entity type is assigned to the variable entityType.

  <template:with path="entitySet>entityType" helper="sap.ui.model.odata.AnnotationHelper.gotoEntityType" var="entityType">

• resolvePath is a helper function for a template:with instruction that resolves a dynamic 14.5.2 Expression edm:AnnotationPath. The function supports navigation properties and term casts. The binding context passed to the helper function, as determined by the template:with instruction's path property, must point to an annotation or annotation property of type Edm.AnnotationPath, embedded within an entity type, The context's model must be sap.ui.model.odata.ODataMetaModel.

  <template:with path="meta>Value" helper="sap.ui.model.odata.AnnotationHelper.resolvePath" var="target">