AX1209

Bubble Chart component for Axiom forms

The Bubble Chart component illustrates data with three variables using a collection of points, where one variable determines a data point's position on the horizontal axis, and a second variable determines the data point's position on the vertical axis. The third variable determines the relative size of the data point.

Bubble charts are part of the ScatterChart family, which includes scatter line and scatter charts. All of these charts use the same data source type (ScatterChart) and have the same basic component properties.

Defining a bubble chart is a two-part process that requires the following:

Creation of a ScatterChart data source in the spreadsheet to define the data to display in the chart.
Placement and configuration of a Bubble Chart component on the Axiom form canvas.

NOTE: Your Axiom Software license determines whether you have access to this component. For more information, see Licensing requirements for Axiom forms.

Data source tags

Bubble Chart components must have a defined data source within the source file to indicate the data for the chart. The tags for the data source are as follows:

Primary tag

[ScatterChart;DataSourceName]

The DataSourceName identifies this data source so that it can be assigned to a chart component. Data source names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save.

The placement of this primary tag defines the control column and the control row for the data source.

All column tags must be placed in this row, to the right of the tag.
All row tags must be placed in this column, below the tag.

Row tags

[Series]: Each row flagged with this tag defines a data point to be displayed in the chart. Multiple rows can belong to the same series, depending on the name entered in the [SeriesName] column.

Column tags

[XValue]

This column contains the values to determine the x-axis position (horizontal) of each data point.

[YValue]

This column contains the values to determine the y-axis position (vertical) of each data point.

[Size]

This column determines the size of each data point (bubble) within the series. You can enter any relevant values for the data point; the bubble size in the chart will be rendered proportionally to the other size values in the series (meaning, the largest value will render as the largest bubble in the series, the next largest value will be a slightly smaller bubble, etc.). This column does not apply to Scatter Charts or Scatter Line Charts.

[Label]

Optional. This column contains the name of each individual data point in the chart. By default, the label will display in a tooltip when the user hovers over the data point. If labels are enabled for the chart, then the label will also display next to the data point within the chart. This tag is not added by the data source wizard; you must manually add it to the data source if you need it.

[Color]

Optional. This column specifies the color assignment for each series or each data point. If omitted, then colors will be dynamically determined based on the style, theme, or skin (in that order). See Specifying chart colors. This tag is not added by the data source wizard; you must manually add it to the data source if you need it.

If you are specifying colors and you want the color to apply to the entire series, then only use one color entry per series (leaving the rest blank), or repeat the same color entry on all items of the series.

[ID]

Optional. Enables the ability to select data points in the chart. This column can contain any value that uniquely identifies each data point, such as numbers or names. This is only necessary if you want to implement interactivity for the form based on the currently selected data point. If you do not need this column, it can be omitted, and then users will be unable to select data points in the chart. For more information, see Interactive behavior.

Column tags (optional, series-wide)

All of the following tags are optional and apply to the entire series, not just the current data point. If you use any of these series-wide tags, you should make sure that each entry in the tag is the same for all data points that belong to the same series. If different entries are found within the same series, the first entry is used.

[SeriesName]: This column contains the names of each series in the chart. Multiple data points in the chart can belong to the same series by entering the same series name in this column. If this column is omitted, then all data points in the chart belong to a single unnamed series.
[Kind]: This column indicates the kind of each series, either Scatter, ScatterLine, or Bubble. If omitted, then all series in the chart will use the Default Series Kind defined in the component settings.
[VisibleinLegend]: This column indicates whether a series is shown in the chart legend, if the legend is enabled. If omitted, all series are shown. Indicate True or False. This tag is not added by the data source wizard; you must manually add it to the data source if you need it.

NOTES:

The primary tag must be placed in the first 500 rows of the sheet.
Formulas can be used to create the tags, as long as the initial bracket and identifying keyword are whole within the formula. For more information, see Using formulas with Axiom feature tags.

The following example shows simple data flagged in a sheet. In real implementations this data would most likely be generated by an Axiom query or Axiom functions; here the data is simply typed in order to show the placement of the tags to the data. This example shows only the columns that are added by the Data Source Wizard; if you want to use the other columns then you must manually add them.

To use the Data Source Wizard to add the tags to a sheet, right-click in the cell where you want to start the data source and then select Create Axiom Form Data Source > Bubble Chart. If the data already exists in the sheet, you can first highlight the labels and data and then use the wizard. Axiom Software will add the tags as displayed in the example above, including adding the [Kind] column. The cells in the row above and the column to the left of the highlighted area must be blank in order for Axiom to place the tags in sheet.

The resulting chart would appear as follows:

