Creating Dashboard Widgets

Brightspot comes with a set of standard dashboard widgets that you can assemble into custom dashboards as described in Shared Dashboards. In addition, you can create your own widgets and add those to custom dashboards.

Step 1: Create a Customized Dashboard Widget

You create a custom dashboard widget by extending the class DashboardWidget and overwriting the method writeHtml. The following example creates a dashboard widget that shows the current time in various time zones.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
package widgets;

import com.psddev.cms.tool.Dashboard;
import com.psddev.cms.tool.DashboardWidget;
import com.psddev.cms.tool.ToolPageContext;

import java.io.IOException;

import java.util.*;

public class CurrentTimesWidget extends DashboardWidget {

    @Override
    public void writeHtml(ToolPageContext page, Dashboard dashboard) throws IOException {
        Map<String, String> timeZoneIdentifiers = new HashMap<>();
        timeZoneIdentifiers.put("New York", "America/New_York");
        timeZoneIdentifiers.put("Los Angeles", "America/Los_Angeles");
        timeZoneIdentifiers.put("Mexico City", "America/Mexico_City");

        page.writeStart("div", "class", "widget");

            page.writeStart("h1");
                page.writeHtml("Current Times");
            page.writeEnd(); /* h1 */

            page.writeStart("table");

                page.writeStart("tr");
                    page.writeStart("th");
                        page.writeHtml("City");
                    page.writeEnd(); /* th */
                    page.writeStart("th");
                        page.writeHtml("Time");
                    page.writeEnd(); /* th */
                page.writeEnd(); /* tr */

                for (String myTimeZone : timeZoneIdentifiers.keySet()) {
                    page.writeStart("tr");
                        page.writeStart("td");
                           page.writeHtml(myTimeZone);
                        page.writeEnd(); /* td */
                        page.writeStart("td");
                            String localTime = displayTime(timeZoneIdentifiers.get(myTimeZone));
                            page.writeHtml(localTime);
                        page.writeEnd(); /* td */
                    page.writeEnd(); /* tr */
                }

            page.writeEnd(); /* table */
        page.writeEnd(); /* div */
    }

    private String displayTime(String timeZoneIdentifier) {
        Calendar localTime = new GregorianCalendar(TimeZone.getTimeZone(timeZoneIdentifier));
        localTime.setTimeInMillis(localTime.getTimeInMillis());
        int hour = localTime.get(Calendar.HOUR_OF_DAY);
        int minute = localTime.get(Calendar.MINUTE);
        return (hour + ":" + minute);
    }

}

In the previous snippet—

  • Line 11 declares the class CurrentTimesWidget. Objects instantiated from this class appear as Current Times Widget in the Dashboard.
  • Lines 15–18 instantiate a HashMap of time zones.
  • Lines 22–24 write the widget’s header Current Times.
  • Lines 28–35 write a table header in the widget’s body.
  • Lines 37–47 loop through each time-zone record. For each record, call the method displayTime to retrieve and then print the time zone’s current time.

Step 2: Add Customized Widget to a Dashboard

You can add the customized widget to one-off or shared dashboards. For an explanation of adding widgets to a shared dashboard, see Creating a Shared Dashboard; adding widgets to one-off dashboards is similar.

../../../_images/custom-dashboard-widget.svg

Step 3: Display Customized Widget in Dashboard

Brightspot displays the customized widget when displaying the dashboard that includes it.

../../../_images/custom-dashboard-widget-displayed.png