Guidelines for Embedding Widgets
When embedding widgets on your website, there are multiple design and usability factors to consider, such as layout, CSS styling, and external linking. Use this page to review the main global factors. For guidance and recommendations for individual widgets, see widget-specific guidelines.
On this page:
Embedded Widgets Example
An example of widgets embedded on a page is shown below. This example includes a Next Best Action banner, a Bill Comparison, and a Home Energy Analysis breakdown. Together these widgets provide a consolidated view of billing details for a customer.
Showing or Hiding Widgets for Different Customers
Not all widgets are applicable to all customers. For example, some widgets are available for residential customers but not non-residential customers. Other widgets can only show data for electricity use and so should not be displayed for gas-only customers. You may therefore want to create a list for yourself that identifies which widgets to show under different conditions. See Determining a Widget's Applicability for details.
Layouts and Minimum Widths
When considering the placement of widgets on your website, it is important to note that Oracle Utilities Opower products only support certain layouts. Widgets respond to the size of the container that includes an embedded widget, and each widget requires a minimum amount of width in each screen layout design. Breakpoint ranges determine when the widget designs transition to a different layout design. All embeddable widgets use the following default breakpoint ranges, described in pixels (px), and have the following minimum width requirements:
| Breakpoint Range | Minimum Width |
|---|---|
| 640px and lower | 320px |
| 641px - 1024px | 600px |
| 1025px and higher | 600px |
Authentication
Most widgets should be embedded on pages that are accessible only after the customer logs in to their utility account. Embedding widgets on a webpage that is accessible to pre-authenticated customers requires a redirect to fully authenticate customers before they can view the widget content.
Exceptions to this rule include widgets such as the optional pre-authenticated workflow for Home Energy Analysis and the Confirmation Message. See the descriptions for these widgets for more details.
Note: You can embed more than one widget on a single webpage. See Improving Widget Load Performance and Improving User Experience Scenarios with Custom Events for tips on how to support this embedding strategy.
Styling Widgets
Styles from the webpage can affect the widgets that are embedded on it. Oracle Utilities uses the utility branding guidelines to configure styles such as colors which include the primary color, efficient neighbors color, and the you color. Utilities provide colors as part of the utility branding guidelines in the Oracle Utilities Opower Platform Configuration Guide.
Be aware of the following styling considerations related to embeddable widgets:
Use Namespaces for Properties: Use namespaces for properties to avoid overriding to widget styles. For example, it is recommended to use properties in the style of .text-block {text-align:center} rather than the more generic td {align-center}.
Avoid !important Values: Any styles defined as !important can override widget styles and could result in poor user experience.
CSS Isolation
Widgets use web components rather than iframes, which means that the widgets are exposed to the Cascading Style Sheets (CSS) properties applied to the webpages that host the widgets. The shadow DOM capability is employed to prevent CSS conflicts between widgets and their respective webpages. This method isolates the widgets from the webpage CSS when viewed in browsers that support shadow DOM.
For browsers that do not support shadow DOM, widgets employ pseudo-shadow DOM logic which interprets the webpage's CSS and attempts to ignore it for the widget. This method can still encounter CSS conflicts if the top level CSS shares a class name with the widget CSS, and the top level CSS has a specific rule related to that class. If CSS conflicts are encountered, contact your Delivery Team to identify the conflict and determine a resolution.
External Links to Widgets
If you plan to link to embedded widgets from external resources such as emails communications to customers, you can improve the user experience of these links by creating and linking to unique URLs for each widget experience. This technique is applicable when multiple widgets are embedded on the same webpage (URI) and are visually exclusive from other content. A common example of this is when widgets are embedded in different tabs of the same webpage.
Various techniques are available to uniquely identify specific content on a webpage, such as fragment identifiers, custom JavaScript, or single-page application routing. The utility is responsible for configuring and supporting any of these techniques to create unique links for the widget content embedded on their webpages. After the unique links are created, they can be used in customer communications and other external resources attempting to link directly to widget content.
For example, a customer email can use the unique link to link directly to a customer's Bill Forecast so that they see it immediately upon redirection, rather than linking to the top of the webpage which might not provide an immediate view of the Bill Forecast.
Widget-Specific Guidelines
Utilities can choose which Digital Self Service widgets to embed on their website. At a minimum, you should consider including the Bill Comparison, Data Browser, Home Energy Analysis, and Ways to Save widgets. Some widgets are best suited for a top-level page or dashboard in your website, while others are optimal for side-by-side displays. See individual widget descriptions for guidance and recommendations.