Welcome to the Juicebox documentation! Here you'll find resources and information on creating and sharing your Juicebox reports, as well as tips and troubleshooting advice. We hope you find this resource helpful.

We are continually updating the documentation to reflect what's new in Juicebox. If you spot an area that is missing or could be improved, please reach out to us to let us know.

Creating reports in Juicebox requires a computer with an internet connection and a browser. Juicebox supports the latest, stable release of the following browsers:

• Apple Safari

• Google Chrome

• Mozilla Firefox

Capture

Annotate

Share

Collect

Charts are data visualizations you can add to your report. Each slice can contain one chart. The following charts are available:

• Headline

• Filters

• Chooser

The measure ingredient editor

Header

Icon

Label (this is the same as the Label under Basics).

Each slice is limited to ingredients from a single data table. But you can use multiple data tables within the same story.

When configuring a chart in an app with multiple data tables, you select the data table to use for the chart.

New ingredients are created by duplicating an existing ingredient and then modifying it as needed. To duplicate an ingredient, open the ingredient editor for the ingredient you want to duplicate, click the the gear icon, and select Duplicate column or Duplicate. The ingredient editor for the duplicated ingredient will open, ready for you to modify and save.

The Card slice is used to display selected columns and measures on cards. Users can select cards to filter downstream results. Here's an example of a Card slice:

On the Configure tab, you can add the following:

Title. A dimension ingredient with values to display as card titles.

Long text. A dimension ingredient with values to display as card text.

Secondary data. Up to 3 measure ingredients to display on each card.

Image. A dimension ingredient with urls to images to display on each card.

All configuration fields are optional, but you must make a selection in at least one of the fields. In most cases, you will want to configure at least the Title field. There will be a card for each distinct combination of

The ingredient editor is a form used to view and edit ingredients. To access the ingredient editor, click on the ingredient pill, either in the data drawer or when configuring charts.

Different options appear in the ingredient editor depending on whether the ingredient is a dimension or a measure and whether the ingredient is a number, date, time, or place. Some of the options only affect particular chart types.

Ingredients are used to configure in Juicebox. There are two types of ingredients: and .

Dimensions

When you first load your data, you'll have one dimension ingredient for each column in your data. You can create additional dimensions from those data columns. For example, let's say your data has 3 columns: First_Name, Last_Name, and Age. After you load your data, you'll have 3 dimension ingredients corresponding to these 3 columns.

The Headline slice lets you combine images, text, and actions to create custom headers for your report or sections within you report. Here's an example of a configured Headline slice:

On the Configure tab, you can add the following:

Icon or Logo. You can select an icon or upload a logo image.

Announcement. You can add text that has a special style applied.

Announcement action. Using the Action builder form, you can add a link to a website or to a slice slug within the report. This link will appear next to the Announcement text.

Actions. Using the Action builder form, you can add a link to a website or to a slice slug within the report. Each link will appears as a button. You can have multiple Action buttons.

Feature image

The Juicebox API is documented .

Here are some tips and tricks we've learned along the way to help you build great reports:

From the data preview you can see the data table columns, each column's data type, and the first 100 rows in the data table. You can also open the dimension ingredient editor by clicking on the pill at the top of each column.

To open the data preview, first open the data drawer and then select the data table you want to view. To exit the data preview, close the data drawer.

Data types

From the data preview, you can see each column in your data and the data types for each column.

Here are data types that are recognized in Juicebox:

Certain things in Juicebox require particular data types. For example, creating a sum or average measure only works with number columns, and the chart requires a date or time column. Bottom line: Don't mix-and-match data types within the same column in your data file. Number columns should contain only numbers, date columns should contain only dates, and so on. If a column has more than one type of data, it will get the text data type.

Replace uploaded data

To update uploaded data, click the Replace file button. If there is more than one data table in your report, select the data table that you want to update. (Alternatively, select the data table you want to update, click the gear icon, and select Replace file from the menu.) Then, select the new data file (CSV, XLS, or XLSX).

Once the upload process finishes, refresh the page. The report will then display the updated data.

Clear the data cache

To improve performance, charts display cached data. The cache is cleared periodically (by default, every 2 hours), but the cache can be cleared manually by clicking the Clear Data Cache button and selecting Yes, clear it. The cache will be cleared for all data tables used in the report.

The caching period is set at the database connection level and the current options are: no caching, cleared after 2 hours, cleared after 1 day, or cleared after 1 year. If you would like the caching period adjusted for a particular database connection, .

Delete a data table

If you have a data table that you don't plan to use in your report, you may want to delete the data table to declutter the data drawer. To do this, open the data drawer, select the data table you want to delete, click the gear icon, and select Delete.

