Custom language allows you to supplement your narratives with custom insights specific to your business. Builders can leverage the analytics and data from the extension and apply their own language or sentence structure to create the most impactful story for the reader. As with the narrative as a whole, data/variables used in custom content are dynamic, adjusting along with the dashboard.
- Adding Custom Content
- Copying Content
- Setting Context Variables
- Special Note on Drilldown Sections
Adding Custom Content
To create custom content, open the "edit" modal. At the bottom of each section is a button - "Add custom story item."
This will bring up an empty "bullet" that can contain any language you desire. This feature is used to bring in custom, dynamic, references to data points that form new sentences focused on the things you care about.
To insert variables or data points, select the fx button on the right of your custom content to add a function.
Select a function from the list of dropdowns and fill in the required fields. For example, if I wanted to know the state with the highest profit, I would select MaxLabel as my function and then designate the measure as ‘profit’. This would return the name of the state.
If I wanted to know the profit value of that state, I would insert another function into my text called MaxValue and follow the prompts given.
Determining exactly when and how to communicate certain information can be just as important as the information itself. As with our out-of-the-box content, custom insights need to account for different scenarios that may arise. For example, you may want to word the sentence differently if that figure was higher or lower than expected. Conditional statements allow the builder to introduce this kind of logic.
For each custom sentence, you have the option to use a conditional statement to govern whether or not the sentence writes. To adequately cover all the scenarios that might arise for a single insight, consider adding multiple variations (custom bullets/sentences) and apply conditional logic to each to ensure only the most appropriate scenario writes.
To the right of the custom language text box is an icon that will bring up the conditional logic. The conditional statement is set up as a True/False statement. If the condition is true, the custom language will write. If not, nothing will print.
Multiple conditions can be applied to each custom sentence, and can be combined using the "Any" or "All" toggle. This corresponds to "Or" and "And" statements, respectively.
Conditional statements are most often used with numerical comparisons, but it also supports string matching by using the equal (=) or not equal (!=) symbols.
For example, let's say the custom sentence added above ought to only be present when the profit ratio of the state with the highest profit exceeded 0.5.
First, define the custom function to be used to inform the conditional logic:
Next, after adding the function, inform the conditional logic with a specific criteria to be applied to that custom function:
The copy buttons allows a user to easily copy an entire custom bullet making it much easier to build different variations of a sentence.
Copying a fully built out custom bullet is a very common and even recommended practice when applying thresholds, building in language variation, and creating different logical variations.
How it works:
- The copy button will copy the entire custom bullet, including any functions used as well as any conditional statements applied to that bullet.
- The copied bullet will appear directly below the original bullet in the same section.
- Note: you cannot copy a bullet to another section.
Setting Context Variables
Context variables is a function that can be referenced by other functions. In other words, it allows you to nest functions within other functions.
First, the context variable is defined by the user, and then it will appear in argument dropdowns for any other function used in the custom content (including conditionals).
Context variables are defined separately for each piece of custom content. You can have multiple context variables per custom bullet.
Adding a context variable - The menu to the right of a custom bullet will reveal an option called "set context." From there you can "add context". Name the context variable and define the associated function. After you save the context variable, you will see it in the dimension value dropdowns for any function you add to your custom content.
Special Note on Drilldown Sections
For two-dimension stories, the second section on down are drilldown sections that each focus on an individual primary dimension entity (e.g. Consumer or Corporate in the example below). Since each of these sections have the same general content structure, custom content in these sections will be applied to the following similar sections.
How it works:
- You can only create or edit content in the first drilldown section. The custom content that will appear in the following sections is not editable.
- Custom content in these sections will already have a context variable created for them called Current Category value (dynamic). See above for more information on context variables.
- This creates a dimension value option called Current Category value (dynamic) which always represents the entity that the drilldown section is about.
- By default, every custom insight created in the first dimension drilldown section will be applied to all dimension drilldown sections.
- To create content that only appears in a single/specific drilldown section, the user can employ conditional logic to ensure it only prints where appropriate.
- Note: while the method of using conditionals to control the content is recommended, it is still possible to use the toggle button to turn off any of the resulting custom bullets
Any users that had created custom content across dimension drilldown sections prior to the rollout of this new feature (Sept 2020) will see that all their content that existed within any dimension drilldown section has 1) been moved to the first dimension drilldown section, and 2) will be duplicated across all drilldown sections. These users will receive a banner message when they open the edit modal for the first time in that dashboard. They will be able to see these changes and make any necessary adjustments.