Skip to content

Latest commit

 

History

History
1061 lines (807 loc) · 23.9 KB

further-features-of-the-field-f49a0f7.md

File metadata and controls

1061 lines (807 loc) · 23.9 KB

Further Features of the Field

Application developers can control important features of the field.

Note:

This topic is only applicable to SAP Fiori elements for OData V4.

Text Annotation and Text Arrangement Annotation

The value displayed within the field can show either only the textual description of the value, or show it together with the ID representation of the value. Consider the following example data set:

SalesOrderID

PlantID

PlantName

100

A1

ABC

101

A2

DEF

In this example, PlantID represents the unique ID of the object "Plant". But this is not easily readable for the end user and typically, the field PlantID would have a reference to the corresponding text.

You can define a text using the Common.Text annotation on a property.

Application developers can define the arrangement of a code or ID value and its text using the UI.TextArrangement annotation.

TextArrangement

Display Format

TextFirst - (default value)

ABC (A1)

TextLast

A1 (ABC)

TextOnly

ABC

TextSeparate

A1

Sample Code:

XML Annotation

<Annotations Target="com.c_salesordermanage_sd/SalesOrganization">
   …
   <Annotation Term="Common.Text" Path="SalesOrganization_Text">
      <Annotation Term="UI.TextArrangement" EnumMember="UI.TextArrangementType/TextOnly"/>
   </Annotation>
   …
</Annotations>

Sample Code:

ABAP CDS Annotation

…
@ObjectModel.text.element:  [ ' SalesOrganization_Text,' ]
@UI.textArrangement: #TEXT_ONLY
SalesOrganization
…

Sample Code:

CAP CDS Annotation

annotate com.c_salesordermanage_sd with {
    ...
    SalesOrganization @(
             Common : {
              Text: SalesOrganization_Text,
              TextArrangement : #TextOnly
            })
    ...
};

The text arrangement can also be done centrally for all properties of an entity set.

The TextArrangement value at entity set level is considered as a fallback only if you have not specified the TextArrangement at property level. So the TextArrangement at property level takes precedence over the one defined at entity set level.

Sample Code:

XML Annotation

<Annotations Target="SalesOrder"> //Main EntitySet
  <Annotation Term="com.sap.vocabularies.UI.v1.TextArrangement" EnumMember="com.sap.vocabularies.UI.v1.TextArrangementType/TextFirst"/>
</Annotations>

Note:

Consider the following when using a text arrangement annotation in a value help:

  • The TextArrangement of the value help entity set is used to determine the display of the fields that show up in the columns of the value help dialog. The TextArrangement specified at property level within the value help entity set again takes precedence over the one defined at entity set level.

  • The TextArrangement annotation #TextOnly is supported in value help tables (that is, in the value help dialog and for the type-ahead feature). Other TextArrangement annotations like #TextFirst, #TextLast, or #TextSeparate are not considered. Combo boxes also support #TextFirst and #TextLast.

  • A separate text column is ignored if the text annotation is already used in another column using the TextArrangement.

Displaying Readable IDs Instead of Edm.Guid Values Using Common.ExternalID

For the properties of Edm.Guid type, you can define a Common.ExternalID annotation that displays a readable identifier of an item. Using this, the readable ID is displayed on the UI instead of the Edm.Guid value. The Common.ExternalID annotation is supported for both the fields and filter fields.

The following code snippets show a Common.ExternalID annotation at the myGuidProperty that is an Edm.Guid property. It points to the readable ID that is the externalId property.

Sample Code:

XML Annotation

      <Annotations Target="ExternalIdService.Entities/myGuidProperty">
        <Annotation Term="Common.ExternalID" Path="externalId"/>
      </Annotations>

Sample Code:

CAP CDS Annotation

annotate ExternalIdService.Entities : myGuidProperty with @(Common: {ExternalID: externalId});

The Common.Text and Common.TextArrangement annotations are evaluated only for the readable ID property instead of the GUID property. However, while the GUID property is not visible on the UI, it is a part of the field as a technical identifier of an item or for filter fields.

Value helps for a field with an ExternalID property are to be defined at the Edm.Guid property. The entity type that is shown in the value help (defined in the collectionPath of the Common.ValueList annotation) can have Edm.Guid properties pointing to the readable ID properties.

Fiscal Annotations

Edm.String properties can be annotated to indicate that they are based on a fiscal date.

The following annotations are available for fiscal dates with the following patterns:

CAP CDS Annotation

Pattern

ABAP CDS Annotation

IsFiscalYearPeriod

YYYYPPP

Semantics.fiscal.yearPeriod

IsDayOfFiscalYear

d

N/A

IsFiscalPeriod

PPP