If you are sure you want to delete the data table, click Yes, delete it.

Download data

For uploaded data tables, you can download the data by opening the data drawer, selecting the data table you want to download, clicking the gear icon, and selecting Download. The data will download as a CSV.

The scatterplot chart displays a column value as a bubble plotted at the intersection of the x-axis measure and the y-axis measure. Adding a slice with a scatterplot chart (i.e., a scatterplot slice) is a good choice when users want to see the relationship between two measures.

Adding a scatterplot slice

To add a scatterplot slice:

• select Scatterplot from the chart list

• select the column with the values you want to display as bubbles

• select the x- and y-axis measures

• select the measure to use for the bubble size (optional)

• select the number of regions

Using a scatterplot slice

Selections made in the scatterplot slice will filter downstream slices. You can select individual bubbles or regions. Selecting a region will select all bubbles within the region.

Juicebox is a platform that lets you easily create and share beautiful, interactive data visualization reports. No code required.

A Juicebox report is the solution you create with Juicebox. Click here to join the Juicebox Gallery workspace to see example reports. Each report has its own URL, and you manage who can view it or make changes to it.

Parts of a Juicebox report

So what makes up a Juicebox report? Each report has the following parts that flow in a hierarchy:

• A story (or data story) is a set of charts (i.e., data visualizations), text, and media presented on a single page, similar to a data dashboard. Each story should be focused on a particular audience and purpose, and guide users to the actionable insights they need. Within each story are sections, and within each section are slices. (Support for multiple stories per app is planned for a future release.)

• Each is composed of one or more slices. Sections allow you to control layouts and background colors within the story.

• are the basic building blocks of your story. Each slice can have text and/or an image, video, or chart.

What's unique about Juicebox

Juicebox lets you easily present and communicate your data to non-technical audiences. Key elements of Juicebox include:

• No code required. You can build a Juicebox report entirely from your computer browser using the . If you know how to create pivot tables and formulas in a spreadsheet, you are ready to start building reports.

• Interactivity is automatic. Selections made in slices above flow down to the slices below by default, allowing users to drill down and drive the story where they want to go.

• Sharing is the point. Juicebox report are meant to be easily. You can decide how to share it (publicly or to only signed-in users). For reports that require a user to sign in, you can set up user data permissions so that each user only sees what they are supposed to see. The reports look great whether shared on a desktop, tablet, or phone.

The Filter slice allows users to select dimension values to filter downstream results. One or more dimensions can be included in a Filter slice and each dimension will appear as a "pill." When the user clicks on the pill, the dimension values appear in a dropdown and the user can select values from the dropdown. Here's an example of a Filter slice:

The Configure tab has the following option (in addition to the common slice configuration options):

Pick columns to filter on. Select one or more dimension ingredients to include as filters. Here's the Configure tab for the example above:

The Style tab has the following options (in addition to the common slice configuration options):

Direction. If Horizontal is selected, the pills will display side-by-side. If Vertical is selected, the pills will be stacked vertically.

Alignment. Select Center, Left, or Right to adjust how pills are aligned within the slice.

Hide counts. By default, the number of distinct dimension values will appear in the pill. Enable this option to hide the counts from the pill.

Here's the Style tab for the example above:

If you have questions or need assistance, please reach out to us. You can do this by emailing us at [email protected]. You can also chat with us from within Juicebox by selecting the help icon in the header of the workspace or app and selecting Chat with us. (The help icon is only visible for users with editing rights.)

The pie chart displays column values and their share of the whole. Adding a slice with a pie chart (i.e., a pie slice) is a good choice when users want to see parts of a whole.

Adding a pie slice

To add a pie slice:

• select Pie from the chart list

• select the column to use to represent a pie slice

• select the measure to use to determine the size of each slice

• select Value to display the actual value of each pie slice or % Percent of whole to display the share of the pie slice as a percent

Using a pie slice

You can hover over or select individual pie slices to see more detail in the center of the chart. Selecting pie slices will filter downstream slices.

By default, selections in a slice filter the data in downstream slices. You can change this default behavior by configuring slice selections.

You can configure the slice selections to act as:

1. Filters. Slice selections will filter downstream slices. (This is the default configuration.)

2. Variables. Slice selections will not filter downstream slices but will be available for use in defining ingredients.

3. Filters and Variables. Slices selections will filter downstream slices and be available for use in defining ingredients.

How to use Variables

If you configure slice selections to act as Variables, the selected values will be saved. You can use the saved values in ingredient definitions. For example, let's say you have a Filter slice with two dimesions: Genres and Directors.

Using variables in your ingredients labels

