Adding Dynamic Images to Your Projects

This article describes how to integrate dynamic images into your dashboards. Dynamic images changes are driven by selection of new attribute values.

You can also insert images into reporting objects such as tables.

Contents:

GoodData dashboards can be easily augmented with static images to enhance the overall visual appeal and convey additional contextual information. However, these images do not change when the context changes.

For example, suppose you have added a dashboard filter to your dashboard. When the new attribute value is selected from the filter, it would be even more useful to update the dashboard image with a new version.

By default, GoodData sets the maximum length of attribute labels to be 128 characters, which may be too small when referencing images by URL. If you anticipate having longer URLs, you can expand the character limit for the attribute label in your project’s logical data model through the gray pages or API call. Otherwise, you can make the necessary modifications through the GoodData Portal, where the defaults for the attribute label are unchanged.

You must have administrator privileges to the project to which you are publishing these changes.

Prepare Source Images

Your set of source images must meet the following criteria:

  • PNG or JPG format
  • Stored in accessible repository, which can be accessed over HTTPS by end users
  • Unique names for each image

HTTPS is mandatory. Otherwise, some browsers might not to show images properly.

Prepare Data

Depending on how the images are to be used in your dashboard, your data table should be assembled in one of the following formats.

You may access other data sources for images, provided that your URL includes any required access credentials and that the image can be referenced in a fully qualified URL.

Dynamic images controlled by a filter

If you intend to insert images into your dashboard so that their selection is controlled by a dashboard filter, your data should be assembled in the following format:

Employee IDEmployee NameEmployee Image
1Person1source=web&url=https%3A%2F%2Fwww.example.org%2Fimage1.jpg
2Person2source=web&url=https%3A%2F%2Fwww.example.org%2Fimage2.png

In the above configuration, the Image Field value is a concatenation of the string source=web&url= and the URL-encoded version of the URL to the location of the image.

Images referenced in a table report

If your images are to appear in a table report, your data should be assembled in the following format:

Employee IDEmployee NameEmployee Image
1Person1

source=web&url=https%3A%2F%2Fwww.example.org%2Fimage1.jpg

2Person2

source=web&url=https%3A%2F%2Fwww.example.org%2Fimage2.png

In the above configuration, the Image Field value is a concatenation of the string source=web&url= and the URL-encoded version of the URL to the location of the image.

