@munichremarkets/fund-portfolio-configurator

v11.0.0

Published

24 days ago

Downloads

388

0High
0Medium
0Low

mrm-bot

michaelewers

Munich Re Markets Fund Portfolio Configurator Widget

This package provides the Fund Portfolio Configurator widget by Munich Re Markets for integration into your website.

Installation

If you use NPM as a package manager, run

  npm install --save @munichremarkets/fund-portfolio-configurator

And if you use Yarn:

  yarn add @munichremarkets/fund-portfolio-configurator

Integration

The Fund Portfolio Configurator widget provides a (plain JavaScript) rendering API in the form of the renderFundPortfolioConfigurator function that is used to display the widget on the page and pass data to the widget.

Importing from NPM

The Fund Portfolio Configurator package contains JavaScript (ES5) code in the ECMAScript module format, so you need to use a bundler that supports this format, such as Webpack or Rollup. Using ES6-style imports, your code might look like this:

import { renderFundPortfolioConfigurator } from '@munichremarkets/fund-portfolio-configurator';

TypeScript declaration files (.d.ts) are also included in the package, providing typings and enhanced IDE support for the rendering API.

Rendering the widget

In order to render the widget, you need to invoke the renderFundPortfolioConfigurator rendering function that is made available as described above. The following data needs to be provided when invoking the rendering function:

A target DOM element (typically a <div> element) into which the widget should be rendered
A configuration object providing data to the widget, see section "Configuring the widget" below

For example, a call to the rendering function might look like this (ES6):

const target = document.getElementById('widget-target');

renderFundPortfolioConfigurator(target, {
  /* configuration data, see below */
});

Please make sure to invoke the rendering function after the DOM has been loaded, e.g. by putting the call into a <script> tag at the end of the <body> or into a DOMContentLoaded event handler.

Note

You need to make sure that the process.env object is available at runtime and contains a NODE_ENV property defining the current environment, see the Node.js documentation. Note that it is not enough to just replace process.env.NODE_ENV, but you need to replace process.env as a whole. Depending on your bundler, you can use these tools:

For Webpack, use the DefinePlugin:

new webpack.DefinePlugin({
  'process.env': JSON.stringify({ NODE_ENV: process.env.NODE_ENV }),
});

For Vite, use the define config option:

defineConfig({
  // ...

  define: {
    'process.env': JSON.stringify({ NODE_ENV: process.env.NODE_ENV }),
  },
});

Warning: Do not use JSON.stringify(process.env) as this may leak other environment variables into your bundle.

Unmounting the widget

The rendering function returns a cleanup function that can be used to unmount the widget like this:

const target = document.getElementById('widget-target');

const unmountWidget = renderFundPortfolioConfigurator(target, {
  /* configuration data, see below */
});

/* use `unmountWidget` e.g. in an event listener */

Configuring the widget

The configuration object passed to renderFundPortfolioConfigurator can contain the following properties (example values):