You can use variables to make dynamic ingredient labels. To start you need to know the ingredient id of the selected variable. You can open the ingredient and click the "..." and select "Copy Ingredient Id".

Use the id of the ingredient being used as a variable in the label by surrounding it with brackets like this “{{ingredient_id}}“. You can also other text in your label too, so "Budget of {{Director}}" would work if an ingredient with id of Director was a variable.The variable must be selected above. Otherwise you'll just get the label without the variable substituted.

Using variables in your ingredient's field expressions

You can use variables in your field definition. For instance, if you have selected a director in a variable, you can refer to the selected director in your field like this: field:

sum(if(Director="{{Director}}", Budget, 0))

Note the double quotes around {{Director}} because it's a string.

Using variables to define constants

You can use variables in your datasource constants. Just refer to the variable to get the first movie released by the selected director.firstMovieReleaseDate: min(if(Director="{{Director}}", ReleaseDate))

Limitations

Here are two things to keep in mind. We plan on improving these later.

• We only substitute variables in fields, singular, and plural for ingredients. We aren't substituting in buckets. We are substituting in optional fields like id_field or latitude_field.

• The variable is the first selected value. If you have multiple values selected, only the first will be available.

​

The leaderboard chart displays which dimensions rank at the top (or bottom) across multiple measures. Adding a slice with a leaderboard chart (i.e., a leaderboard slice) is a good choice when users want to quickly see the "winners" and "losers."

Adding a leaderboard slice

To add a leaderboard slice:

• select Leaderboard from the chart list

• select the column with the values you want to be ranked

• select the measures by which you want to rank the column values

• select the max rows

• add slice text (optional)

Using a leaderboard slice

If you have 10 rows in your leaderboard, you can use the LOOK AT options to see the top 10, bottom 10, or top 5 and bottom 5. (If you have 25 rows, you can opt to see the top 25, bottom 25, or top 13 and bottom 12). To see the ranking of a column value not shown in the leaderboard, you can click the filter pill and search for the dimension. Selections made in the leaderboard slice will filter downstream slices.

Selections made in a story automatically drive how the story progresses in two ways:

• focusing

• filtering

Selections that focus

Selections in charts let you focus in on a particular thing. In the example below, a user can select a measure (like Happiness or Family) using the measure chooser. The chart below shows only the selected measure.

Selections that filter

Selections in a slice will automatically filter downstream slices. This allows users to drill down on the data that is relevant to their problem.

In the example below, there are two slices. The top slice has a chart that shows regions ranked by a Happiness measure, and the bottom slice has a chart that shows which countries lead across multiple measures. Notice that when nothing is selected in the bar chart, the leaderboard shows the leaders across all countries. But when a particular region is selected in the bar chart (i.e., Western Europe), the leaderboard only ranks countries within the selected region.

For workspaces with multiple reports, users can navigate between reports from the workspace home page.

Using the home page

After signing in to your workspace, you will be on the workspace home page. Editors for the workspace will see all of the workspace reports. Viewers will only see those reports they have been given access to.

To find a specific report you can use the Sort by feature to order reports by last edit date, last publish date, or alphabetically. You can also use the Search feature to search report titles and descriptions.

