sap-fiori-add-visual-filter

What this skill does

# Add Visual Filter Bar to SAP Fiori Elements Application

## Purpose
This skill guides you through adding a visual filter to a value help dialog in SAP Fiori Elements applications. Visual filters display aggregated data as charts (bar, column, line, or donut) to help users filter data visually.

## When to Use This Skill
- Adding visual filters to value help dialogs on filter fields
- Enhancing user experience with graphical data representations
- Displaying aggregated data (sum, average, min, max) in filter selections
- Implementing analytics features in Fiori Elements OData V4 applications

## Prerequisites
- SAP CAP project with OData V4 service
- SAP Fiori Elements application (List Report or Analytical List Page)
- An entity with properties that can be aggregated
- Basic understanding of CDS annotations and manifest.json configuration

## Implementation Steps

### Step 1: Enable Aggregation Support in Service Definition
Add `@Aggregation.ApplySupported` annotation to the entity in your service file (e.g., `srv/service.cds`):

```cds
service YourService {
  entity YourEntity as projection on schema.YourEntity;
}

annotate YourService.YourEntity with @Aggregation.ApplySupported: {
  Transformations: ['aggregate', 'groupby'],
  AggregatableProperties: [
    { Property: MeasureField }  // e.g., Amount, Price, Quantity, Revenue
  ],
  GroupableProperties: [
    DimensionField1,  // e.g., Status, Category, Region, Department
    DimensionField2,
    // ... other fields that can be grouped
  ]
};
```

**Key Points:**
- The annotation must be applied directly to the entity, not the service block
- Use `annotate ServiceName.EntityName with @Aggregation.ApplySupported` after the service definition
- `AggregatableProperties`: Numeric fields that can be summed, averaged, etc. (measures)
- `GroupableProperties`: Fields to group by (dimensions)
- Both properties are required for visual filters to work

### Step 2: Define Aggregated Property in Annotations
In your annotations file (e.g., `app/your-app/annotations.cds`), define the aggregated property:

```cds
annotate service.YourEntity @(
    Analytics.AggregatedProperty #MeasureField_sum : {
        $Type : 'Analytics.AggregatedPropertyType',
        Name : 'MeasureField_sum',
        AggregatableProperty : MeasureField,
        AggregationMethod : 'sum',  // Options: sum, min, max, average
        @Common.Label : 'Total Amount'
    }
);
```

**Aggregation Methods:**
- `sum`: Total sum of values
- `min`: Minimum value
- `max`: Maximum value
- `average`: Average value

### Step 3: Create the Chart Definition
Define a chart that will be displayed in the value help dialog:

```cds
annotate service.YourEntity @(
    UI.Chart #visualFilter : {
        $Type : 'UI.ChartDefinitionType',
        ChartType : #Bar,  // Options: #Bar, #Column, #Line, #Donut
        Dimensions : [
            DimensionField  // Field to group by (e.g., Category, Status, Region)
        ],
        DynamicMeasures : [
            '@Analytics.AggregatedProperty#MeasureField_sum'
        ]
    }
);
```

**Chart Types:**
- `#Bar`: Horizontal bar chart
- `#Column`: Vertical column chart
- `#Line`: Line chart
- `#Donut`: Donut/pie chart

### Step 4: Create Presentation Variant
Link the chart to a presentation variant:

```cds
annotate service.YourEntity @(
    UI.PresentationVariant #visualFilter : {
        $Type : 'UI.PresentationVariantType',
        Visualizations : [
            '@UI.Chart#visualFilter'
        ]
    }
);
```

### Step 5: Configure Value List with Visual Filter
Add the field to SelectionFields and configure the value list:

```cds
annotate service.YourEntity with @(
    UI.SelectionFields : [
        DimensionField,
        // ... other filter fields
    ]
);

annotate service.YourEntity with {
    DimensionField @(
        Common.ValueList #visualFilter : {
            $Type : 'Common.ValueListType',
            CollectionPath : 'YourEntity',
            Parameters : [
                {
                    $Type : 'Common.ValueListParameterInOut',
                    LocalDataProperty : DimensionField,
                    ValueListProperty : 'DimensionField',
                },
            ],
            PresentationVariantQualifier : 'visualFilter',
        },
        Common.Label : 'Field Label',
    )
}
```

**Key Elements:**
- `CollectionPath`: Entity to query for value help data
- `Parameters`: Maps the local property to the value list property
- `PresentationVariantQualifier`: Links to the presentation variant (must match the qualifier from Step 4)
- Field must be included in `UI.SelectionFields` to appear in the filter bar

### Step 6: Configure Visual Filter in Manifest.json
In your Fiori app's `webapp/manifest.json`, configure the visual filter display in the List Report settings:

```json
{
  "sap.ui5": {
    "routing": {
      "targets": {
        "YourEntityList": {
          "type": "Component",
          "id": "YourEntityList",
          "name": "sap.fe.templates.ListReport",
          "options": {
            "settings": {
              "contextPath": "/YourEntity",
              "controlConfiguration": {
                "@com.sap.vocabularies.UI.v1.SelectionFields": {
                  "filterFields": {
                    "DimensionField": {
                      "visualFilter": {
                        "valueList": "com.sap.vocabularies.Common.v1.ValueList#visualFilter"
                      }
                    }
                  },
                  "layout": "CompactVisual"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**Manifest Configuration Details:**
- `controlConfiguration`: Configure specific UI controls
- `@com.sap.vocabularies.UI.v1.SelectionFields`: Targets the filter bar
- `filterFields`: Object containing field-specific configurations
- `DimensionField`: The field name (must match the field in annotations)
- `visualFilter.valueList`: Full vocabulary path to the value list annotation (including the qualifier)
- `layout`: Set to `"CompactVisual"` to enable visual filter layout in the filter bar

**Important Notes:**
- The `valueList` path must match exactly: `com.sap.vocabularies.Common.v1.ValueList#visualFilter`
- The qualifier after `#` must match the qualifier used in the `@Common.ValueList` annotation
- Without this manifest configuration, the visual filter will not display even if annotations are correct

## Complete Example

Generic implementation template:

**Service Definition (srv/service.cds):**
```cds
service MyService {
  entity Products as projection on db.Products;
}

annotate MyService.Products with @Aggregation.ApplySupported: {
  Transformations: ['aggregate', 'groupby'],
  AggregatableProperties: [
    { Property: Amount }  // Your numeric/measure field
  ],
  GroupableProperties: [
    Category,      // Your dimension field
    Status,
    CreatedDate
    // Add other fields users can group by
  ]
};
```

**Annotations (app/yourapp/annotations.cds):**
```cds
// Step 2: Define aggregated property
annotate service.Products @(
    Analytics.AggregatedProperty #Amount_sum : {
        $Type : 'Analytics.AggregatedPropertyType',
        Name : 'Amount_sum',
        AggregatableProperty : Amount,
        AggregationMethod : 'sum',
        @Common.Label : 'Total Amount'
    }
);

// Step 3: Define chart
annotate service.Products @(
    UI.Chart #visualFilter : {
        $Type : 'UI.ChartDefinitionType',
        ChartType : #Bar,
        Dimensions : [
            Category
        ],
        DynamicMeasures : [
            '@Analytics.AggregatedProperty#Amount_sum'
        ]
    }
);

// Step 4: Create presentation variant
annotate service.Products @(
    UI.PresentationVariant #visualFilter : {
        $Type : 'UI.PresentationVariantType',
        Visualizations : [
            '@UI.Chart#visualFilter'
        ]
    }
);

// Step 5a: Add to selection fields
annotate service.Products @(
    UI.SelectionFields : [
        Categ