{
  // Whether to include widget-scoped Bootstrap 4.x CSS into the page
  // Optional, default: false
  // Set this to `true` if you are not already using Bootstrap on your website
  includeBootstrap4Css: true,

  // Base URL of fund data backend
  // Optional, default: 'https://data.munichremarkets.com/funddata'
  // May optionally end in '/'
  fundBackendBaseUrl: 'https://some-url',

  // Base URL of reference security data backend
  // Optional, default: 'https://widget.index-wechsel.de/references'
  // May optionally end in '/'
  referenceSecurityBackendBaseUrl: 'https://some-url',

  // A token provided in JWT (JSON Web Token) format (see https://jwt.io).
  // The token is required for rendering the widget and permits access to the index data backend.
  // Mandatory
  jwt: '<some-token>',

  // Configuration of which filters are available to the user in the fund list,
  // containing one item per filter type in the desired order (if array is empty, no filter area is shown).
  // Currently, the following filter types are available:
  // FundFilterType.Risk, FundFilterType.Rating, FundFilterType.FundType,
  // FundFilterType.Region, FundFilterType.Sector and FundFilterType.EsgCompliance

  // Optional - if not specified, default filter configuration is used that
  // includes all filter options except for the EsgCompliance filter.
  // The thresholds for the sector and region filters are zero.
  // It is not possible to change parts of the default configuration,
  // in order to add or remove filters or their values, you have to define a new configuration
  // that includes definitions for all filters and values that you would like to use.

  // You can import the 'defaultFilterConfig' and adjust it to your specific needs:
  // import { defaultFilterConfig } from '@munichremarkets/fund-portfolio-configurator'
  // For example:
  // - Include additional filter type to your configuration:
  //     const newConfig = [
  //       ...defaultFilterConfig,
  //       {
  //         filterType: FundFilterType.EsgCompliance,
  //         values: [EsgCompliance.Article8, EsgCompliance.Article9, EsgCompliance.None],
  //       },
  //     ]
  // - Remove a filter type (e.g., Risk):
  //    const newConfig = defaultFilterConfig.filter(f => f.filterType !== FundFilterType.Risk)
  // - Restrict the filter value options for a particular filter type:
  //    new newConfig = defaultFilterConfig.map(f => f.filterType === FundFilterType.Rating ? {...f, values: [5, 4, 3]} : f)
  // Once you have created your custom configuration, you can assign it to 'filterConfig' property (filterConfig: newConfig)

  // If there are no funds associated with a specific filter option, that option will not be displayed.
  // If there are no funds associated with any of the options for a particular filter, the entire filter will be hidden.

  // Below you'll find an example configuration for each available filter with all available values.

  filterConfig: [
    {
      // Type of filter, i.e. the criterion by which the fund list is filtered
      // Mandatory
      filterType: FundFilterType.Risk,

      // List of values for the specified filter type in the desired order
      // Mandatory
      values: [7, 6, 5, 4, 3, 2, 1],
    },
    {
      filterType: FundFilterType.Rating,
      values: [5, 4, 3, 2, 1],
    },
    {
      filterType: FundFilterType.FundType,
      values: ['stocks-fund', 'etf', 'moneymarket-fund', 'mixed-fund', 'bonds-fund', 'guarantee-fund'],
    },
    {
      filterType: FundFilterType.Region,
      // Threshold for the regions filter. Should be a number between 0 and 1.
      // Optional, default: 0
      // A fund matches a region filter criterion if and only if the share of the region
      // within the fund is greater than or equal to this value.
      // If the threshold is zero, only shares greater than zero are matched.
      minimumShare: 0.4,
      values: ['europe', 'northamerica', 'asia', 'latam', 'australia'],
    },
    {
      filterType: FundFilterType.Sector,
      // Threshold for the sectors filter. Should be a number between 0 and 1.
      // Optional, default: 0
      // A fund matches a sector filter criterion if and only if the share of the sector
      // within the fund is greater than or equal to this value.
      // If the threshold is zero, only shares greater than zero are matched.
      minimumShare: 0.15,
      // These may be grouped together via the text override mechanism, see "Grouping of sectors" below
      values: [
        'equityBasicMaterials',
        'equityCommunicationServices',
        'equityConsumerCyclical',
        'equityConsumerDefensive',
        'equityEnergy',
        'equityFinancialServices',
        'equityHealthServices',
        'equityIndustrials',
        'equityRealEstate',
        'equityTechnology',
        'equityUtilities',
        'fixedIncomeCashAndEquivalents',
        'fixedIncomeCorporate',
        'fixedIncomeDerivatesOther',
        'fixedIncomeGovernment',
        'fixedIncomeMunicipal',
        'fixedIncomeSecuritized',
        'other',
      ],
    },
    {
      filterType: FundFilterType.EsgCompliance,
      values: ['none', 'article8', 'article9'],
    },
  ],

  // UUID of the fund universe to use
  // This can be used to customize the set of funds available in the widget
  // Optional - if not specified, a default fund universe is used
  fundUniverseId: 'd090af5f-2258-4838-88d3-ca462696c7fb',

  // Configuration of which indicators are shown when selecting funds or viewing the detailed information for a specific fund
  // Optional - if not specified, a default indicator configuration is used (Sectors, Asset Classes, Regions)
  //
  // There are three slots, all of which are optional:
  // * On narrow screens, all slots that are specified are shown from top to bottom in order
  // * On wide screens, slot 1 is shown on the left, slot 2 in the center, and slot 3 on the right
  // * If none of the slots is specified, no indicator area is shown
  //
  // The following indicators are available for each slot:
  // IndicatorType.Sectors, IndicatorType.AssetClasses, IndicatorType.Regions, IndicatorType.ReturnRisk, IndicatorType.TopHoldings
  indicatorConfig: {
    slot1: IndicatorType.Sectors,
    slot2: IndicatorType.AssetClasses,
    slot3: IndicatorType.Regions,
  },

  // Locale to use for localized texts
  // Mandatory
  // Currently available locales: Locale.DeDe, Locale.EnUs
  locale: Locale.DeDe,

  // Minimal share (from 0 to 1) that each fund within a portfolio must have in order for the portfolio to be valid
  // Optional, default: 0.1
  minimumSharePerFund: 0.1,

  // Maximum amount of funds each portfolio may contain in order for the portfolio to be valid. By default, the number of funds will be unlimited.
  // Optional, default: undefined
  maximumFundsCount: 10,

  // Callback to be invoked when the widget's workflow is finished and a portfolio is selected
  // Optional - if not specified, the button to select a portfolio is not displayed
  // Arguments:
  // `items` (mandatory): list of funds contained in the portfolio like this:
  // [
  //   {
  //     // ISIN of the fund
  //     isin: 'LU0323357649',
  //
  //     // Share of the fund within the portfolio, from 0 to 1
  //     share: 0.5,
  //
  //     // Name of the fund
  //     name: 'Fund 1'
  //   },
  //
  //   {
  //     isin: 'FR0010135103',
  //     share: 0.5,
  //     name: 'Fund 2'
  //   }
  // ]
  onSelectPortfolio: items => console.log(items),

  // List of predefined strategies the user can choose from
  // Mandatory
  // This does *not* include the "Custom Portfolio" strategy
  strategyTemplates: [
    {
      // Caption of the strategy in all locales that you need to support
      // Mandatory
      caption: {
        [Locale.DeDe]: 'Nachhaltigkeit',
        [Locale.EnUs]: 'Sustainability',
      },

      // Description of the strategy in all locales that you need to support
      // Mandatory
      description: {
        [Locale.DeDe]: 'Nachhaltiges Portfolio mit Aktienquote von 50%',
        [Locale.EnUs]: 'Sustainable portfolio with equity share of ~50%',
      },

      // List of funds contained in the strategy
      // Mandatory
      items: [
        {
          // ISIN of the fund
          // Mandatory
          isin: 'LU0323357649',

          // Share of the fund within the strategy, from 0 to 1
          // Mandatory
          share: 0.5,
        },

        {
          isin: 'FR0010135103',
          share: 0.5,
        },
      ],

      // Name of the strategy in all locales that you need to support
      // Mandatory
      name: {
        [Locale.DeDe]: 'ESG Ausgewogen',
        [Locale.EnUs]: 'ESG Balanced',
      },

      // Unique identifier of the strategy which will be used for tracking purposes
      // The values 'individual' and 'current' are reserved for the according strategies and cannot be used
      // Optional - if tracking is disabled, this field can be omitted
      strategyId: '3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a',
    },
  ],

  // Custom texts per locale
  // Optional - if not specified, default texts are used
  textOverrides: {
    'widgets.fundPortfolioConfigurator.title': {
      // Texts can be provided in any supported locale (see `locale` option)
      [Locale.DeDe]: 'Fonds-Portfoliokonfigurator',
      [Locale.EnUs]: 'Fund Portfolio Configurator',
    },
  },

  // Toggle whether to display the text risk indicator in the chart area
  // recommended if IndicatorType.ReturnRisk is not configured via the indicatorConfig property
  // Optional - default is true
  showTextRiskIndicator: true,

  // Define the priority of the strategies.
  // Note that the order of the `strategyTemplates` also defines a priority within the strategy templates.
  // The strategies with the highest priority will initially be shown in a more prominent position in the carousel of
  // the Fund Portfolio Configurator.
  // The only allowed combinations are [FundPortfolioConfiguratorStrategyType.TemplateStrategies, FundPortfolioConfiguratorStrategyType.IndividualStrategy] and
  // [FundPortfolioConfiguratorStrategyType.IndividualStrategy, FundPortfolioConfiguratorStrategyType.TemplateStrategies]
  // Default: [FundPortfolioConfiguratorStrategyType.TemplateStrategies, FundPortfolioConfiguratorStrategyType.IndividualStrategy]
  strategyOrder: [FundPortfolioConfiguratorStrategyType.IndividualStrategy, FundPortfolioConfiguratorStrategyType.TemplateStrategies],

  // Configuration of which tabs are shown when comparing portfolios
  // Optional - if not specified, a default comparison section configuration is used (RiskReturn, Sectors, Regions, TopHoldings, AssetClasses)
  // List containing the sections in the desired order:
  // * Up to 5 sections can be selected
  // * Regardless of the selected configuration a performance section is always displayed as the first tab
  // * If empty, only the performance section is displayed
  // The following sections are available:
  // ComparisonSection.RiskReturn, ComparisonSection.AssetClasses, ComparisonSection.Sectors, ComparisonSection.Regions, ComparisonSection.TopHoldings
  comparisonSectionConfig: [ComparisonSection.Regions, ComparisonSection.RiskReturn, ComparisonSection.AssetClasses],

  // Configuration object for configuring the Matomo tracking of the widget
  // Optional
  internalTrackingConfiguration: {
    // Site ID to be used for Matomo tracking if enabled (see `trackingEnabled` option)
    // Mandatory
    trackingSiteId: '1',

    // Whether Matomo tracking is enabled
    // Optional, default: false
    // If set to false, no requests will be sent to Matomo
    trackingEnabled: true,
  },

  // Configuration object for configuring whether and how tracking events should be provided to the host website
  // Optional - if not specified, no data is provided to your website
  externalTrackingConfiguration: {
    // Size of the batches of events to emit at once
    // Optional, default: 10
    eventQueueSize: 10,

    // Function to be invoked for each batch of events
    // Also invoked on the window event 'beforeunload' with all events still in the queue
    // For the structure of each event, see example events below
    // Optional - if not specified, no events are emitted
    onTrackEvents: events => console.log(events),
  },

  // URL or data-URL of a company logo in the print view
  // Optional - if not specified, no logo is rendered in the print view
  companyLogoUrl:
    'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDAgMTAwIj4KICAgIDx0ZXh0IHg9IjAiIHk9IjQwIiBmaWxsPSJ3aGl0ZSI+SnVzdCBhbiBleGFtcGxlPC90ZXh0Pgo8L3N2Zz4=',

  // Uuid deciding which referenceSecurity is used as a benchmark
  // Optional - if not specified, the benchmark is not shown
  referenceSecurity: { id: '52ee7c09-78b1-4e07-a7d1-f79d9b33e85e' },

  // Whether to include information about ESG compliance for funds
  // Optional - default: false
  // If set to true, the ESG compliance information for funds is displayed
  showEsgCompliance: true,

  // Callback that is invoked when the Fund Details Link is clicked and can provide external links for the fund.
  // Optional - if not specified, a link to the PDF factsheet URL from the fund data backend is displayed
  //
  // Arguments:
  // `isin` (mandatory): ISIN of the fund
  // `factsheetPdfUrl` (mandatory): PDF factsheet URL from the fund data backend, may be an empty string
  // `externalUrl` (optional): External URL from the fund data backend if available
  //
  // If specified, the callback must return an object in one of the two formats shown in the examples below.
  // Those formats differ in their effect on the behaviour of the widget.

  // 1. This configuration results in the specified links being displayed in the Fund Details Modal
  generateFundDetailsLinks: (isin, factsheetPdfUrl, externalUrl) => ({
    mode: 'indirect',
    links: [
      { localizedCaption: `Factsheet Pdf Link`, targetUrl: factsheetPdfUrl },
      { localizedCaption: `Link for ${isin}`, targetUrl: `https://www.example.com/${isin}` },
      { localizedCaption: `Another link for ${isin}`, targetUrl: `https://www.example2.com/${isin}` },
    ],
  }),

  // 2. This configuration opens the specified targetUrl in a new tab instead of a modal upon clicking the Details link of a fund
  //generateFundDetailsLinks: (isin, factsheetPdfUrl, externalUrl) => ({
  //  mode: 'direct',
  //  targetUrl: `https://www.example.com/${isin}`,
  //}),

  // Preselected new portfolio
  // Optional
  //
  // This should be left unspecified in most cases. If specified, the widget starts on the summary page with the given
  // portfolio preselected. The user can then either confirm it or go back and change it using the "Edit" button. This
  // is useful for scenarios such as "Shift & Switch", where the user has already selected a portfolio for one use case
  // (e.g. "Shift") and should now just confirm or change the portfolio for the second use case (e.g. "Switch") without
  // having to start from scratch.
  newPortfolio: [
    {
      // ISIN of the fund
      // Mandatory
      isin: 'LU0136412771',

      // Share of the fund within the portfolio, from 0 to 1
      // Mandatory
      share: 0.5,
    },

    {
      isin: 'LU0776410689',
      share: 0.5,
    },
  ],

  // The following configuration options depend on the 'mode' in which the widget is run
  //
  // There are three modes:
  // 1) Create mode: The user creates a new portfolio
  // 2) Shift mode: The user shifts their portfolio value into a new portfolio
  // 3) Switch mode: The user switches their monthly contributions into a new portfolio

  // Defines the mode in which the widget is run
  // Mandatory
  // Available modes: 'create', 'shift', 'switch'
  mode: 'shift',

  // The current portfolio
  // Only available in the 'shift' and 'switch' modes
  // Mandatory
  currentPortfolio: [
    {
      // ISIN of the fund
      // Mandatory
      isin: 'LU0323357649',

      // Share of the fund within the portfolio, from 0 to 1
      // Mandatory
      share: 0.5,
    },

    {
      isin: 'FR0010135103',
      share: 0.5,
    },
  ],

  // Total monthly contribution (regular payment) to the user's portfolio in EUR
  // Only available in the 'create' and 'switch' modes
  //
  // In 'create' mode, this is optional and specifies the total monthly contribution to the new portfolio. If not
  // specified, no values for the monthly contribution are displayed on the summary page.
  //
  // In 'switch' mode, this is mandatory and specifies the total monthly contribution to the current portfolio.
  totalMonthlyContribution: 350,

  // Total value of the user's portfolio in EUR
  // Only available in the 'create' and 'shift' modes
  //
  // In 'create' mode, this is optional and specifies the initial deposit of the new portfolio. If not specified, no
  // values for the initial deposit are displayed on the summary page.
  //
  // In 'shift' mode, this is mandatory and specifies the total value of the current portfolio.
  totalPortfolioValue: 5000,

  // Whether to enable the product tour
  // Only available in 'create' mode
  // Optional - default: false
  //
  // In addition to setting this flag, certain preconditions have to be met for allowing the product tour to be started:
  // - at least one strategy template has to be configured via 'strategyTemplates' (see above)
  // - at least one of the configured strategy templates has to contain at least two funds
  //   (The product tour will then use the first such strategy template.)
  //
  // The button for starting the tour will not be shown if the user has one or more locally saved draft(s) or when
  // viewing the widget on a 'mobile' viewport.
  enableProductTour: true,
}