Semantics.fiscal.period

IsFiscalQuarter

Q

Semantics.fiscal.quarter

IsFiscalWeek

WW

Semantics.fiscal.week

IsFiscalYear

YYYY

Semantics.fiscal.year

IsFiscalYearQuarter

YYYYQ

Semantics.fiscal.yearQuarter

IsFiscalYearWeek

YYYYWW

Semantics.fiscal.yearWeek

N/A

 

Semantics.fiscal.yearVariant

For example, IsFiscalYearPeriod indicates that the annotated Edm.String property is a string based on a fiscal date following the YYYYPPP pattern.

Sample Code:

XML Annotation

<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalYearPeriod">
  <Annotation Term="Common.IsFiscalYearPeriod" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Year Period"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalDayOfYear">
  <Annotation Term="Common.IsDayOfFiscalYear" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Day Of Year"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalPeriod">
  <Annotation Term="Common.IsFiscalPeriod" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Period"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalQuarter">
  <Annotation Term="Common.IsFiscalQuarter" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Quarter"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalWeek">
  <Annotation Term="Common.IsFiscalWeek" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Week"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalYear">
  <Annotation Term="Common.IsFiscalYear" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Year"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalYearQuarter">
  <Annotation Term="Common.IsFiscalYearQuarter" Bool="true"/>
  <Annotation Term="Common.IsDigitSequence" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Year Quarter"/>
</Annotations>
<Annotations Target="sap.fe.manageitems.TechnicalTestingService.LineItems/fiscalWeekYear">
  <Annotation Term="Common.IsFiscalYearWeek" Bool="true"/>
  <Annotation Term="Common.Label" String="Fiscal Week Year"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

DEFINE VIEW SalesOrderItemHistoryOvw as select from ... 
{
    ...
    
    @Semantics.fiscal.yearPeriod: true
    fiscalYearPeriod,
    
    @Semantics.fiscal.period: true
    fiscalPeriod,
    
    @Semantics.fiscal.year: true
    fiscalYear,
    
    ...   
}

Sample Code:

CAP CDS Annotation

fiscalYearPeriod  : String     @title: 'Fiscal Year Period'   @Common.IsFiscalYearPeriod : true;
fiscalDayOfYear   : String     @title: 'Fiscal Day Of Year'   @Common.IsDayOfFiscalYear  : true;
fiscalPeriod      : String     @title: 'Fiscal Period'        @Common.IsFiscalPeriod     : true;
fiscalQuarter     : String(1)  @title: 'Fiscal Quarter'       @Common.IsFiscalQuarter    : true;
fiscalWeek        : String     @title: 'Fiscal Week'          @Common.IsFiscalWeek       : true;
fiscalYear        : String     @title: 'Fiscal Year'          @Common.IsFiscalYear       : true;
fiscalYearQuarter : String(5) @title: 'Fiscal Year Quarter' @Common.IsFiscalYearQuarter: true @Common.IsDigitSequence: true;
fiscalWeekYear    : String     @title: 'Fiscal Week Year'     @Common.IsFiscalYearWeek   : true;

For more information about ABAP and CDS semantics annotations, see Semantics Annotations.

Check out our live example in the flexible programming model explorer at Field - Fiscal types.

Visibility and Enablement of the Field

The visibility of the field is affected by the UI.Hidden annotation, that can be given either at property level or field level.

UI.Hidden Within a DataField

Sample Code:

XML Annotation

<Record Type="UI.DataField">
   <PropertyValue Property="Value" Path="TotalNetAmount" />
   <Annotation Term="UI.Hidden" Bool="false" />
</Record>

Sample Code:

ABAP CDS Annotation

{
    value: 'TOTALNETAMOUNT',
    type: #STANDARD
}
@UI.hidden: true
TOTALNETAMOUNT;

Sample Code:

CAP CDS Annotation

{
    $Type : 'UI.DataField',
    Value : 'TotalNetAmount',
    ![@UI.Hidden] : false
}

UI.Hidden Within a Property

Sample Code:

XML Annotation

<Annotations Target="com.c_salesordermanage_sd.SalesOrderManage/TotalNetAmount">
    <Annotation Term="Common.Label" String="Net Amount"/>
    <Annotation Term="Measures.ISOCurrency" Path="TransactionCurrency"/>
    <Annotation Term="UI.Hidden" Bool="true" />
</Annotations>

Sample Code:

ABAP CDS Annotation

ABAP CDS does not support Measures.ISOCurrency. Use the local XML annotation.

Sample Code:

CAP CDS Annotation

annotate com.c_salesordermanage_sd. SalesOrderManage with {
  TotalNetAmount
  @UI.Hidden
  @Common.Label : 'Net Amount'
  @Measures.ISOCurrency :  TransactionCurrency ;
};

