3 - Analytics Modules and Widgets

This page describes how to add new analytics widgets (displayed on the analytics page).

Add a new analytics module

The module will deliver the data.

• Add a new analytics module .cs file (Vereinsmeisterschaften.Core > Analytics):
• The name should be of format AnalyticsModule<AnalyticsName>
• The class must derive from IAnalyticsModule. The AnalyticsAvailable flag can be returned, depending on the availability of the data.
• All services can be used here to calculate the analytics properties (use dependency injection to get the services)
• The analytics module must be added to the services (App.xaml.cs): services.AddSingleton<AnalyticsModule<AnalyticsName>>();
• Add all necessary placeholders like described in Add new Placeholders
• Implement the SupportedDocumentPlaceholderKeys property that should return a list with all placeholder keys that are supported by this analytics module. e.g.
  public List<string> SupportedDocumentPlaceholderKeys => new List<string>()
{
Placeholders.PLACEHOLDER_KEY_ANALYTICS_EXAMPLE_PLACEHOLDER1,
Placeholders.PLACEHOLDER_KEY_ANALYTICS_EXAMPLE_PLACEHOLDER2
};
• Implement the CollectDocumentPlaceholderContents method that should return a DocXPlaceholderHelper.TextPlaceholders object containing all placeholder contents. e.g.
  public DocXPlaceholderHelper.TextPlaceholders CollectDocumentPlaceholderContents()
{
DocXPlaceholderHelper.TextPlaceholders textPlaceholder = new DocXPlaceholderHelper.TextPlaceholders();
foreach (string placeholder in Placeholders.Placeholders_AnalyticsExamplePlaceholder1) { textPlaceholder.Add(placeholder, ModulePropertyInt1.ToString()); }
foreach (string placeholder in Placeholders.Placeholders_AnalyticsExamplePlaceholder2) { textPlaceholder.Add(placeholder, ModulePropertyStr2); }
return textPlaceholder;
}

Add a new analytics widget

The widget will display the data that is delivered by the module.

• Add a new analytics widget user control (Vereinsmeisterschaften > Views > AnalyticsWidgets):
• The name should be of format AnalyticsWidget<AnalyticsName>
• Add following resource to the Resources.resx (Vereinsmeisterschaften > Properties):
  • AnalyticsWidget<AnalyticsName>Title (e.g. AnalyticsWidgetAgeDistributionTitle): Title that is displayed on the UI for the widget
• Add following resource to the Tooltips.resx (Vereinsmeisterschaften > Properties):
  • TooltipAnalyticsWidget<AnalyticsName> (e.g. TooltipAnalyticsWidgetAgeDistribution): Tooltip that is displayed on the UI for the widget
• Code Behind:
  • The class must derive from AnalyticsWidgetBase.
  • The constructor can be like this: public AnalyticsWidget<AnalyticsName>(AnalyticsModule<AnalyticsName> analyticsModule) : base(analyticsModule) { InitializeComponent(); }
  • For an easier access to the analytics module, use something like this: private AnalyticsModule<AnalyticsName> _analyticsModule => AnalyticsModule as AnalyticsModule<AnalyticsName>;
  • When necessary, use any Series type from the LiveChartsCore namespace
  • Override the Icon property.
  • The title and info properties are automatically retrieved from the Resources.resx and Tooltips.resx.
  • To change the size of the widget, also override the NormalAnalyticsWidgetWidth and NormalAnalyticsWidgetHeight properties.
• XAML:
  • <local:AnalyticsWidgetBase x:Class="Vereinsmeisterschaften.Views.AnalyticsWidgets.AnalyticsWidget<AnalyticsName>"...
  • DataContext: DataContext="{Binding RelativeSource={RelativeSource Mode=Self}}"
  • Template: Template="{StaticResource ControlTemplateAnalyticsWidgetBase}"

When the charts needs scrolling (see e.g. AnalyticsWidgetStartsPerPerson.xaml for an example):

• XAML: use a scroll viewer around: <ScrollViewer x:Name="PART_scrollViewerChart" behaviors:NestedScrollViewersBehavior.IsEnabled="True">
• XAML: set the chart height to a defined value: ...Chart Height="{Binding ChartHeight}"
• Code Behind: trigger a change of the chart height, when the size of the scroll viewer changes (add this to the constructor): PART_scrollViewerChart.SizeChanged += (sender, e) => OnPropertyChanged(nameof(ChartHeight));
• Code Behind: Chart height could e.g. be: public double ChartHeight => Math.Max(PART_scrollViewerChart.ActualHeight, NumberRows * ChartMaxBarWidth);