Custom Layouts for KPI Dashboards

KPI Dashboard layouts capabilities described in this article are experimental and should be treated as preview of the upcoming functionality.

By default, a single row in a KPI dashboard can have multiple KPIs or one insight. KPI dashboards now have a flexible layout where you can add also multiple insights in a single row by updating the JSON structure of the dashboard metadata object.

Contents:

Overview

The custom layouts use a 12-column grid. You can assign widgets (that is insights and KPIs) any number of columns between 1 and 12.

The height of all widgets in a row is aligned to the highest widget in the row. The height is 300px for KPIs and Headline reports, and 450px for other insight types.

If you assign width of less than three columns to insights, they may be difficult to read.

Custom layouts of KPI dashboards are responsive and fluid. To prevent the dashboard from being difficult to read on small screens, KPI dashboards use a pre-defined set of breakpoints that adjust the layout on display accordingly.

For example, if the size of the screen reaches a breakpoint, the widgets from a row rearrange to two rows.

Create a custom layout for dashboards

  1. Create a KPI dashboard and add KPIs and insights to the dashboard.
    For details, see Set up a KPI Dashboard.
  2. Open the list of KPI dashboards at: https://<domain_url> /gdc/md/{project_id}/query/analyticaldashboard
    For details about accessing your project ID, see Find the Project ID.
  3. Click the KPI dashboard for which you want to create the custom layout to display the KPI dashboard metadata (MD) object.

    If you install the GoodData Extension Tool for Chrome, you can hover your mouse over the widget URIs in the KPI dashboard MD object to display the names of the widgets. For details, see GoodData Extension Tool for Chrome.

  4. To open the dashboard MD object for editing, add ?mode=edit to the object URL:
    https://<domain_url> /gdc/md/{project_id}/obj/{object_id}?mode=edit
    The object definition in JSON opens.
  5. Edit the JSON to add your layout.
    For details, see Layout JSON structure.

    You can use any online JSON validator to verify the validity of the layout.

  6. Click Submit to save the KPI dashboard MD object.
  7. Open the KPI dashboard and verify the new layout.

Edit dashboards with custom layout

To add/remove widgets or reorder them on the KPI dashboard, you must first update the dashboard in the KPIs section and then update the MD object of this dashboard as well.

  1. On the KPI dashboard that you want to update, click Edit.

    The custom layout is not displayed in the KPI dashboard Edit mode.

  2. Edit the dashboard and click Save & Publish.
    The KPI dashboard is not updated and an informative message appears.
  3. Open the KPI dashboard MD object in gray pages and update the layout section.
    For details, see the Create a custom layout for dashboards and Layout JSON structure sections.
  4. Submit the changes.

Layout JSON structure

The JSON structure for the layout definition is an optional part of the KPI dashboard MD object.
It consists of the definition of rows and columns with URLs to the widgets.

"widgets": [...widgets uris], 
"layout":{  
            "fluidLayout":{  
               "rows":[  
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"<widget_uri>"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{ 
                                 "width": <width number (1-12)>
                              }
                           }
                        }, ...columns definitions]
                    }, ...rows definitions]
                  }
               ]
            }
         }
  • Each layout must be under the layout property in the KPI dashboard MD object. It has the fluidLayout root key that has a mandatory field rows .

    {
      ...
         "layout":{  
                "fluidLayout":{
                   "rows":[ …] 
                }
         }
      ...
    }
  • The rows property is an array of rows that represent the physical rows in the layout. Each row contains columns .

    {  
     ...
          "fluidLayout":{  
             "rows":[  
                {  
                   "columns":[ … ]
                },
                {  
                   "Columns":[ … ]
                }
             ]
          }
     ...
    }
  • The columns property is an array of columns objects. Each column has mandatory fields content and size , and represents one item (widget) in the layout.

    {  
     ...
         "columns":[  
            {  
               "content":{  
                  ...
               },
               "size":{  
                  ...
               }
            }
         ]
     ...
    }
  • The content property defines the content of the column in a row. Content has a mandatory field widget .

    { 
     "content":{ 
        "widget":{ 
           "qualifier":{ 
              "uri":"<widget_url>"
           }
        }
     },
     "size":{ 
        "xl":{ 
           "width": <number>
        }
     }
    }
  • The widget property is an object wrapper for the widget uri. The uri must be the same as the uri in the widget array of the KPI dashboard MD object.

    If you install the GoodData Extension Tool for Chrome, you can hover your mouse over the widget URIs in the KPI dashboard MD object to display the names of the widgets. For details, see GoodData Extension Tool for Chrome.

    {  
       "qualifier":{  
          "uri":"<widget_url>"
       }
    }
  • The size property is the defined size of the content. It has a mandatory property xl that defines the size of the object on XL screens.

  • The xl object defines the width of the widget in the layout row. It has a mandatory filed width that is a number from 1 to 12.
    For details, see Overview.

    {  
       "xl":{
          "width": <number>
       }
    }

Example 1

The following example contains one row with two visualizations each with a width of 6 columns, and one row with one KPI with width 2 and a visualization with width 10.

Dashboard view

KPI dashboard MD object JSON

{  
   "analyticalDashboard":{  
      "content":{  
         "filterContext":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75818",
         "layout":{  
            "fluidLayout":{  
               "rows":[  
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75819"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 6
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75821"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 6
                              }
                           }
                        }
                     ]
                  },
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75820"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 2
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75822"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 10
                              }
                           }
                        }
                     ]
                  }
               ]
            }
         },
         "widgets":[  
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75819",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75821",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75820",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75822"
         ]
      }
   }
}

Example 2

The following example contains 3 rows. The first row has four KPIs, each with width 3. The second row contains one visualization with width 4 and one visualization with width 8. The third row contains a single visualization with width 12.

KPI dashboard view

KPI dashboard MD object JSON

{  
   "analyticalDashboard":{  
      "content":{  
         "filterContext":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75828",
         "layout":{  
            "fluidLayout":{  
               "rows":[  
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75824"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 3
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75825"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 3
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75827"
                                 }
                              }
                           },
                           
                           "size":{  
                              "xl":{  
                                 "width":3
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75826"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 3
                              }
                           }
                        }
                     ]
                  },
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75829"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 4
                              }
                           }
                        },
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75832"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 8
                              }
                           }
                        }
                     ]
                  },
                  {  
                     "columns":[  
                        {  
                           "content":{  
                              "widget":{  
                                 "qualifier":{  
                                    "uri":"/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75830"
                                 }
                              }
                           },
                           "size":{  
                              "xl":{  
                                 "width": 12
                              }
                           }
                        }
                     ]
                  }
               ]
            }
         },
         "widgets":[  
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75824",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75825",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75827",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75826",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75829",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75832",
            "/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/75830"
         ]
      }
   }
}