Widget Best Practices
This page offers advice on how you should implement your widget and list it in the Chrome Web Store. As Awesome New Tab Page matures and we gain valuable feedback from users, these recommendations will be updated.
This wiki is a work in progress. It's currently not as deep as I'd like it to be, and I'm positive I've left things out. However, please keep these in mind and be open to new best practices as they come along. I'd appreciate any feedback you guys have.
There are a few things that essentially all widgets must do in order to work well, or even at all.
Before making a widget, ensure that it meets the definition of a widget. It's extremely frowned upon to do something Awesome New Tab Page can already, will soon be able to, should be able to do. Widgets should be high quality and extremely functional tools, nothing less.
See also: What are widgets?
The latest version of Poke, [Poke v2](Poke v2), should be used by all widgets (even if you don't want to use resizing). Poke v1 will likely eventually be deprecated and all widgets that haven't been updated will no longer be peaceable. It's also important to ensure that you use the correct values of the correct type.
All links within a widget should be created with their target set to _top. Widgets are loaded in an iframe, and for optimal and expected user experience, links should open in the top-most window. Here's an example
<a href="https://www.google.com/" target="_top">Google</a>
You may also use _parent, although _top is recommended. It's best to avoid using _blank, as this is most commonly not expected behavior. Remember, Awesome New Tab Page is a new tab page. Its purpose is to be navigated away from. If users wish to open a link in a new window, they can middle mouse click on it.
It's generally a good idea to never use javascript alerts. If you're debugging your extension, consider using the much more appropriate console.log() function instead, which will display the information unobtrusively in the console.
Learn more: Chrome Extensions Tutorial: Debugging.
Widgets should be beautiful. I understand that design can be challenging (I am the worst designer on the planet), however, users generally expect a certain level of attractiveness. Take a look at the Awesome Weather Widget which has 2 fairly simple designs that are both usually regarded as amazing.
Function is an extremely important yet unfortunately under-rated part of building widgets. Widgets should have a purpose. They should bring something new, exciting, and powerful to a user's new tab page. As yourself what can my widget do? If your answer to that question doesn't impress you, chances are it wont impress potential users very much either.
Widgets should be easy to use, customize, and interact with. If your widget is difficult or frustrating to use, chances are there's room for improvement. Constantly consider ways to both simplify and optimize user experience. A simple question you could consider (that applies for most people): Could your mom use it? If the answer is yes, either your mom is super awesome, or you have a fairly solid user experience (maybe even both!).
Speed is very important to users. Opening their new tab page is likely something they do many times a day, and the last thing they want to do on each pageload is wait for things to finish loading. Avoid web requests on load. Most things can be cached and stored in localStorage. Take a look at the (weather widget's background.html)[https://github.com/michaelhart/Awesome-Weather-Widget/blob/master/background.html] for a basic example of how to accomplish this.
When your widget loads, it should ideally load nothing but information from localStorage. If you're developing a widget with potentially time-sensitive details, consider loading cached data initially and then loading fresh data a few seconds after the page has loaded.
See also: getBackgroundPage.
Don't load iframes in your widget. Widgets should be entirely self-contained, and work even if there is no or unreliable internet connectivity. If you need to get data from another web page, do so regularly using the background.html, validate, and cache that data in localStorage.
Security is extremely important. It's a good idea to always be mindful of the security implications of creating widgets and how they may be exploited. Below are a few simple things you can do to help minimize risk.
When setting permissions for your extension, always use just enough. For example, don't use the <all_urls> permission unless you legitimately need access to all websites. A vulnerability in your extension could lead to a vulnerability in all websites your extension has access to.
See also: Google Chrome Permissions.
When loading data from the web, it's a good idea to validate that data to ensure it's what you expected it to be. For example, if you're working on a stock widget and it's loading stock information, ensure that the data you get is valid numbers. If the data isn't as expected, don't use it.
If possible, get data from the HTTPS version of websites rather than the HTTP version. This can help avoid potential Man-in-the-Middle attacks. If this is not possible, don't fret. Validation in addition with the extremely low probability of a MITM attack should keep users relatively secure.
Due to Chrome security restrictions, you can not use the getBackgroundPage page method. If you need to exchange data between your widget and background, localStorage is the solution. You may also want to look into [localStorage events](localStorage Events) if you need storage events.
Until I have time to build an integrated widget listing, widgets must be searchable from the Chrome Web Store. The Chrome Web Store has its own guidelines, but the below best practices should supplement them.
See also: Supplying images, Branding Guidelines.
Do not use the Awesome New Tab Page logo in your widgets. Do not use the Awesome New Tab Page logo as your widget's icon.
Do not use the Awesome New Tab Page logo in your extension's promotional or screenshot images, except files expressly approved here in this wiki.
If you wish to use the below images, do not modify them in any way. You, of course, do not have to use these images. These images are not a replacement for actual screenshots of your widget.
(More images to be added later.)
If your widget is packaged in an extension that only contains your widget, be sure to indicate this in the name of your extension. For example Awesome Weather Widget. You can also optionally add "[ANTP] to the end of your widget's name. For example Awesome Weather Widget [ANTP].
If your widget is packaged in an extension that is supplemented by a widget, you should not refer to it as a widget in the name or include the [ANTP] tag.
Do not use the phrase "Awesome New Tab Page" or similar in your extension's name. Do not misrepresent your relationship with the authors of this project (namely, me) or with the project itself.
To ensure your widget shows up in search results, include this message (or something similar) in the top of your extension's description. This should also decrease confusion for users who find the widgets before the find Awesome New Tab Page.
This is a widget for the Chrome extension "Awesome New Tab Page" (ANTP).
Without ANTP, this extension does nothing. If you'd like to use this widget, you must also install it, which you can find here:
https://chrome.google.com/webstore/detail/mgmiemnjjchgkmgbeljfocdjjnpjnmcg
Do not misrepresent your relationship with the authors of this project (namely, me) or with the project itself.