To open the draft version of a report, click the Edit button. To open the published version of a report, hover or click around the report title, and then click the View Report button. (If the report has not been shared, you'll see a "Not shared yet" message.)

To get back to the home page from any report, click on the Home button in the report header.

The bar chart displays column values ranked by a measure. Adding a slice with a bar chart (i.e., a bar slice) is a good choice when users want to compare measures between categories (i.e., column values).

Adding a bar slice

To add a bar slice:

• select Bar from the chart list

• select the column to use for the bars

• select the measure you want to use for the bar width

• add slice text (optional)

Using a bar slice

Users can scroll if necessary to see all categories. Users can select one or more categories (i.e., column values) to filter downstream slices.

You can view and modify your workspace settings by going to the Settings page. To access the Settings page, click the gear icon in the upper right corner of your workspace. From there, select Settings.

Once on the Settings page, you'll be able to change your workspace name and, depending on your subscription plan, create a custom subdomain and limit app access to only email addresses from a specific domain.

You must load data before you can design your report. Data can be in a flat file (CSV, XLS, or XLSX) or in a database table (or view). You load your data by either uploading the file or, if your data is in a database, selecting the schema and table (or view) to connect to.

The data drawer is where you set up your data. To open the data drawer, click the bar at the bottom of the editing panel. Click the bar again to close the data drawer.

After you load data, you can view your columns in the data preview and configure charts using dimensions and measures.

The Reports Navigation slice displays each report the viewer has access to as a card. The viewer can select a card to navigate to that report. Here's an example of a Reports Navigation chart.

If you need to explicitly define which reports are displayed, reach out to us.

Owners can access the the Subscription page by clicking the gear icon in the upper-right corner of your workspace. From there, select Subscription.

Once on the Subscription page, you can compare plans and reach out to us about plans customized to meet your needs.

The map chart displays a as a bubble on a map. Optionally, the bubble can be sized and colored by measures. Adding a slice with a map chart (i.e., a map slice) is a good choice when users want to see geographic information.

Adding a map slice

To add a map slice:

• select Map

Get a workspace

To get a workspace, go to and click the Let's Talk button. From there, pick a time to talk or send us a message. Once we understand your needs, we'll send you instructions to create your workspace.

The trend chart displays a measure plotted over time. Adding a slice with a trend chart (i.e., a trend slice) is a good choice when users want to see how a measure changes over time.

Adding a trend slice

To add a trend slice:

• select Trend from the chart list

To control how date or time dimensions are displayed in the report, you can specify a format. For example, let's say you have a dimension called Release Year. A representative value for Release Year in your data is 2019-03-01. You probably do not want to display the unformatted value in your report. Therefore, you will want to specify a time format in the ingredient editor.

The time format specified will determine how the date or time value will display in your report. The following date formats are available for selection in the column editor:

The table chart displays selected dimensions and measures as columns in a table. Users can search, sort, and download the data. To search, click the filter pill and search for any value in the table. To sort the data by the values in a column, click on the column header. If data download is enabled, click on the Data button to download the data as a CSV or Excel file. By default, selecting rows will filter downstream results.

Configure

The Configure tab has the following options (in addition to the ):

Pick columns for your table. Select the dimension and measure ingredients to show in the table. They will appear in the order selected.

Adding viewers to a report

To add a viewer to a report with "Sign in required" access, you . Anyone who clicks on the access link and becomes a new user in your workspace with the and access to the report.

Until your report is shared, only editors in your workspace will see the changes you've made. When you're ready for others to see your report, it's time to share your work with viewers. There are two steps to sharing a report:

1. Publish the report (or changes to the report)

2. Invite viewers

You must load data before you can configure charts. There are three ways to load data:

1. Upload a data file

2. Connect to a database table

3. Connect to sample data

The data drawer is where you set up your data. To open the data drawer, click the bar at the bottom of the editing panel. Click the bar again to close the data drawer.

Upload a data file

To upload the report's first data file, open the data drawer and drag a flat file (CSV, XLS, or XLSX) containing your data onto the data upload box or click Upload CSV or Excel and select the file to be uploaded. The file will be loaded to a BigQuery table and connected to the report.

To load additional data files, first click the + and then drag-and-drop or select your CSV or Excel file.

Connect to a database table or view

If your report is connected to a database, you can select the schema and table (or view) to use as the data source. To set up a database connection, . The following databases are supported:

For databases that are not maintained on a cloud platform, we support the latest two release versions. Earlier versions may work with Juicebox, but are not supported.

Connect to sample data

Juicebox also provides a selection of sample data tables if you want to start exploring before you have your own data. To load sample data, open the data drawer, select the Sample Data button, and choose one of the available datasets.

Choose a sample data table and select Add Table.

The sample data includes the following tables.

Header

In the ingredient editor header, you can set the icon and label, view the source data table, and access perform various actions from the gear menu.

Icon. This is a FontAwesome icon associated with the dimension ingredient. By default, text dimensions have check-square, time dimensions have calendar, place dimensions have map-marker-alt , and number dimensions and measures have hashtag . The default icon can be changed, or the icon can be removed.

Label. This is the ingredient label. It is the same as the Plural label.

Data table. This displays the name of the source data table.

Gear menu. Provides access to the following actions:

• Duplicate column. Creates a new dimension ingredient with the same definition. This is used to .

• Duplicate as Advanced. Creates a new dimension ingredient with the same definition expressed in yaml. This is used in cases where the UI does not yet support a particular configuration option. In most cases, you should not need to duplicate as Advanced.

• Copy ingredient ID. Copies the underlying ingredient ID for use in complex ingredient field formulas.

Basics

The Basics section of the ingredient editor contains the options that are required or used most frequently.

Field formula. This is where the ingredient logic is defined. It could be the name of a single column or it could involve .

Plural label. This is the label that will be used when the user selects multiple dimension values or no dimension values in the report.

Singular label. This is the label that will be used when the user selects a single dimension value in the report.

Number format. Only for dimensions with a number data type. Select how values should be formatted from the dropdown, or enter a custom .

Time format. Only for date or time dimensions. Select how values should be formatted from the dropdown, or enter in a custom .

Latitude. Only for place dimensions. Enter the column associated with latitude value.

Longitude. Only for place dimensions. Enter the column associated with the longitude value.

Geometry Field. Only for place dimensions. Enter the column associated with the geojson geometry field.

Styling

Description

Color

Color when negative

Image url

Hide count. By default, filter pills will display the count of distinct dimension values. Enable this option if you want to hide the count.

Advanced

Buckets

A bucketed dimension groups field values into buckets based on in the Buckets box, like so:

For example, let's say your data includes a score field with customer scores, and you want to use the scores to group customers into different roles: Detractor, Passive, and Promoter. Here's what you would enter in the Buckets box:

Conditions are evaluated in the order they are defined, which makes defining buckets for continuous values convenient:

The Buckets default label is the label to display if a value does not meet any of the conditions.

Lookups

If the values in a field are not what you want displayed in your report, you can create lookups to change them by entering a list of values to lookup with their associated value to display in the Lookups box, like so:

For example, let's say the Country field has "United States" values that you want to display as "USA", and it has null values that you want to display as "Unknown". Here's what you would enter in the Lookups box:

If there is a value in the field that is not added to the list of values to lookup, then the original value in your data will be displayed.

Id Field. Specify a custom unique identifier for columns. Especially useful for selections and filtering in unique cases. For example, you could set the field definition to string(" ") to hide the values and the Id Field to last_name .

Order By

Filter

Reverse. By default, higher numbers are deemed "better." To flip this, turn on Reverse.

If you're logged in as an editor (or a user with editing rights), you're able to create and edit reports.

Add a new report

To add a new report, select + Create New from the home page.

After selecting + Create New, you'll be asked to select the starting point for building your report. You can start with a pre-designed report from the Examples or select Start with a blank report to build an report from scratch:

• Examples. Selections in the Examples category are finished reports, with data loaded and charts configured using that data. Examples are great to add to your workspace and use as reference or inspiration.

• Start with a blank report. Select Start Blank if you want to start with a blank slate.

After selecting your starting point, the report creation wizard will walk you through creating your report. You'll provide a title, description, color theme, and font, and then select Create Report to create your report. (Alternatively, you can select Skip Setup to create your report with default settings.)

Once your report is created, you'll be taken to the draft version of the report. You're now ready to edit the report to and .

Edit a report

You make changes to a draft version of the report (the draft report) using an in-browser interface called the editing panel. Only can access the editing panel.

Accessing the editing panel

To access the editing panel from the home page, select Edit on the report.

To access the editing panel from a published report, select Cmd+E (Mac) or Ctrl+E (Windows).

Overview of a draft report

Changes to a report are made to a draft version of the report. If you see the editing panel, you know you are in the draft report. The editing panel is located on the left side of the draft report. Changes made and saved in the editing panel are immediately reflected in the draft report.

You your report using the editing panel. You add to your report from the data drawer. You your report (or report changes) by clicking the Sharing button.

Duplicate a report

To duplicate a report, click the Duplicate Report button at the top of the editing panel. (Alternatively, you can click the Duplicate Report button from report Settings menu or from the home page.) Next, give your new report a title and select Duplicate. Once the new report is created it will open as a draft version, ready for you to edit and share.

Delete a report

To delete a report, open Settings & Themes and click the Delete Report button. (Alternatively, you can click the Delete Report button from the report Settings menu or from the home page.) Then confirm that you want to delete the report.

The first step in sharing a report is publishing the report.

Publishing for the first time

To publish for the first time, click the Sharing button in the report header. It will say "Start Sharing".

Next, decide how you want to control access to the report:

• Sign in required. Report can only be viewed by those that have signed in with a Juicebox account that has access to the report. Viewer access to the report can be by workspace owners or admins.

• Link with a password. Report can be viewed by anyone with the report link and password. Because sign in is not required, report access cannot be managed.

• Anyone with the link. Report can be viewed by anyone with the report link. Because sign in is not required, report access cannot be managed.

After publishing, you are ready to .

Publishing changes to a report

Until you publish them, any changes you make to a report are only visible to editors while in the draft report. That is, viewers with access to the report won't see your changes until you publish them. With Juicebox, you can publish, refine your report, publish the new changes, refine some more, publish the new changes, and so on. You can continually improve and experiment without affecting what viewers see until you're ready.

To publish changes, click the Sharing button in the report header. It will say "Sharing". Then click Save & Publish.

The version of the report that editors work on is called the draft report. All changes are saved to the draft report until they are published, you do not have to keep track of whether you are working in the draft report. Here are indicators that you are in the draft version:

• You see "draft" in the report url

• You see the editing panel

• You see the Sharing button

Discarding changes to a report

At some point you may want to discard all the unpublished changes in the draft report and go back to the previously published version of the report. To do this, click the Sharing button and select Discard.

Data permissions objects create filters that are applied to every database query. If the database table does not contain the column or ingredient referenced, the data permission will be ignored.

Data permission objects reference ingredients which are named expressions that can use more than one database column. Data permission objects will soon be able to reference raw table columns by surrounding the column name with square bracket.

• ingredient: [list of values] Show only rows where the ingredient expression evaluates to one of the list of values.

For all the following examples an [column] can be used in any place where an ingredientis used.

• ingredient__notin: [list of values] Show only rows where the ingredient expression does not contain a value in the list of values.

• ingredient__eq: value Show only rows where the ingredient expression is equal to a value.

• ingredient__ne: value Show only rows where the ingredient expression is not equal to a value.

Examples of data permissions

This user can only see rows where the state ingredient is in the list of four states AND the age ingredient is greater than 30.

This user can see rows where the database table contains a column named “Student Name” which is equal to “Maria Hill” and the column named “Organization” is equal to 101.

Making data permissions affect all apps

Making data permissions that affect individual apps

Juicebox apps can be embedded in any website you control.

Overview of Embedding

Delivering a Juicebox story requires:

1. A Juicebox application.

2. Juicebox users that may have .

3. A website where your story will be displayed.

Embedding gives you control of items 2) and 3). For these examples, we’ll call you HealthyCo 🧃. You sell organic juices and have developed several reports for internal and external use to show how your juices are performing.

