Websites/Snippets/about:home 101
Warning: This document is out-of-date; see https://abouthome-snippets-service.readthedocs.org/en/latest/developing.html#snippet-requirements for a more up-to-date description of the requirements for developing a snippet.Since Firefox 4, about:home has been hosted locally within the browser instead of by Google. Snippets displayed on about:home follow different rules than the old snippets, and this page attempts to explain the process that the browser goes through to retrieve and display snippets on about:home.
Contents
What are Snippets?
Snippets are nothing but HTML, CSS, and Javascript. With a few exceptions[1], anything that is possible on a normal webpage should be possible on about:home. Please check with the snippets team first before planning a snippet that has special functionality, such as video, animation, or other interactive components.
Snippets:
- Must be well-formed XML
- Must use data: URIs for images to avoid excessive requests.
- Must embed Javascript and CSS directly rather than using external files.
- Should not distract from the search bar functionality of the page.
- Should be 200kb or less in size.
- Should not remove focus from the search box or expect immediate focus or input.
[1]: The biggest example is iframes, which break other about:home functionality. See bug 682944.
Retrieving Snippets
Snippets are saved for 24 hours after they are retrieved from the central snippets service in localStorage. The main keys in localStorage that are used are:
- snippets-last-update - A timestamp indicating when the last snippets update was.
- snippets - The chunk of HTML, CSS, and Javascript that was last retrieved from the snippets service.
The snippets service uses a URL containing information about the requesting browser to serve snippets. The URL that is accessed takes the form:
For example, if you are running Firefox Aurora with en-US as your locale, you would access:
Snippets are served as a chunk of HTML, CSS, and Javascript. The snippet service takes all the snippets that match your browser, bundles them together, and returns the resulting markup.
Displaying Snippets
The chunk of markup is directly injected into the page. Afterwords the included Javascript is evaluated.
There are two snippets that must always be delivered along with all public snippets: the global CSS snippet, and the global Javascript snippet. The CSS snippet contains style info that hides all the snippets. The Javascript snippet contains code that randomly chooses a snippet, displays it to the user, and runs any code that is registered to run when that particular snippet is displayed.
Tools
There is an addon that forces your about:home page to retrieve new snippets every time it is viewed, and lets you control which snippet server you get snippets from and what parameters you send. You can find a download link to the about:home Snippet Switcher on its Github Downloads Page.
Manually Forcing a Snippet Refresh
You can also force your browser to retrieve new snippets without the addon:
- Go to about:home.
- Open the Web Console (Cmd-Alt-K on OS X)
- Run: gSnippetsMap.clear()
- If you are using Firefox 24 or earlier, you have to run this instead: localStorage['snippets-last-update'] = 0
- Open the History -> Clear Recent History menu item, check only "Cache" and set the time range to "Everything" and click "Clear Now".
- Refresh about:home
Note that you still have to close and reopen Firefox if you changed the snippets URL via about:config. It's recommended to close and reopen Firefox prior to following the steps above in that case.
Managing Snippets
Snippets are managed using a Django admin interface that can be accessed through the web VPN at http://vpn.mozilla.com. Snippets are matched using Client Match Rules, which are explained in the service page.
Links
- Snippets Stage Server: http://snippets.stage.mozilla.com