NOTE: The labels for the X-Axis and Y-Axis ("Population" and "Avg Income") are defined in the component properties, not in the data source. It is also recommended to use the optional [Label] column to define a label for each bubble. You can choose to display the labels next to each bubble in the chart, or have them only display in tooltips when hovering the cursor over the bubble.

Component properties

You can define the following properties for a Bubble Chart component:

Component properties can be configured using the Form Assistant task pane or the Form Designer unless otherwise noted. All properties can also be defined on the Form Control Sheet directly if desired. For example, if you want a property to be dynamic depending on the result of a formula, you can define that formula in the control sheet. To access the control sheet settings for the component, double-click any property name to go to that property in the Form Control Sheet.

Component behavior properties

The following properties control the display and behavior of this particular component type.

Item	Description
Data Source	The data source for the chart. You must have defined the data source within the file using the appropriate tags in order to select it for the chart. NOTE: In the Form Control Sheet, the selected data source is written as SheetName!DataSourceName. The sheet name is the sheet where the selected data source is located. If a data source is already specified and you want to locate it within the file, click the Show location button to the right of the drop-down list. This will move your cursor to the associated data source tag in the file.
Data Source Load	Specifies the loading behavior of the component: Inline (default): The component properties and data are both loaded when the form is loaded. This behavior causes the overall form load to take longer, because the component data must be loaded before any of the form can display on the web page. However, once the form does load, the component is fully rendered. Asynchronous: When the form is loaded, the component "shell" is loaded and rendered on the web page without the underlying data from the data source. This behavior speeds up the initial load of the form, because it does not have to wait for the component data to load. Once the form is rendered, a second pass is performed to load the component data. A loading spinner displays within the component "placeholder" until the data has finished loading.
Auto Submit	Specifies whether the Axiom form is automatically refreshed when a user selects a data point in the chart. The data source must contain an `[ID]` column in order to select data points. By default, this option is disabled. You should leave this option disabled if you have not set up your chart to support interactivity. If enabled, then the form automatically refreshes when the user selects a data point in the chart. It is recommended to enable this option if the chart is set up to support interactivity, so that the user gets immediate feedback on their selection.
Selected ID	The ID for the currently selected data point in the chart. This setting is optional and should only be used if you want users to be able to select a data point to impact the Axiom form in some way. The data source must have a `[ID]` tag in order to use this feature. This setting serves two purposes: It defines the initially selected data point in the chart, if you want the chart to start with a particular data point selected. You can leave this blank to specify that no data point is selected, or enter an ID from the ID column in the data source. When a user views the form and selects a data point in the chart, the ID of the user's selection is submitted back to the source file and placed in this cell on the Form Control Sheet. Formulas can reference this cell in order to dynamically change the form based on the currently selected data point in the chart.
Title Text	The title text for the chart. This text displays in the title bar of the chart panel within the Axiom form, if the title bar is enabled. If the title bar is not enabled, then the text displays centered over the top of the chart. NOTE: The font type / size / weight / style of the title text are dependent on the style or skin and cannot be changed.
Show Title Bar	Specifies whether the title bar is visible. By default this option is enabled, which means that the component will display in a bordered box with a title bar across the top. The defined title text displays within the bar. The formatting of the title bar and its border are determined by the skin specified for the form. If disabled, then the title bar and its border will not display on the component. If the title bar is enabled and the component also has a separately defined border (either via a style or by using the formatting overrides in the advanced component settings), then both borders will display on the component. In some cases this effect may be desired; in other cases one of the borders should be disabled.
Legend	The location of the chart legend. You can specify None for no legend, or specify a location such as Top, Bottom, Right, or Left. If you are using a legend, and you want to omit a series from displaying in the legend, you can use the optional column `[VisibleinLegend]` for the data source. Legends not only identify each series in the chart, they can also be used to dynamically show and hide series in the chart. Users can click on a series name in the legend to toggle that series hidden and visible.
Default Series Kind	Specifies the default kind for series in the chart, to be used if the Kind column is omitted from the data source, or if an entry in the column is blank. Select either Bubble, Scatter, or Scatter Line. When you place a chart component on the canvas, the Default Series Kind is automatically set based on the type of chart you used. For example, if you drag and drop a Bubble Chart on the canvas, then the default is automatically set to Bubble.
Show Labels	Specifies whether labels will display next to each data point in the chart. Labels are defined in the optional [Label] column within the data source. If your chart has many data points, you may want to disable this setting to avoid clutter in the chart. The labels will still display in tooltips when the user hovers over the data point, if labels are defined in the data source.
Show Grid Lines	Specifies whether gridlines display on the chart. By default, this is enabled.
Show Axes	Specifies whether the axis labels display on the chart. By default, this is enabled. Disabling this option hides the scale values for both axes. NOTE: If an optional Y-axis label is defined, it will display regardless of this setting.
Y-Axis Label	Optional. Enter a label for the Y-axis (vertical). This will display next to the Y-axis scale. For example, if the scale is dollars in millions, you can define a label of "Dollars" or "Dollars in Millions".
Y-Axis Format	Optional. Specify the format for the Y-axis: Number (default), Currency, or Percent. NOTES: If you select Currency, the currency symbol is determined by your operating system locale. This setting only impacts the Y-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet.
Y-Axis Decimals	Optional. Specify how many decimal places to show on the Y-axis labels. By default, no decimal places are shown (0). NOTE: This setting only impacts the Y-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet.
Y-Axis Min Y-Axis Max	Optional. Specify the maximum value and the minimum value for the Y-axis labels. If omitted, the maximum and minimum values will be determined by the values in the series. For example, you might use this option if you want to show a full percent scale from 0% to 100%, even though the minimum and maximum values in the series are 25% and 83%. NOTE: If the series format is percent, the minimum and maximum values should be entered in the decimal equivalent. For example, enter 1 if you want the maximum to be 100%.
Y-Axis Scale	Optional. Specifies a scaling property for the numbers displayed along the Y-axis. By default, no scale is applied. Enter a number to scale all Y-axis numbers by that value. The Y-axis numbers will be divided by the specified value. For example, if a Y-axis value is 25,000,000 and the scale is 1000, the value will be displayed as 25,000. If the scale is 1000000, then the value will be displayed as 25. NOTES: This setting only impacts the Y-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet. If a scale property is defined, the Min and Max values should reflect the original values before scaling is applied, not the scaled values. For example, enter 35,000,000 if you want that to be the top value on the Y-axis scale, not 35.
X-Axis Label	Optional. Enter a label for the X-axis (horizontal). This will display next to the X-axis scale. For example, if the scale is dollars in millions, you can define a label of "Dollars" or "Dollars in Millions".
X-Axis Format	Optional. Specify the format for the X-axis: Number (default), Currency, or Percent. NOTES: If you select Currency, the currency symbol is determined by your operating system locale. This setting only impacts the X-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet.
X-Axis Decimals	Optional. Specify how many decimal places to show on the X-axis labels. By default, no decimal places are shown (0). NOTE: This setting only impacts the X-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet.
X-Axis Min X-Axis Max	Optional. Specify the maximum value and the minimum value for the X-axis labels. If omitted, the maximum and minimum values will be determined by the values in the series. For example, you might use this option if you want to show a full percent scale from 0% to 100%, even though the minimum and maximum values in the series are 25% and 83%. NOTE: If the series format is percent, the minimum and maximum values should be entered in the decimal equivalent. For example, enter 1 if you want the maximum to be 100%.
X-Axis Scale	Optional. Specifies a scaling property for the numbers displayed along the X-axis. By default, no scale is applied. Enter a number to scale all X-axis numbers by that value. The X-axis numbers will be divided by the specified value. For example, if an X-axis value is 25,000,000 and the scale is 1000, the value will be displayed as 25,000. If the scale is 1000000, then the value will be displayed as 25. NOTES: This setting only impacts the X-axis numbers. The actual chart values (shown in tooltips) will continue to display as they are formatted in the spreadsheet. If a scale property is defined, the Min and Max values should reflect the original values before scaling is applied, not the scaled values. For example, enter 35,000,000 if you want that to be the top value on the X-axis scale, not 35.
Bubble Units	If the chart is a Bubble Chart, specify a label for the bubble sizes. This label will display on the tooltip when a user hovers their cursor over a bubble. For example, if the bubble sizes represent the number of beds in a hospital, you might enter "Beds" as the bubble units. The tooltip would then display text such as "500 Beds".
Bubble Size Format	If the chart is a Bubble Chart, specify the format of the bubble sizes: Number (default), Currency, or Percent. This will impact the display of the size value in the tooltip when a user hovers their cursor over the bubble.
Bubble Size Decimals	If the chart is a Bubble Chart, specify how many decimal places to show for the bubble sizes. By default, no decimal places are shown (0). This will impact the display of the size value in the tooltip when a user hovers their cursor over the bubble.