What is embedding?

Embedding allows Juicebox stories to be delivered in any webpage by generating a one-time use url that represents a user viewing a report.

This url can be displayed in an iFrame on HealthyCo’s website.

When should I use embedding?

There are several ways to use Juicebox.

How embedding works

Use the Juicebox API to perform user setup and request an embeddable url to show a user an app. That embeddable url can be used as an iFrame src to display the Juicebox in your website. .

You can sign in to your workspace by going directly to your workspace URL or by going to myjuicebox.io and clicking the Sign back in button.

Signing in using your workspace URL

After entering your workspace URL into the browser, you'll be asked to sign in to your workspace. You can sign in by email or by using a Google or LinkedIn account.

Signing in using

You can sign in to your workspace by going to . From there, click the Sign back in button.

Next, sign in using your email address or using your Google or LinkedIn account. If there is more than one workspace associated with your email address, you'll be asked to select a workspace. Otherwise, you'll be taken directly to your workspace.

Signing in from an access link or invitation email

You may be invited to join a workspace through an access link or through an invitation email. After clicking the access link or Open Report button in the invitation email, you'll be asked to sign in.

From there, you can sign in with a Google account, LinkedIn account, or email address. If you do not already have an account, you'll be asked to sign up for one.

Here are some resources that we use at Juice and recommend.

