File Structure for the React Format Panel

This feature is available starting in MicroStrategy 2021 Update 3.

This topic details the structure of the Format panel files.

• Files

• Components

• Properties

  • Add New Properties

  • Use a Single Unified Property

• Middle Layer (Query and Apply)

Files

The FormatPanelConfig folder contains the following Format panel files and folders:

• container-config (required) This folder contains all components used in the Title and Container (third) tab. These files are used for all visualizations. This folder does not require any modifications.

• shared-config (required) This folder contains components used for the container-config and custom (first and second tab) configs. This folder does not require any modifications.

  • font-section.js Contains components used for changing font family, options color, and size

• textAndForm (required) This folder contains all configs for the Text and Form (second) tab.

  • textAndFormConfig.js Custom config that contains all components placed in the Text and Form (second) tab.

• vizOptions (required) This folder contains all configs for the Visualization Options (first) tab.

  • textAndFormConfig.js Custom config that contains all components in the Visualization Options (first) tab.

• apply.js (required) Contains a middle-layer function that is triggered after changes in the Format panel. Allows the update of property values.

• query.js (required) Contains a middle-layer function that is triggered before each visualization refresh. Allows the management of component states inside the Format panel.

• properties.js (required) Contains an array of all property names.

• config.js (required) The main config for the Format panel.

• enums.js (optional) Allows the simplification of properties management. This file does not duplicate enum names, but uses existing ones.

• utils.js (optional) Contains all functions used inside query.js and apply.js.

Components

See Component API for the React Format Panel for descriptions of the available components and their corresponding attributes.

Properties

All interactive components used in the Format panel must have an assigned key property. A key property is a reference to a property name.

Property initialization is performed using the setDefaultPropertyValues function. Before using the key property for associated components, make sure that the property has been initialized. Otherwise, unexpected issues can occur.

It is a good practice to use enums to reference to property names.

In the sample visualization, the definition of all properties is included in src/properties/propertiesInfo.js file. The structure allows you to define a name, enum, and default value at the same time. To avoid the duplication of code, those property definitions are used in the Format panel. Therefore, there is a direct connection between the mentioned file and formatPanelConfig/enums.js.

To ensure interaction between mojo and the React Format panel, all properties must be grouped under a single array in formatPanelConfig/properties.js.

Add New Properties

All property logic is applied to avoid duplication of enums and also simplify the way the properties are defined. To define a new property, add a new object assigned to an enum under the PROPERTIES_INFO variable in src/properties/propertiesInfo.js.

Use a Single Unified Property

In some situations, one change in the Format panel updates several properties. One example of this is changing a template style. This change may update several fonts and background colors.

The traditional way of updating the Format panel was to modify the values in a specific order. However, the API behaves in a synchronous way and each function call to make updates takes roughly 0.3s. Updating several properties at once leads to noticeable loss of performance.

One solution is to store all properties inside one large property. Let's call this property, unifiedProperty. This way you can use a single function call to update properties, regardless of how many are changed. There is no performance degradation when updating a single individual property or when updating properties that exist as part of the larger, unifiedProperty.

Properties assigned to components are stored under one variable. As a result, each time an action occurs in the Format panel, the variable is parsed, updated, and saved within the dashboard.

Middle Layer (Query and Apply)

The following functions assist in property management for the Format panel:

• query This function enables the management of a component's state. The function is triggered before a visualization is rendered each time. Assigned property values determine whether a component is visible/invisible, enabled/disabled, or what value is applied to the component.

• apply This function is triggered when users make changes in the Format panel. The function updates properties and performs other custom functions.

See Advanced Functionality: Implement a Middle Layer for the React Format Panel for more information.