Name and description

After a report has been successfully run at least once, you can change its name and description:

1. From the report editor, click Report in the header and then click Rename.
2. Enter a name and, optionally, a description.
3. Click Save.

You can remove the report's name and/or description from the report layout using the HTML editor.

Colors and themes

Your Mode Workspace includes a number of chart color palettes and report themes that you can use to quickly change the look and feel of the reports that you create.

Color palette: The set of colors used for various elements in built-in charts and visualizations, including series markers. You can browse and select color palettes in the Chart Settings box on the right side of the chart builder:

1. Click on the Color dropdown.
2. Select a palette from the menu below.
3. Click Assign Palette to apply your selection to your visualization.

Report theme: The set of styles controlling various aspects of a report's look and feel (e.g., background color, fonts, etc.). Themes can be applied to a report in report settings. In addition, you may style any report by including custom CSS using the HTML editor.

Custom color palettes and report themes may be defined for Workspaces on a paid plan.

Report details

Open a report and click View Details in the header to see additional details about the report, including the logic and data behind it. Along the left side you may see some or all of the following sections, depending on your level of access to the report:

• Details: Includes the names of any collaborators (users who have modified the report) and the report's run history.
• HTML: The HTML code that defines the report layout as well as any embedded custom HTML, JavaScript or CSS.
• Notebook: Any input, output, and markup cells (including Python or R code) if defined in the report's Notebook.
• SQL and Results: The SQL code and results for each query in the report.

Run history

Every time you run a report, Mode saves a copy of its configuration and results (excluding Notebook code, HTML, Chart configuration, and Calculated Field formulas) so you can see exactly how a report looked from a given point in time. A historical run is saved even if the queries in the report do not complete successfully. Historical report runs are accessible indefinitely unless the report is deleted.

You can access a report's run history from report details. Click on one of the historical report runs in the list to view the report as it appeared at that time. Each historical run has a unique static report run URL so that specific run can be shared with others.

Report builder

The report builder is a drag-and-drop interface for laying out and adding context to the components of your report. When editing a report, access the report builder by clicking on Report Builder on the left side of the window.

Common keyboard shortcuts are available while editing. You can re-arrange or re-size your text elements the same way you would any other report element. To remove a text box, click on it and then click Remove in the toolbar.

To move a component, click and drag it to move it around the layout. To resize a component, click on it and the drag the grab icons on either side to change its width, or click Set Height to adjust its height. You may choose between small, medium (the default size), and large. For display tables, you may also set the height to full to show up to 1000 records.

Text boxes

In the report builder, you can add text boxes (including text, links, images and more) to provide more context for your report:

1. In the report builder, click Add Text.
2. Add any text or links. You can also embed an image.
3. When you are finished editing, click anywhere outside the text box to save.

HTML editor

To modify the HTML of a report, click Edit HTML at the top of the report builder. After modifying code in the HTML editor, click Update to preview your changes. Any valid HTML can be added to a report using the HTML editor, including JavaScript inside <script> tags and CSS inside <style> tags.

The report's HTML will automatically adjust as you rearrange and resize any of the elements using the drag-and-drop interface. However, for more fine-grained control over report layout and styling, or to add advanced visualizations using JavaScript, you must use the HTML editor.

This report shows how you can combine various built-in and custom visualizations. Use the Details tab to view the HTML code and see how it works.

Layout grid

Built-in charts (including tables), text boxes and Notebook visualizations are automatically arranged along a 12-column grid inside a div of class mode-grid container. The structure of the HTML is shown below:

<div class="mode-grid container">     <!-- The container div for the report grid layout.        -->

  <div class="row">                   <!-- There is a div with class "row" for each row.        -->

    <div class="col-md-7">            <!-- Each chart is inside a div with class "col-md-X".    -->
      <mode-chart ... ></mode-chart>  <!-- X equals the the number of columns wide (of 12) the  -->
    </div>                            <!-- chart should be. This chart is 7 of 12 columns wide. -->

    <div class="col-md-5">            <!-- The second chart is 5 columns wide, occupying the    -->
      <mode-chart ... ></mode-chart>  <!-- remaining space in same row as the first chart.       -->
    </div>

  </div>

  <div class="row">                   <!-- This div starts a new row of report components.      -->

    <div class="col-md-12">           <!-- Since this div has the class "col-md-12", the        -->
      <mode-chart ... ></mode-chart>  <!-- component nested within it (a chart) will fill        -->
    </div>                            <!-- the entire row.                                      -->

  </div>

</div>

The HTML for the layout grid will update automatically as you modify elements in the drag-and-drop interface of the report builder. However, please note:

• Deleting a reference to a chart or table from the report's HTML will remove it from the layout, but will not delete the underlying chart or table from the report editor.
• You can add custom HTML elements (e.g., paragraphs, images, links, etc.) within or outside the grid generated for you by Mode. Note that adding custom HTML elements within the grid generated for you by Mode (i.e., inside the div tags with class mode-grid container) will result in unexpected behavior and as such is not recommended at this time.
• We recommend positioning and sizing built-in visualizations with the drag-and-drop interface before modifying the HTML directly, because custom HTML content cannot be modified using the drag-and-drop interface.

The report's name and description are automatically added to all reports inside a <div> with the class mode-header. Either can be removed from the layout by deleting them using the HTML editor. When a report is embedded, the contents of this <div> (including the name and description), will not be rendered in the embed output unless the embed-hidden class is removed.

