Frontend Structure

Owned by Ethan Freestone
Last updated: Mar 30, 2021
3 min read

Dashboard structure

When a user opens the Dashboard app for the first time, they will first briefly see a loading screen as the user is resolved and the DEFAULT dashboard is created.

  • Here DEFAULT is the name given to the initial dashboard given to all users.
  • In the background the DashboardRoute first fetches all the dashboards for a user.
    • If the DEFAULT dashboard needs to be created then that will happen

  • The dashboard app has url path: /dashboard, and the user can either go directly to that url, or specify a named dashboard with /dashboard/<dashboard name>.

    • Should a dashboard with this name not exist for the user then they will see a 404 screen

      Currently neither the ability to select from multiple dashboards, nor to rename/create new dashboards is supported. The use of named dashboard offers a mechanism for this functionality to be added in the future if desired.

      Please note that although DEFAULT was chosen as the name for the initial dashboard, there is no convention necessary to enforce capitalised dashboard names.

  • The DashboardRoute will then attempt to fetch the dashboard specified in the url path. (If no dashboard is specified the user will be automatically redirected to /dashboard/DEFAULT).

Once the dashboard is fetched, the user will see their list of widgets, and have the options to create a new Widget, and to reorder the dashboard. The list of widgets will display in order from left to right, then top to bottom, with some css to keep the number of columns relevant to the width of the user's screen. For a small screen this will be a single column, up to 4 columns for a screen wider than 1920 pixels (1080p display). The order can be tweaked through an edit order screen, with a drag and drop list of widgets.

  • This is locale specific, with Arabic set to the default language the dashboard will instead run from right-left, top-bottom.
  • In addition, this has the potential to change and work more like a drag and drop dashboard on a grid at some point in the future, but we are not aiming for that in our initial release.


Widget component structure

A generic widget is constructed like the following, where every Widget is simply a WidgetHeader, containing the widget title and an actions menu, and some child component, which is determined by the fetched WidgetInstance's WidgetDefinition. That child component is then what determines how the fetched data is to be parsed and displayed.

Any information coming from the fetch is to be displayed inside the children block ONLY.

So the component heirarchy is as follows:

  • Widget
    • WidgetHeader
      • Actions Button
    • WidgetType-Specific Component
      • Display
      • WidgetFooter

We'll demonstrate this with a diagram of SimpleSearch.

The above heirarchy for SimpleSearch specifically becomes:

  • Widget
    • WidgetHeader
      • Actions button
    • SimpleSearch
      • Count badge
      • SimpleTable
      • WidgetFooter

You can see that the large majority of the widget is taken up with a table. This table displays a configured number of rows of fetched data, with configured columns. This component also contains a badge to show the total number of entries that the fetch returned, and a WidgetFooter.

WidgetFooter is a standard component offered by ui-dashboard, so there can be consistency between Instances of differing WidgetTypes. However not all types will require a footer (see style guidelines), and also the footer will contain a timestamp of the fetch, so it belongs in the type-specific component, in this case SimpleSearch.