General properties

The following general properties are available for all components:

Item	Description
Component Name	The name of the component. This is for identification in the file; this name does not display on the Axiom form canvas. The name of the component identifies the corresponding settings for the component on the Form Control Sheet. The component names are also useful if you have multiple types of the same component within an Axiom form, so that you can tell which component you are currently editing. Component names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save. NOTE: Spaces are not allowed in component names and will be automatically removed by Axiom Software. For example, if you enter "My Component" as the component name, it will be automatically adjusted to "MyComponent".
Visible	Specifies whether the component is visible on the Axiom form (On/Off). By default this is set to On. This setting can be used to dynamically show or hide the component using a formula. Keep in mind that if you have multiple components that you need to dynamically show or hide based on the same condition, then it is preferable to place those components on a dedicated layer and then show or hide the entire layer instead of the individual components. NOTE: This setting is only available on the Form Control Sheet; it cannot be set in the Form Assistant or in the Form Designer.
Layer	The layer that the component belongs to on the Axiom form canvas. In the Form Assistant and the Form Designer, this displays as the layer name (for example: Layer 1). In the Form Control Sheet, this is recorded as the layer ID (for example: 1). If the canvas only has one layer, then the component is automatically assigned to that layer and cannot be changed. If the canvas has multiple layers, you can assign the component to any layer using the drop-down list. By default, the component will be assigned to whichever layer is selected in the Layers box when you initially drag the component onto the canvas. For more information on layers, see Using multiple layers on the canvas. If desired, you can jump to the applicable layer settings on the Form Control Sheet by clicking the binoculars icon next to the drop-down list.
Parent	The parent component that this component is assigned to. If blank, then the component does not have an assigned parent. Currently, only Panel components can be designated as parents. If a component has an assigned parent, then that component is positioned within the parent instead of within the canvas at large. If the parent is hidden, all "child" components of that parent are also hidden. The parent assignment is automatically completed when a component is dragged into a panel in the Form Designer, and automatically cleared when a component is dragged out of a panel. In most cases, you should not need to manually assign a parent. For more information, see Using panels to group and position components.