The following things should be considered in order to ensure that the widget works as intended.

Note: Providing data that does not adhere to the documented API of the widget may lead to unexpected behavior or the widget not working altogether.

Text override mechanism

Some texts that are displayed by the widget can be overridden by providing the textOverrides option in the configuration object. It expects an object in the form of

{
    'some.overridable.key': {
        [Locale.DeDe]: 'Some German text',
        [Locale.EnUs]: 'Some English text (US)',
        [Locale.EnGb]: 'Some English text (GB)',
    },
    'some.other.key': { /* ... */ }
}

where some.overridable.key is a localization key specified by the widget.

Note: The override mechanism is entirely optional. If it is omitted, default texts are used instead.

Semantic markup

Some texts can contain basic semantic HTML markup that is sanitized before displaying. The following tags are allowed and will be displayed as bold, italic, underlined, etc.: strong, b, em, i, u, br, p.

Note: HTML tags cannot contain attributes. If provided anyway, they are removed during sanitization ( e.g. <em class="some-classname">some text</em> will be converted to <em>some text</em>).

Interpolation

In some cases, texts might need to include dynamic values (e.g. monetary values or percentages). Such values can be referenced in the text using {{someVariable}}, where someVariable is a predefined name specific to the respective text key and will be replaced with the actual value during runtime.