Colors and images

Here are some tools we like for finding the right colors and images for your report:

• Eye Dropper: a Google Chrome extension that lets you find the hex code for any color on most websites.

• : a color scheme generator that helps you find colors that work well together.

• : a source for freely-usable images, with photographer attribution.

Fake data generator

Sometimes you want to play around with design before gathering real data. To do that, you'll need some fake data. can help generate good quality fake data quickly. We've also had success asking GenAI tools like to create fake data.

Data preparation

Cleaning and restructuring data is a lot easier with a tool like .

Setting Data Permissions for an Access View

See Limiting what data users can see.

How to set selections on an Access View

You can preselect items for your users on the Access View. A selections object contains keys that are a colon delimited pair of the Slice Slug and the Ingredient Id of the Ingredient used in the slice.

You can find the Slice Slug in the editor.

The Ingredient Id can be found by selecting the Ingredient grouping used in the slice, then selecting "Copy Ingredient Id" in the ingredient editor.

Making selections in a chooser

Choosers can just include the chooser slice name.

For choosers, you need to get the Ingredient Id for the Ingredient you want to select

To select the third "Count of Date and Time" ingredient in the chooser above, you'd use this selections object.

Making selections in the Access View URL.

You can also make selections using the url. To do so, pass the data like this:

Here's an example of a complex selection that selects one choice and two items on a leaderboard. All of this would appear on a single line, but we're splitting it to make it easier to read. Note that spaces need to be by replacing them with a "+" sign or "%20".

The result looks like this:

Handling Pagination

The maximum pagination size is limited by object. Apps are limited to page sizes of 100, other objects will return 10000 objects. If the number of available objects exceeds the limit, the list will be paginated. Response headers will contain the following values.

• X-Count The total number of objects available.

• X-PageThe current page number

• X-PageSize The number of objects on each page.

• X-Next A link to fetch the next page of data. This will be "None" when on the last page of data.