The previous data format that included direct URL references to the images (such as, https://www.example.org/image1.jpg) has been deprecated. Do not use it.

Prepare Metadata

Prepare the metadata for your project so that the project can display the source images you have defined.

Defining the Attribute Label

Through CloudConnect Designer, locate an attribute that uniquely identifies the content of the image. In the above data table, this attribute corresponds to the Employee ID column. Add a label, that corresponds with the Image column, to this attribute.

A label is a reference to the attribute in a different form.

CloudConnect Designer is a separately downloadable application that you install on your local desktop. It is used for building logical data models and ETL graphs for use in your GoodData projects. Before you begin, you must download and install CloudConnect Designer. For more information, see the Downloads page at https://secure.gooddata.com/downloads.html. If you are a white-labeled customer, log in to the Downloads page from your white-labeled domain: https://my.domain.com/downloads.html.

Steps:

  1. On your local desktop, launch CloudConnect Designer.
  2. In the Project Explorer tab, select the project you wish to change.
  3. In the model folder, you should find the *.LDM file or files for your project. Double-click the logical data model file you wish to edit.
  4. To the appropriate dataset, add or modify the attribute label.
    1. Double-click the dataset. The Attributes and Facts window opens.
    2. Suppose your Employees dataset looks like the following in the Attributes and Facts window:
    3. For information purposes, click the Show identifier checkbox.
      To the above dataset, you must add the label. To add a label, click the Plus icon. Select Add Label for > Employee ID.

      If you intend for the image to be clickable, add the column as a Hyperlink.

    4. For the Title of the new entry, enter Employee Image. Verify that the type has been specified as a Label.
    5. Click the Show Datatypes checkbox. In the Datatypes column, click the entry for the new label. Click the Browse… button.
    6. In the Select Datatype window, verify that the Text radio button has been selected. In the textbox, enter 255.

      The absolute limit on the length of the attribute is 255 characters.

    7. When you are finished, the dataset definition should look like the following:

      Example dataset with added label
    8. Write down the internal identifier for the attribute and each label. You will need it later.
    9. To save the dataset changes, click OK.
    10. Verify that the logical data model is associated with the proper project. In the Project Explorer tab, secondary-click the target project and select Working Project for….
    11. Before you publish, you should validate. Secondary-click in the Model Editor pane and select Validate… .
    12. If validation passes, save the *.LDM file.
    13. Click Publish model to server in the Details sidebar.

The project has been updated to add the label to the unique identifier for each image.

Update the ETL Graph

Now, you must update your ETL graph to add the values for the new attribute label. You must either:

  • Update an existing ETL graph to include a new column. You may be required to republish all the data in the ETL graph.
  • Create a new ETL graph that populates this attribute label.

For more information on creating ETL graphs in CloudConnect Designer, see Disconnecting Dataset Directly.

Update the Project Definition

In your GoodData project, you must update the project definition so that it is aware that the display form of the label is an image.

Previously, this step required that you modify the LDM via GoodData API. Now, the following process enables you to complete this update through the GoodData Portal.

Steps:

  1. Log in to the GoodData Portal.
  2. From the Projects drop-down, select the project to which you have published the logical data model.
  3. From the toolbar, select Manage. In the Data tab, click Attributes. Select the attribute to which you added the label (e.g. Employee ID).
  4. The object information is displayed for the attribute and its labels.
  5. In the Controls column under the Labels section, click the Edit link.
  6. From the Type drop-down, select Image.
  7. Your attribute definition should look like the following:
  8. Click Save.
    The project definition has been updated.

Define Reports and Dashboards

Now that the project’s logical data model and ETL graph have been updated to utilize the new attribute label, you must create the project objects to access and display these images.

In the steps below, you can see how these images can be made available in reports and dashboards.

Example - Adding Images to a Report

In this example, you can add the label to a tabular report as a column displaying the attribute values, which reference the stored images.

Steps:

  1. Log in to the GoodData Portal.
  2. From the Projects drop-down, select the project to which you have published the logical data model and ETL graph changes.
  3. In the Portal menu, select Reports.
  4. In the Reports page, open or create a new report.
  5. Click the How step.
  6. From the list of available attributes, navigate to the Employee ID and select it.
  7. In the Filter Values column, select Employee Image from the drop-down.
  8. To add the attribute label, click Done.
    The report is updated with the new column.

Example - Adding Images to a Dashboard

Adding a Dashboard Filter for the Image

At this point, you need to add a dashboard filter to filter on the values for the Employee ID attribute. When the dashboard filter is configured, selections made in the filter automatically filter all content in the dashboard tab to display only for the selected attribute, which means that filtration is also applied to the dynamic image object you specify below.

When configuring the dashboard filter, you should specify that users may select only one value in the Selection tab.

For more information on adding dashboard filters, see Dashboard Filters.

Adding the Image Set to the Dashboard

Now, you can add the image to your dashboard using the following steps.

Steps:

  1. Log in to the GoodData Portal.
  2. Select the project from the Project drop-down.
  3. From the Dashboards menu, select the dashboard to which you wish to add the image.
  4. Click the tab of the dashboard to which to add the image.
  5. Click the Edit icon.
  6. In the Edit toolbar, click Web Content.
  7. Insert the following URL:
    https://secure.gooddata.com/gdc/app/projects/%CURRENT_PROJECT_HASH%/images?displayFormIdentifier=[label_id]&attributeElementUri=%FILTER_VALUE([attribute_id])%
    
    1. [label_id] = the internal identifier for the label containing the image data.
    2. [attribute_id] = the internal identifier for the parent attribute
    3. For a specific example, see "Example - Displaying Player Image by Jersey Number" below.
  8. Click Save.
  9. Resize and reposition the image as needed.

At this point, you should be able to use the dashboard filter to select values for the Employee Name, which automatically updates the displayed image.

Example - Displaying Player Image by Jersey Number

Suppose you are building a project to track statistics for a sports team and want to filter a dashboard based on the jersey number of the individual. In addition to creating a dashboard filter based on the jersey number, you want to display a picture of the player based on the individual’s jersey number.

In this case, you should complete the all of the above steps with the following changes.

  1. Acquire an image of each player.
  2. Acquire the project identifier for the project to contain the images through the GoodData Portal. In this example, we will use the following: MyProjectHash.
  3. In the logical data model, locate the attribute that is used to identify the individual. Create a label for this attribute for jersey number. The display name of this label should be jersyno.
  4. Write down the internal identifier for the attribute and the label. For purposes of this example, we will use label.support_gooddata_test.jersyno for the label and attr.support_gooddata_test.jersyno for the attribute.
  5. Make necessary changes to the logical data model and ETL graph and publish to the project.
  6. In the GoodData Portal, create the report to contain the image and the dashboard filter to be used to filter based on the jersey number.
  7. In the dashboard that is to contain the image of the player, insert the following URL as web content:
    https://secure.gooddata.com/gdc/app/projects/MyProjectHash/images?displayFormIdentifier=label.support_gooddata_test.jersyno.imageurl&attributeElementUri=%FILTER_VALUE(attr.support_gooddata_test.jersyno)%

The above represents the basic set of configuration steps. Be sure to test the results.

Test the Results

Before you release these reports to your end users, you should review the results of each report using the image resources and perform significant sample testing to verify that the reports are being populated with the appropriate images.