Empty default text

In some cases default texts might be empty, which will cause the enclosing markup element (e.g. an information icon with accompanying text label) to purposefully not be displayed in the widget. This is a mechanism to remove markup elements entirely when the text that they usually display is missing. In these cases, a text override can be supplied to make the element visible again.

Grouping of sectors

The Fund Portfolio Configurator widget provides a fine-grained set of sectors that can be shown in the sector indicator and sector filter. The full set of available sectors is given by the text keys starting with general.enums.fundSectors:

general.enums.fundSectors.equityBasicMaterials
general.enums.fundSectors.equityCommunicationServices
general.enums.fundSectors.equityConsumerCyclical
general.enums.fundSectors.equityConsumerDefensive
general.enums.fundSectors.equityEnergy
general.enums.fundSectors.equityFinancialServices
general.enums.fundSectors.equityHealthServices
general.enums.fundSectors.equityIndustrials
general.enums.fundSectors.equityRealEstate
general.enums.fundSectors.equityTechnology
general.enums.fundSectors.equityUtilities
general.enums.fundSectors.fixedIncomeCashAndEquivalents
general.enums.fundSectors.fixedIncomeCorporate
general.enums.fundSectors.fixedIncomeDerivatesOther
general.enums.fundSectors.fixedIncomeGovernment
general.enums.fundSectors.fixedIncomeMunicipal
general.enums.fundSectors.fixedIncomeSecuritized
general.enums.fundSectors.other