• X-Previous A link to fetch the previous page of data. This will be "None" when on the first page of data.

Slice text can change dynamically based on what a user has selected in slices above.

For example, suppose you have a slice followed by a slice, and the measure used in the trend slice is the measure selected in the upstream chooser slice. Your trend slice title says "Here's the trend for the measure selected above":

You want to replace the phrase "the measure selected above" with the label of the measure selected above. For example, If the user selects IMDb Rating

Data doesn't speak for itself.

While "the data speaks for itself" is a nice idealistic phrase, in practice people often don't see or hear anything from the data because it is simply presented poorly. While you don't want to present a message the data isn't saying, you do want to ensure valuable insights are both attractive and effective.

Visual design is about guiding attention. Let's look at some simple tips to guide attention through your data presentation.

Color

• Choose a data color that resonates with your story topic or company brand. Bolder, vibrant colors tend to be better for this.

• Use section color backgrounds to define a visual flow for your story. For example, you may want a bold colored introductory section to grab interest, and then use lighter color section backgrounds in the rest of your story that will be less distracting for reading data from charts.

• Be sure your text has good contrast for readability. If a dark background color is chosen on a section or slice, Juicebox will automatically make your text white.

Typography & Styles

• There are several font themes to choose from. Choose a set that conveys the mood of your story best. Is the story more opinionated or explanatory? Choose the "Literary" style. Is the story more a statistically accurate report update? You may want to choose "Professional", or "Bold" if you want to make a stronger point.

• Use large text headers in Slice text to create titles for your sections.

• Use small text for notes about data or guidance tips you would like to communicate to your viewers.

Column and Measure Labels & Icons

• Any data you add to Juicebox will be represented by a . Taking the extra thought to label this well and provide complimentary icons will make the editing experience better for you as an editor. However more importantly, this will result in a more unique and understandable story for your audience.

• Keep your labels as short as possible while maintaining clarity. For example, instead of "Sales Dollars", you may just want to write "Sales" since you can use a dollar sign for your icon and format your numbers with the dollar format.

• Icons allow you to add uniqueness or personality appropriate to your story style and data. Don't be afraid to have some fun with your icons! Search for good icons via text search or categories dropdown.

Slices & Layouts

• Unlike other dashboard reporting tools, Juicebox is more about helping you present your data like a story that has a beginning, middle, and end. This is why slices lay out vertically, by default, like a cross between a website and a slideshow presentation. You wouldn't start a presentation to your team by showing thumbnails of all your slides at once. Why would a data presentation be any different?

• Put text next to your chart with a slice "Chart on right" or "Chart on left" This is great for adding more explanatory text that can easily be read while viewing a chart.

• You also may put entire slices next to each other by changing the section layout to "Side-by-side layout". For this option, sometimes slices will scroll horizontally, so this is a good option when there are charts or text you would consider optional viewing.

Branding

• Often you may have a logo or branding colors you would like to style a data story with. You may want to set the as your logo color. And then use lighter secondary brand colors in section or slice backgrounds.

• Have a logo? to a slice for instant brand appeal. Voila!

Photos

• You can to a slice, either your own or images from . Photos are a great opportunity to add visual interest to your story. Similar to a blog post with a great intro image, data stories are no different.

The editing panel appears on the left of the draft report and is where you design the report.

These are the editing panel components:

• Header buttons

• Settings & Themes

Header buttons

At the top of the editing panel are two buttons: Add Editor and Duplicate Report.

The Add Editor button allows you to to the workspace.

The Duplicate Report button creates a duplicate version of the report.

Settings & Themes

The Settings & Themes section is where you modify the basic settings for your report (title, description, icon) and the color and font themes. Here you also can delete a report and turn off the default behavior that automatically loads design changes to the draft report. Just expand the Settings & Themes section and make changes as needed.

Delete Report. Click this button to delete the report.

Icon. The icon appears on the home page and report header. Each report starts with a basic icon.

Title. The title appears on the home page and report header. Aim to keep this short, ideally 1-3 words.

Description. The description appears on the home page and report header. Here's where you add a bit more detail about your report. Aim to keep it at a sentence or a few phrases in length.

Color theme. Choose the color theme to use for your report. You can select from pre-designed color themes or customize your own. The color in the circle will be the color used in charts. The three additional colors will be used automatically as the header and section backgrounds and will be available for selection as the background color for the header, sections, and slices.

You can switch color themes at any time. If theme colors are used as backgrounds, these will be switched to the new theme colors. (If a non-theme color is used as a background, this color will not change when the theme changes.)

Font theme. Choose a font theme for your report. You can switch font themes at any time.