The property ID of the entity ProductsType is always hidden

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ProductsType/ID">
    <Annotation Term="SAP__UI.Hidden"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

annotate view PRODUCTSTYPE with {
@UI.hidden: true
id;
}

Sample Code:

CAP CDS Annotation

annotate ProductsType with {
  ID @UI.Hidden;
};

UI.Hidden: Path-Based

The property ModifiedAt is hidden in the FieldGroup with the qualifier AdministrativeData if the property HasDraftEntity is set to true – all other appearances of the property ModifiedAt are not influenced.

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ProductsType">
    <Annotation Term="SAP__UI.FieldGroup" Qualifier="AdministrativeData">
        <Record>
            <PropertyValue Property="Data">
                <Collection>
                    <Record Type="SAP__UI.DataField">
                        <Annotation Term="SAP__UI.Hidden" Path=="HasDraftEntity"/>
                        <PropertyValue Property="Label" String="Modified at"/>
                        <PropertyValue Property="Value" Path="ModifiedAt"/>
                    </Record>

Sample Code:

ABAP CDS Annotation

@UI.fieldGroup: [{ qualifier: ' AdministrativeData', position: 10, label: 'ModifiedAt' }]
@UI.hidden: true

Sample Code:

CAP CDS Annotation

entity ProductsType : {
    UI.FieldGroup #AdministrativeData : {
    Data : [
        {
            $Type : 'UI.DataField',
            Label : 'Modified at',
            Value : ModifiedAt,
            ![@UI.Hidden] : HasDraftEntity,
        },
    ],
},
}

Note:

ABAP CDS does not allow a UI.hidden annotation pointing to a path. Please use the local XML annotation.

The property ModifiedAt is always hidden (wherever the property appears) if the property HasDraftEntity is set to true – in all other cases it’s visible.

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ProductsType/ModifiedAt">
    <Annotation Term="SAP__UI.Hidden" Path="HasDraftEntity"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

annotate view PRODUCTSTYPE with {
@UI.hidden: true
modifiedat;
}

Sample Code:

CAP CDS Annotation

entity ProductsType :{
    ModifiedAt : {
               ![@UI.Hidden] : HasDraftEntity
    }
}

Note:

ABAP CDS does not allow a UI.hidden annotation pointing to a path. Use the local XML annotation.

Metadata Showing FieldControl

In addition, the value of the FieldControl determines how the field behaves. It uses an enumeration (FieldControlType) as possible values (the values are provided in the table below). You can statically set a property to read only (similar to Core.Computed), but you can also refer to a property that uses the enumeration values as possible data values.

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ArtistsType/Name">
   <Annotation Term="SAP__common.FieldControl" EnumMember="SAP__common.FieldControlType/Mandatory"/>
   ....
   ....
</Annotations>

Sample Code:

ABAP CDS Annotation

@ObjectModel.mandatory: true
Name;

Sample Code:

CAP CDS Annotation

entity Artist : {
    Name : {
        FieldControl : #Mandatory
    }
}

Note:

@ObjectModel.mandatory can be applied on the ABAP CDS view only. This is not possible using metadata extensions. Furthermore, only @ObjectModel.mandatory is exposed and not @ObjectModel.readOnly.

Metadata Showing FieldControl Within a DataField Definition

In SAP Fiori elements for OData V4, you can use the common.FieldControl annotation within the usage of properties (as in UI.LineItem or UI.FieldGroup). With this option you can control the enablement of a property within a specific field group, for example, or you can define a property to be read only in a tabular visualization, but to be editable as a form field.

Sample Code:

XML Annotation

<Record Type="UI.DataField">
   <PropertyValue Property="Value" Path="TotalNetAmount" />
   <Annotation Term=" SAP__common.FieldControl" EnumMember="SAP__common.FieldControlType/ReadOnly"/>
</Record>

Sample Code:

ABAP CDS Annotation

{
    value: 'TOTALNETAMOUNT',
    type: #STANDARD
  }

Sample Code:

CAP CDS Annotation

{
            $Type : 'UI.DataField',
            Value : TotalNetAmount,
            ![@Common.FieldControl] : #ReadOnly,
}

Note:

ABAP CDS only supports @ObjectModel.mandatory but not @ObjectModel.readOnly.

Value of the FieldControl

Behavior

Mandatory

Property must have a non-null value whenever save or update is triggered. This validation must be done by the back end, since it's not done by SAP Fiori elements.

Note:

If a field has the FieldControl annotation set to mandatory, its column header will be marked as mandatory in edit mode.

Optional

Property can have a null value.

ReadOnly