In case you don't need this fine granularity, you can group multiple sectors together using the text override mechanism described above. More precisely, if you define the same text overrides for several of these text keys, the corresponding sectors are shown as one sector (using the given text) and their respective shares are added together.

For example, if both equityConsumerCyclical and equityConsumerDefensive are assigned the same text "Consumer Goods" and there is a share of 3% for equityConsumerCyclical and 4% for equityConsumerDefensive, the widget will group both together into a single sector called "Consumer Goods" with a share of 7%.

In fact, the default texts provided by the widget already group some sectors together using this mechanism.

As a special case, this means you can subsume sectors under the generic "Others" sector by assigning them the same text as general.enums.fundSectors.other.

Note that since texts are locale-dependent, this grouping of sectors may also depend on the locale. It is recommended to use the same grouping for all locales to avoid confusion.

Mandatory and optional fields in the configuration

When using TypeScript, your IDE should automatically indicate which fields are mandatory/optional via the provided typings.
When using plain JavaScript, please refer to the section above regarding mandatory/optional fields.
The widget will perform a schema validation on the provided configuration and will fail to render if the validation fails. In this case you can then find additional information on why the validation failed in the console of your browser.

Providing enumeration values in the configuration

Enumerations can be directly imported from the widget library. This works with both plain JavaScript and TypeScript. For instance, the Locale enumeration can be used like this:

import { renderFundPortfolioConfigurator, Locale } from '@munichremarkets/fund-portfolio-configurator';

const target = document.getElementById('widget-target');
renderFundPortfolioConfigurator(target, { locale: Locale.En_US, ... });

Although other ways of providing an enumeration value are technically possible (e.g. numerical or string values), it is considered improper usage and may stop working at any point.

Recommendations

Do not use a side navigation besides the widget.
Do not implement the widget in modals.
The respective widget should take as much height as it needs.
Provide at least 1440px width for the widgets.
Don't include much content above and below the widget.

Due to the scrolling behavior of the widget, it is recommended that you allow the widget to take the full height of the page with possible exceptions being a header and a footer. The widget assumes that a sticky header may be present on mobile viewports but not on desktop viewports. This distinction comes into play when the widget automatically scrolls to the top because this means scrolling to the top of the page on mobile viewports but to the top of the widget for desktop viewports.

Styling

Framework

The Fund Portfolio Configurator widget uses version 4.x of the Bootstrap framework for styling. When integrating the widget into your website, you need to do different things depending on whether your website uses Bootstrap, too:

Case 1: Your website uses Bootstrap

In this case, Bootstrap CSS rules are already present on your website and all the Bootstrap theme colors defined by your website will automatically be used by the widget. Note that the supported range of Bootstrap versions is from 4.2 to 4.6 (inclusive).

Case 2: Your website does not use Bootstrap

In this case, you are required to set the includeBootstrap4Css flag to true when invoking the widget rendering function, so that the Bootstrap 4.x CSS rules shipped with the widget are included on your page. Those CSS rules will not affect the appearance of elements outside the widget because they are scoped to the .sri-widget CSS class that is assigned to a DOM element the widget is rendered into.

Adaptation of styling

By default, the styling of the widget automatically adapts to the styling of your website to a certain extent. However, you can still customize the appearance if necessary.

Automatic styling

Fonts

Since the widget does not define its own font, any font you define in the DOM tree above the widget will automatically be used within the widget.

Note: If your website uses external web fonts, e.g. from Google Fonts, you need to set crossorigin or crossorigin="anonymous" on the corresponding <link> tag. Otherwise, those web fonts cannot be used in certain parts of the print views produced by the widget, and you will see a fallback font instead.

Example:

<link href="https://fonts.googleapis.com/css2?family=Roboto" rel="stylesheet" crossorigin />

Spacings