Editor controls. By default, changes made to the report design in the editing panel will be automatically loaded to the draft report. You can turn off that behavior by toggling off Editor controls. If Editor controls is turned off, you will have to click Reload Changes in the draft app before the changes will be loaded.

Header Style

The Header Style section is where you create and style a basic header for your report. To do this, expand the Header Style section, select a header style, and adjust the header background as needed.

Click the paint drop icon in the upper right of the Header Style section to adjust the header background color or image.

• Customize. The Customize button will allow you to define or modify a custom color theme. Any other section or slice using the original theme colors will change to the new colors.

• Custom. The Custom button lets you add a color outside of the color theme. Using the custom color will not affect any section or slice using a theme color.

Sections

Sections are groups of slices within a report. Sections allow you to control layouts and backgrounds. To add a section, click on the plus-sign button that appears when you hover above, below, or between existing sections and select the type of chart to add to the new section. (If you're not sure which chart type, pick any of them. You can always delete it later.)

Rename the section. The new section will have a name. Click on the name to edit it.

Hide the section. When you hover on the section name, you'll see a toggle. If toggled off, the section will not display in the report.

Delete the section. To delete a section, click on the gear icon and select Delete Section.

Adjust the section layout. By default slices within a section will be stacked, one on top of the next, with no space in between. This default layout can be adjusted by clicking the Section Style dropdown.

There are commonly used layouts available in the Layout dropdown, as well as the option to define a Custom layout. Custom layouts allow you to place slices exactly where you want.

Adjust the section background. You can adjust the section background color and/or image by clicking the paint drop icon and making changes as needed.

• Customize. The Customize button will allow you to define or modify a custom color theme. Any other section or slice using the original theme colors will change to the new colors.

• Custom. The Custom button lets you add a color outside of the color theme. Using the custom color will not affect any section or slice using a theme color.

If you choose a dark background, Juicebox will invert the visualization and text colors automatically.

Collapse and reorder sections. To move a section up or down, hover over the section header and drag and drop the section where you want it to display. Because sections can get quite long, reordering will be easier if you collapse your sections first. To collapse a section, simply click the section header. To expand a collapsed section, click section header again.

Listening to other sections. [Coming soon.]

Slices

Slices are the basic building blocks of your report. There's a lot to say about them on the next page.

After you publish your report, it's time to invite others to view it! How this happens depends on how you are controlling access to the report.

Sharing a report with "Anyone with the link" access

To share a report with "Anyone with the link" access, copy the report link and share it with others as you would any other website link. Anyone who clicks on the link will see the published version of your report.

Slices are the basic building blocks of your story. Slices are added to . Each slice can have text either by itself or with media (image or video) or a .

Adding, duplicating, and deleting slices

To add a slice to an empty section, click on the section header and select the slice type from the list. To add a slice to a section that has one or more slices, click the + button where you want the new slice to appear and select the slice type from the dropdown.

Rather than adding a brand new slice, it may be easier to duplicate and modify an existing slice. To duplicate a slice, select the gear icon and then select

Data preparation is tedious and time-consuming. We get it. But unless the data is properly prepared, your report design process is likely to be frustrating and unsuccessful. Time spent preparing your data will be worth it.

What does properly prepared data look like?

• Organized. Data values are organized in columns and rows in a single table. No merged cells, and no titles or notes that span multiple columns.

A chooser chart can be used to:

• Show a summary of measures

• Let a user choose which measure to use in downstream charts

• Let a user choose which column to use in downstream charts

Users must be logged in to the workspace with a Juicebox user account. User permissions (i.e., what users can do once logged in) depends on the user role. There are four user roles: viewer, editor, admin, and owner.

User Roles

Here's an overview of what each role can do.

You can request the current filtered state of a Juicebox table. This can return either a downloadable file for your user or a json object that can be used to for other automations.

Juicebox uses the javacsript api to safely allow cross origin communication between window objects. Juicebox listens for postMessage events. Juicebox filters postMessage messages to an allowed origin page (currently all Juicebox servers). Your Juicebox representative can ensure your site or test site is whitelisted.

The messages can call is-report-ready, export-data, or download-data.

To embed Juicebox apps in your own website, follow these steps.

1. Request a JWT token as a client admin user. This token can be reused.

2. Request details about what Juicebox apps are available. This will provide you an app id for the app you want to embed.

3. Create a Juicebox user with the appropriate

Start with your audience

Before you start creating your Juicebox data story, you’ll want to make sure you have a good understanding of your audience’s needs. Everyone who will be using your data story or report has a role in the organization and associated responsibilities. The more your data story or report can help them fulfill those responsibilities, the more value it will have. To do that, make sure you understand your ideal user. Consider these questions:

• Who is your ideal user?