External assets

You may include external assets (e.g., JavaScript libraries, stylesheets, images, JSON files, etc.) in your report by referencing them via URL with the appropriate tags in the report's HTML. Note:

• Any external assets must be hosted on the internet (Mode does not host custom assets) and loaded securely using HTTPS, not HTTP.
• D3 (v3.1.5) and JQuery (v1.10.2), two JavaScript libraries commonly used for data visualization, are pre-loaded into all Mode reports. You do not need to add <script> tags to your report to use these libraries.

For example, consider the following Population Map report, specifically the HTML code:

• JavaScript libraries TopoJSON and Underscore.js are included at the beginning of the <body>tag.
• A hosted JSON file required to draw the U.S. map is loaded on line 257.

Loading state customization

In the HTML editor or in a custom theme you can target a number of CSS classes to customize elements of a report's presentation while data is being loaded and visualizations are being rendered:

• .editor-chart .chart-header: The title of the fully rendered visualization (charts and notebook output).
• .mode-placeholder .placeholder-title: The title of the chart placeholder.
• .mode-placeholder .loading-message: The message appearing in a chart placeholder. Default: “Fetching your data...” with an animated ellipses.
• .mode-python .loading-message: The message appearing in the notebook placeholder. Default: “Fetching your notebook data...” with an animated ellipses.
• .ph-color-light: The first of three colors included in the placeholder image that appears in the center of the loading state.
• .ph-color-medium: The second of three colors included in the placeholder image that appears in the center of the loading state.
• .ph-color-dark: The third color included in the placeholder image that appears in the center of the loading state. Note: Only some of the SVGs feature three colors.

Access query results with JavaScript

Results from any query in your report can be accessed using JavaScript in the HTML editor via the datasets array available in any JavaScript scope. The content property of any dataset within datasets contains the query results.

If the query result exceeds our legacy limit, the content property of the dataset associated with this query will be empty. Note that users will still be able to view and create Mode charts and tables in these instances.

The datasets array contains the following information for each query in the report:

Queries are added to datasets[] in the order that they were added to the report, regardless of the order that they appear in Mode.

Example

For example, suppose the first query (named "2006 Oscar Nominees") in a report returned the following data:

Accessing datasets[0] would return the following JSON object containing all of the query's results and metadata (use ⊕ and ⊖ to explore):

{{< renderjson "/other/datasets-demo.json.svg" />

You can see a live example of this dataset, and learn more about accessing and using the datasets[] JSON object, in this example report.

Accessing data by query name

Use the JavaScript filter() method to search datasets[] and return the result set for that query. This example declares a new variable (data) and sets it equal to the results of a query called "My Query":

var data = datasets.filter(function(d) { return d.queryName == "My Query"; })[0].content;

Additional options

Settings

To access additional report settings from the report editor view, click Report in the header and select Settings:

• Report Theme: Applies the selected theme to the report's styling.
• Full width: Disabled by default. When enabled, report elements will expand to fill the available viewing window.
• Disable Run from the report view: Prevents report viewers from being able to run the report and underlying queries. When disabled, reports can still be run via a schedule or from the editor view.

Fullscreen mode

Fullscreen mode maximizes the content of your report so it occupies the entire screen, eliminating all other parts of the Mode interface and browser window. A report in fullscreen mode will automatically refresh and display the latest data whenever the report is successfully run unless you access it using a static run link. To enable fullscreen mode:

1. In the report header, click Fullscreen (this option may be in the More menu).
2. Your report will expand to fill the screen. Only the margins of the report will expand. The report elements themselves will not. To include more elements in your dashboard, enable full width mode in report settings.
3. To exit fullscreen mode, press the Escape key.

URL query string

You may add one or more field-value pairs to a Mode report's URL query string to control that report's behavior. You may combine multiple field-value pairs in a report's URL query string, separated by &.

run

Forces the report to re-run and refreshes all query results, Notebook output, and visualizations.

• If present in the query string, must be equal to the value now.
• Whenever a report URL is accessed that includes run=now in the query string, the report will re-run. If run=now is not included in the query string, Mode will return data from the most recent time the report was run.
• If the URL query string includes values for parameters then the report will be run each time the URL is accessed, even if run=now is not included.

The following example URL will update all queries and visualizations each time it is accessed:

https://app.mode.com/benn/reports/31baa986cdfd?run=now

param_[PARAMETER_NAME]

Specifies the value that should be used for a given report parameter of [PARAMETER_NAME].

• Parameter names and values in report URLs are case sensitive.
• Remember to URL encode any special characters used in your parameter names or values.
• If no value or an invalid value is provided for a parameter in the URL query string, the value of the default property in the parameter definition will be used.
• For multiselect parameters, each distinct value must be provided as a separate field-value pair in the format param_[PARAM_NAME][]=[PARAM_VALUE].

The following example URL will run the target report with "Midwest" and "Northeast" selected for the sales_region multiselect parameter and "2000" as the value for the order_max text parameter:

https://app.mode.com/modeanalytics/reports/a9e1fe690f93?param_sales_region[]=Midwest&param_sales_region[]=Northeast&param_order_max=2000

Report builder keyboard shortcuts

Text boxes

HTML editor