Font sizes and most of the spacings are defined in units of rem (root em), so these sizes will automatically be set relative to the font size of your website's <body> element.

Width

The widget will automatically fill the full width of its parent element.

Theming

Primary theming API: Overriding Bootstrap theme colors & CSS variables

Regardless of whether you are providing a custom-themed Bootstrap or not, certain colors (SRI colors) need to be customized. The minimal set of CSS variables that should be overridden are element, and the shades of primary and secondary:

primary-[50-900]
secondary-[50-900]
element-[0-23]
element-other

The element-* colors are used within indicators and charts (funds, categories, ...). The element-other color is used specifically for those instances where it's necessary to display an "Other" category in an indicator or chart.

By default, all additional colors are derived from those colors so overriding them should already provide a good baseline for theming.

To make sure that your settings for these variables take precedence over the defaults defined by the widget, use the CSS selector .sri-widget.sri-external like this:

.sri-widget.sri-external {
  --primary-500: red;
}

Case 1: Your website uses Bootstrap

Bootstrap theme colors: Bootstrap components used throughout the Munich Re Markets widgets will be styled correctly, CSS variables for those customized colors are expected to be available on :root. This should require no further action.

Case 2: Your website does not use Bootstrap

Bootstrap theme colors: The CSS variables referring to the Bootstrap theme colors need to be overridden:

--primary
--secondary
--success
--danger
--warning
--info
--light
--dark

To make sure that your settings for these variables take precedence over the defaults defined by the widget, use the CSS selector .sri-widget.sri-external like this:

.sri-widget.sri-external {
  --primary: red;
}

Note:

Bootstrap internally uses SCSS variables, which are only present at build time. Since you will use the Bootstrap CSS rules shipped with the widget if you don't provide your own, components provided by Bootstrap will not be themed properly by just overriding the CSS variables. Also, classes like .text-primary, .bg-primary etc. will use wrong color values. In those cases the according CSS classes have to be overridden individually (see next section).
Any style overrides except changing Bootstrap theme colors may stop working at any point and hence need to be thoroughly tested on every upgrade.

Secondary theming API: Overriding CSS classes

You can override each style of the application via CSS classes individually. Therefore, it is important to know the basic markup of the widget, which looks like this:

<!-- Passed into the rendering function by your website -->
<div>
  <!-- Created by the rendering function -->
  <div>
    <div class="sri-widget sri-external">
      <div class="sri-fund-portfolio-configurator">
        <!-- Widget content -->
      </div>
    </div>
  </div>
</div>

If you want to style an element within the main content of the widget, prefix all CSS rules with .sri-widget.sri-external to ensure that your CSS rule is more specific than the ones shipped with the widget and hence overrides the latter. For example, to style a button (.sri-btn), use a CSS rule like this:

.sri-widget.sri-external .sri-btn {
  /* ... */
}

If you use other widgets on the same page and need to scope a rule specifically to the Fund Portfolio Configurator widget, additionally include the widget-specific class like this:

.sri-widget.sri-external.sri-fund-portfolio-configurator .sri-btn {
  /* ... */
}

There is one special case: Some elements need to be rendered directly into the <body> of your website to ensure that they cover other elements, e.g. modal dialogs and tooltips. For these elements, the markup looks like this:

<div class="sri-widget sri-external sri-fund-portfolio-configurator sri-modal">
  <!-- Modal content -->
</div>

In this case, you can override styles within the modal using CSS rules like this:

.sri-widget.sri-external.sri-fund-portfolio-configurator.sri-modal .sri-btn {
  /* ... */
}

Notes:

Use !important for rules originating from Bootstrap. This is because Bootstrap already declares all rules as !important, so your rules need to be !important, too, in order to override the Bootstrap rules.
Any style overrides except changing Bootstrap theme colors may stop working at any point and hence need to be thoroughly tested on every upgrade.

Recommendations for mobile viewports

Viewports in the "Extra small" (xs) and "Small" (sm) ranges of the responsive breakpoints defined by Bootstrap, i.e. narrower than 768px, are considered "mobile" viewports and larger ones are considered "desktop" viewports.

Although the Fund Portfolio Configurator widget is generally responsive across all breakpoints, there are significant changes in layout between mobile and desktop viewports. Hence it is recommended to test your website in both variants.

Browser support

The following browsers are supported:

Chrome (latest version)
Firefox (latest version)
Safari on macOS and iOS (latest two major versions)