Property value cannot be changed. In edit mode, this property will not show up as an editable field.

Inapplicable

Property has no meaning in the current entity state and will show up in disabled state.

Example:

In a travel expense report, the property DestinationCountry is Inapplicable if the trip type is domestic, and mandatory if the trip type is international.

Tip:

Fields that are part of InsertRestrictions/RequiredProperties or UpdateRestrictions/RequiredProperties are marked as mandatory only in the create/update flow. For more information, see Adding Actions to Tables.

Note:

Handling of FieldControl=Inapplicable

  • SAP Fiori elements ignores the static Inapplicable value because it is similar to the absence of the property in the service. Applications have to ensure that the service does not include fields that are marked as inapplicable.

  • Regarding the dynamic Inapplicable value, the fields for which the FieldControl evaluates to inapplicable are rendered as disabled.

Editability of the Field

There are different ways in which a field can be marked as editable:

  1. Core.Computed

  2. Core.Immutable

  3. Common.FieldControl

While the first two options are only used with the static values true and false, the third option is also used dynamically by referring to another property.

If a property is annotated with Core.Computed true, it is always displayed in a non-editable way.

Core.Immutable has the same result in edit mode, but in create mode the property is editable.

Common.FieldControl is a term using an enumeration with ReadOnly as a possible value. You can statically set a property to read-only (similar to Core.Computed), but you can also refer to a property that uses the enumeration values as possible data values.

Tip:

Not all field representations are editable in the object page header. Only the plain text facet and form facets are considered for editability. Semantic links are also displayed in edit mode, but only when the field is associated with a value help.

Example:

  1. The property CreatedAt of the entity ProductsType is always read only

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ProductsType/CreatedAt">
    <Annotation Term="SAP__Core.Computed"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

Core vocabulary annotations are not supported in ABAP CDS.

Sample Code:

CAP CDS Annotation

entity ProductsType : {
    CreatedAt : {
        Core.Computed: true
    }
}
  1. The property SupplierName is always read only in this application

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ProductsType/SupplierName">
    <Annotation Term="SAP__Common.FieldControl" EnumMember="com.sap.vocabularies.Common.v1.FieldControl/ReadOnly"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

No ABAP CDS annotation sample is available. Please use the local XML annotation.

Sample Code:

CAP CDS Annotation

entity ProductsType : {
    SupplierName : {
        Common.FieldControl : #ReadOnly
    }
}

Note:

ABAP CDS only supports @ObjectModel.mandatory but not @ObjectModel.readOnly.

  1. The property AvailabilityCode is always read only if the property _FieldControl/AvailabilityCode_FC has the value 1

Sample Code:

XML Annotation

<Annotations Target="SAP__self.ReviewsType/AvailabilityCode">
    <Annotation Term=" SAP__Common.FieldControl" Path="__FieldControl/AvailabilityCode_FC"/>
</Annotations>

Sample Code:

ABAP CDS Annotation

No ABAP CDS annotation sample is available. Please use the local XML annotation.

Sample Code:

CAP CDS Annotation

entity ReviewsType : {
    Common.FieldControl : __FieldControl.AvailabilityCode_FC
}

Note:

ABAP CDS does not allow a path-based value for the field control (the field element can only be annotated with @ObjectModel.mandatory).

Tooltip for a Data Point

A data point supports a tooltip that can be shown if no explicit label exists for that data point, that is, in a field group inside a table cell or in a header facet.

The tooltip is determined by the OData annotation Common.QuickInfo.

Sample Code:

XML Annotation

<Annotation Term="UI.DataPoint" Qualifier="Rating">
    <Record Type="UI.DataPointType">
        <Annotation Term="Common.QuickInfo" String="Rating Indicator "/>
        <PropertyValue Property="TargetValue" Int="5"/>
        <PropertyValue Property="Title" String="Rating"/>
        <PropertyValue Property="Value" Path="Rating"/>
        <PropertyValue Property="Visualization" EnumMember="UI.VisualizationType/Rating"/>
    </Record>
</Annotation>

Sample Code:

ABAP CDS Annotation

@UI.dataPoint: {
  title: 'Rating',
  visualization: #RATING
  targetValue: 5
}
Rating;

Sample Code:

CAP CDS Annotation

UI.DataPoint #Rating : {
    $Type : 'UI.DataPointType',
    TargetValue : 5,
    Title : 'Rating',
    Value : Rating,
    Visualization : #Rating,
    ![@Common.QuickInfo] : 'Rating Indicator ',
}

Note:

In ABAP CDS, Common.QuickInfo is not supported for the dataPoint and the qualifier is always auto-generated with the same value as the field ('Rating' in the example above).

The following screenshot shows the result on the UI: