Widget Guidance

All EPA widgets are centrally provided through Developer Central. OMS and OWC works with EPA program widget content owners to create, publish, and maintain their widgets.

Widget Diagram
The structure of the widget template.

On this page:

What is a Widget?

A widget  is a piece of web code which can be embedded into other web pages as an iframe. The code will appear on the other web page, but you manage and maintain the content of your widget. It permits you to provide useful information without having to update every single page where the widget appears.

Why Use Widgets?

Widgets can reach a broader audience than EPA's website because your code can be embedded on sites other than www.epa.gov.

This piece of code can be used to provide information in many ways, for example:

  • Access to geographic data, as in the case of the Envirofacts city search widget
  • Outputting RSS feed news items
  • And many other ways to provide small chunks of information for others to embed on their web pages

See other examples of EPA Widgets.

Things to consider before creating a widget

  • The users of a widget aren't necessarily the same people who would add it to a web page. For example, a library might add an EPA search widget to its site, but it's actually library patrons who will use it.
  • The widget should offer useful information that changes (for example a daily tip) or a function (such as a ZIP code lookup).
    • Don't create a widget with only a fixed image or static content… this is merely a text box and a does not need to be delivered through a widget process.
    • Don't create a widget about your office or organization.
  • Even though widgets are on the web, they do not stand alone. A widget usually cannot be taken down without disrupting users who have added it to their web page.
  • To be sure widgets are worth continuing, plan ahead how you will monitor widget usage and keep track of changes over time.

Approval

All widget concepts should be reviewed and approved by OMS and OWC before you begin developing the widget. Work with your internal product development process as needed.

Get approval from:

  1. Your manager; and
  2. Your Web Council Member (see Web Council Members and Other Key Web Contacts to find your Web Council Member); and
  3. OWC (your Web Councilor will get this information for you).
  4. OMS (will perform a code review, make widget code available and list widget in Developer Central). 

Set Up and Configuration

Read this entire document before you begin. This document describes the general process and standards for developing EPA widgets. The process approximates a generalized widget life-cycle:

Concept and Planning

Note: Remember that your official activities on-line are subject to the ethics regulations  as well as other federal and agency laws, policies and regulations. In addition, existing policies and guidance for accessibility , privacy, external site links, cookies, and writing style apply to social media tools as well. References to these are included at the end of this document.

When seeking approval from you Web Council Member, provide the answers to the following questions:

Purpose and function

  • What will the widget do?
  • What is your goal for this widget?
  • How does it support your program's mission?

Audience

  • Who do you expect to add your widget to their Web page?
  • Who do you expect to use the widget?
  • When and how you will announce availability of the widget? 
    Ask your content coordinator about using EPA's social media tools, such as a blog post about the widget, or Twitter or Facebook messages.

Development

  • How will you update the widget content or function?
  • How often will you update the widget content or function?
  • How will the widget be accessible, e.g., meeting Section 508 requirements?
  • What are any possible security issues?
  • What are any possible conflicts with existing federal or EPA policies?
  • What will the widget look like and how big will it be?

Management

  • Do you and your management understand and support a widget as a virtually forever commitment?
  • How will you measure widget use or success?
  • If the widget has a finite life cycle, how long is that?

Development and Deployment

First get approval from your management, Web Council Member, and OWC for the widget concept before you begin to develop a widget. Follow the standards listed below. If you wish to deviate from a standard, please bring the reasons why to your Web Council Member and get approval from OWC before you proceed.

In general, a widget should include the following:

  • a name — the name can simply be the content or function of the widget
  • variable content or a function for users (e.g., something the user can do)
  • if needed, minimal instructions how to use the widget
  • a prominent link to the program Web site about the content or function
  • a small "i" link to the widget's own home page
  • a small EPA logo link to the EPA home page

For those seeking to make new widgets available to the public, they must:

  1. Prior to the development of a new widget, a widget concept should be submitted for review and approval. Concept approval will include the Web Council member for the respective AA or RA, and a representative from the Office of Web Communications given that the new widget is:
    • a different kind of web content from usual,
    • intended to show up on other websites outside of epa.gov,
    • show up in statistics as their own category, and
    • are some of EPA’s most popular content
  2. Integrate all necessary Cascading Style Sheets (CSS), JavaScript (JS) and widget code into the widget.
  3. Document any stand alone image/JS files that are necessary for the widget to function properly.
  4. Ensure that the following widget development criteria are met:
  5. Test to ensure the widget works as designed.
  6. Once published, email developers@epa.gov to have the widget included in EPA’s public Widget List on Developer Central.

After the widget and any associated JS files are submitted, reviewed, and approved, Developer Central will make the widget available by adding it to the Developer Central Widget page with the appropriate iframe code to be used to display the widget on your pages.

Keep in mind:

  • Design the widget so no instructions are needed, or absolutely minimal instructions. For example: "Enter ZIP" is better than "Please enter your home or business ZIP Code here:" In most cases, no instructions should be needed.
  • Important: Provide a clear link to the EPA program page related to the widget's information or function. Use the destination page's title as the link text (e.g., Earth Day).
  • Important: Create a border around the widget body, so the widget can appear distinct even if the user's page is the identical color. Embed a line in the graphic, or use an iFrame border of 1.
  • Important: Put the rectangular EPA logo (not the round seal) in the bottom left corner of the widget. Link it to https://www.epa.gov. Keep the logo unobtrusive by making its color a little lighter or darker than the main widget background. (Avoid vivid, distracting contrasts or colors such as hot pink).
  • Important: Create a page on epa.gov about the widget itself. This is where you post the widget, any variations such as different sizes, instructions or links how to get or add the widget to a Web page, and similar related information. Create the widget's own home page using an obvious, guessable URL, for example, epa.gov/program-name/widgets
  • Important: Link to your widget page from an italic lowercase letter "i" (for "information"), at the bottom right of the widget. The "i" is about 7px wide by 10px high.
  • Different sizes of the same widget should use a similar design, but scaled appropriately. They may be of different colors.

Metrics

You can track the activity of your widgets using EPA’s Google Analytics (GA) account.

Widget pageviews are based on how often those widgets are loaded in a browser as part of a Web page.  Since widgets are inserted into many different Web pages across multiple sites, their “popularity” may lack for context.  Were visitors interested in the Web page or the widget, or both?  Some high-traffic Web pages have widgets embedded, and each time the Web page is requested, so too are those embedded widgets, regardless of the visitor’s interest in the widget.  At the very least, a high number of widget pageviews can suggest positive exposure for your widgets.

Keeping track of your widget exposure may help you determine how much the widget is being used so you can:

  • analyze the widget's usefulness over time
  • assess the effectiveness of marketing the widget
  • show your managers their investment in the widget is justified
  • know when you reach saturation (if activity levels off)
  • know when the widget stops being useful (if activity falls)

*** When analyzing your widget Web traffic, always keep in mind that spikes and dips in Web traffic may be directly related to the status of Web pages that contain your widget.

Termination

Taking a widget down will leave a hole on Web pages where it was installed. Therefore, most widgets should have an indefinite life. However, a widget could have a short lifespan for two reasons:

  • you planned for a short lifespan
  • unforeseen circumstances require to take it down

For a pre-planned short-term widget: On the widget's page, be clear that it will be live only from X date to Y date, after which it will go offline. While it is possible this might discourage casual users from adding the widget, remember, you will have a good reason for a short-term widget and your target users will understand your reasons.

For unforeseen circumstances: If you can, replace the widget content with a simple, clear announcement that the widget is offline or discontinued, giving the reason. Include a link to a page with relevant information. State that we regret the inconvenience.

Unless you intentionally planned and got approval from OWC to post a short-term widget, please do not take down a widget. If you must take it down please notify your Web Council Member, OWC, and OMS.

References

Ethics

EPA Policy

Guidance

Additional Resources

  • The Web Guide is the authoritative source for Web sites and applications at EPA.
  • The Information Collection Request Center  describes information collection requirements imposed on the public by the EPA.
  • Special Terms of Service Agreements have been negotiated with various social media sites that resolve the legal issues with the standard Terms of Service (TOS) users have to agree to when setting up an account.

Contact

Your Web Council Representative should contact the Office of Web Communications (OWC) after you've read this guidance, but before you start developing your widget. When you begin development of your widget, you should coordinate with Developer Central.

Web Guide

Contact the Web Guide
Contact the Web Guide to ask a question, provide feedback, or report a problem.
Last updated on October 4, 2024