Adding a new Sky Light

[Quicksaver]

If you believe there's some functionality within Firefox that would benefit from being shown in Sky Lights, please let me know by opening a new issue or posting here about it.

Of course, I'm sure there are other add-ons that might benefit from adding their own lights as well. If you'd like to see an add-on you use in their own light, please try contacting its developer first and direct them to this page. Controlling a light is better done by the add-on itself, as only the add-on itself will know exactly what light to show and when.

For Developers

I've kept the process to add new lights as simple and as direct as possible. But should you have any questions or problems, let me know and I'll do my best to resolve them. I also encourage you to subscribe to this issue, so that you're notified of any changes to the Sky Lights system immediately if/when I make them.

Before anything, Sky Lights might not be enabled all the time the add-on is enabled, so just checking for the add-on itself isn't enough. Instead, the easiest method is to set the following event listeners:

// 'LoadedSkyLights' will be fired every time the Sky Lights system starts,
// ditto for 'UnloadingSkyLights' when disabling it.
window.addEventListener('LoadedSkyLights', doLoadStuff);
window.addEventListener('UnloadingSkyLights', doUnloadStuff);

To check if the Sky Lights are already loaded at any point, you can just check for something of the sort:

// .theFoxOnlyBetter exists when the add-on is enabled in a given window,
// its .skyLights property will be an object only if the Sky Lights are enabled,
// otherwise it'll be undefined.
lightsLoaded = !!(window.theFoxOnlyBetter && window.theFoxOnlyBetter.skyLights);

To control your light, you use the update() method. The first time you call it, the light is created after all other lights; subsequent calls update the already existing light. Note that the user always has the final say in the relative position of each Sky Light, and also if it should not be shown at all!

update() takes two mandatory parameters: a string id and a simple object with the light's parameters, all of which are optional and only those supplied will be changed/updated; parameters set in previous calls to update() won't be changed if not specified, and will stay in effect until explicitly set again.

theFoxOnlyBetter.skyLights.update('myLightID', {
  label: (string) 'My Light',
  description: (string) 'My Light does this and that.',
  state: (string) 'someState',
  tooltip: (string) 'some text',
  context: (string) 'myMenuID',
  color: (string) 'any color',
  action: (method) function(event) { doSomething(); },
  active: (bool) true/false,
  alert: (int) 3 || (bool) true/false,
  speed: (int) 500
});

• myLightID - should be a name or a simple but unique identifier for your light; it will be used as the light's DOM node ID, as: theFoxOnlyBetter-skyLights-myLightID.
• label - the user-friendly name of your light, shown in the Sky Lights customization area of the add-on preferences tab; this will likely just be the name of your add-on. If not provided, myLightID will be used instead.
• description - a short description of what the light will show/do, to be appended to the helptext area in the add-on preferences tab (the panel that appears when moving the mouse over the Sky Lights customization area). If not provided, no description for the light will be shown in that area.
• state - a simple string identifying the current state of the light should you need it; it will be applied as a state attribute to the light's DOM node; in CSS you'd check for it as #theFoxOnlyBetter-skyLights-myLightID[state="someState"].
• tooltip - a small text string to be shown when the mouse hovers the light.
• context - the node ID for whichever menu that should be shown when the user right clicks the light.
• color - the color to set the light to; can be any identifying color string, including "transparent", hex code, rgb/a or hsl/a value or pretty much anything that can be applied as the background-color CSS property.
• action - if provided, this method will be called when the user clicks the light; it will be passed the event object associated as its only argument.
• active - if true, the light will stay bright, as if the mouse is always over it.
• alert - an integer set to the number of times the light will blink to call attention to itself; if (bool) true, the light will blink indefinitely until the mouse hovers it.
• speed - an integer set to the duration of each phase of the light's blinking animation when its alert state is enabled; if not set each phase will default to a duration of 500ms.

You also have available a method to quickly retrieve the DOM node for your light, should you need it for whatever reason:

theFoxOnlyBetter.skyLights.get('myLightID');

To remove your light, for example when your add-on is disabled, you should use:

theFoxOnlyBetter.skyLights.remove('myLightID');

For a thorough example of how to use these, you can see how I implement the Identity Box as a Sky Light in https://github.com/Quicksaver/The-Fox--Only-Better/blob/master/resource/modules/compatibilityFix/identityBox.jsm

I highly recommend you include an icon for your Sky Light (maybe use the add-on's own icon if you also used its name for the label), to act as a visual aid when customizing the lights in the add-on preferences. It will appear as a 32 x 32px image in the center of the light's customizable node item, reachable with the CSS selector #theFoxOnlyBetter-DnDpref-myLightID .DnDpref-icon. You can see this is how I add icons for the Sky Lights already included: https://github.com/Quicksaver/The-Fox--Only-Better/blob/master/chrome/skin/common/options.css

In case your original function was implemented through a toolbar or a customizable button, you'll probably want to keep it visible in the mini bar as well, to complement the Sky Light when it's hidden. This is very simple to do, just add a showInMiniBar="true" attribute to your toolbar or button node, and it will stay visible in the mini bar.

[Quicksaver]

Added ability to keep buttons visible in the mini bar, to complement the Sky Light.

[Quicksaver]

Added information about how to add labels and icons for the Sky Lights customization area.

[Quicksaver]

Changed alert and added speed properties to the Sky Lights.

[CherenTheCat]

I believe a Sky Light that allows you to refresh the page without having to open the chrome would be helpful, since the chrome can sometimes block the top of the page and makes it hard to use some of the page, especially right after a refresh.