Style and formatting properties

To define the component formatting, you can assign one or more styles to the component. Styles can impact formatting properties such as fonts, borders, and colors.

If you do not want to apply a style to this component, or if you want to override one or more formatting properties in an assigned style, click the Show Advanced Settings link underneath the Style box to display the individual formatting properties. For more information on defining individual formatting properties for a component, see Formatting overrides for Axiom form components.

Currently, the Axiom Software platform does not provide any styles specifically designed for charts in the ScatterChart family. Only the generic styles are available.

Item	Description
Style	Optional. The styles used to determine the formatting of the component. You can assign one or more styles. Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles. Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.
Component Theme	(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme. This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary. This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override. NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Item

Description

Style

Optional. The styles used to determine the formatting of the component. You can assign one or more styles.

Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles.

Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.

Component Theme

(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme.

This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary.

This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override.

NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Position and size properties

You can view the position and size properties for a component by clicking the Show Advanced Settings link under the Style box. If necessary, you can edit these properties directly (instead of automatically modifying them by adjusting the component's position and size on the canvas). For more information on using these settings, see Controlling component position and size.

Item	Description
Reference Location	The reference location determines how the x-position and y-position of a component are evaluated. By default the reference location is UpperLeft. NOTE: This setting is not exposed in the advanced component settings. It can be changed on the canvas by double-clicking the corner selection handles of a component, or you can edit the setting on the Form Control Sheet directly.
X Position Y Position	The x-position determines the component's position along the horizontal axis, and the y-position determines the component's position along the vertical axis. Both are evaluated relative to the reference location. Positions can be set in pixels (default) or percentages.
Width Height	The width and height determine the size of the component. The width and height can be set in pixels (default) or percentages. Size keywords are also available to support special behavior.
Rendering Order	The order in which the component is rendered in the layer. A component with a larger order number will display above a component with a smaller order number. For components that support tab navigation (tabbing to the next editable component), the rendering order also determines the tabbing order. NOTE: On the Form Control Sheet, this setting is labeled as Z-Index.
Lock Layout	If enabled, the component size and position are locked and cannot be changed by dragging and dropping on the canvas. This optional setting is intended to protect against accidentally moving or resizing a component while working on the canvas.

Interactive behavior

If the [ID] column is used in the data source, then users viewing the Axiom form can select a data point in the chart. The ID for the selected data point is submitted back to the source file and written to the Selected ID setting on the Form Control Sheet. Once a data point is selected, the user can either click on a different data point to change the selection, or click on the same data point to clear the selection.

If you want the Axiom form to respond to the currently selected data point, then you must set up the file so that another component references the selected ID and changes based on it. For example, an Axiom form could contain another chart or a grid that dynamically changes data based upon the currently selected data point in the chart. For more information on setting up interactive components for an Axiom form, see Using interactive components in an Axiom form.

Note the following when setting up the IDs for the data points in the data source:

IDs must be unique. Only one data point in the chart can be selected at a time. If IDs are not unique, the chart will not behave as expected.
If a data point does not have an ID (the cell is blank), then that data point is not selectable. Clicking on that data point will not result in an ID being written back to the source file.