Stack Exchange Topbar Tools 0.2.1

(aka SETT)

A JavaScript library for doing all sorts of stuff with the new black Stack Exchange top bar. It's not finished. The cool stuff will be implemented Real Soon Now™.

Getting Started

This library uses two names in global scope - StackExchangeTopbarTools and StackExchangeTopbarToolsPluginInit. The former contains all code supplied by the library; the latter is used in the plugin initialisation process to make it guaranteed to not blow up.

Plugins can make use of SETT by simply using the following code template:

function with_jQuery(f) {
  var s = document.createElement("script");
  s.type = "text/javascript";
  s.textContent = "(" + f.toString() + ")(jQuery)";
  s.setAttribute('data-with-jquery', '');
  document.head.appendChild(s);
};

with_jQuery(function($) {
  (window.StackExchangeTopbarToolsPluginInit
   = window.StackExchangeTopbarToolsPluginInit
   || []).push(function(SETT) {
    
    // Your plugin code goes here
    // You can refer to the library object by the shorthand SETT
    
  });
  if (typeof window.StackExchangeTopbarTools === 'object')
    window.StackExchangeTopbarTools.pluginsReady();
});

Userscript plugins are advised to use only the following @include:

// @include /^https?:\/\/(.*\.)?(?:(?:stack(?:apps|exchange|overflow)|superuser|serverfault|askubuntu)\.com|mathoverflow\.net)\/.*/

Don't worry that this seems overly inclusive; the master SETT script is more selective about where it is run, and the plugins won't do anything without it.

Attributes of the bar itself

Background color

SETT.topbar.color(new background color);

Supply a string containing any color accepted by CSS (for example, '#824D07').

Viewport-related stuff

SETT.topbar.floating(bool);

True means float at top of viewport, false means don't. If omitted, changes to whatever it isn't doing now.

SETT.topbar.fullWidth(bool);

True means expand to full width of viewport, false means stay 980px wide. If omitted, changes to whatever it isn't doing now.

The links on the RHS

Adding links

SETT.links.append({
  id: link ID (not a DOM ID),
  text: link text,
  tooltip: text to display on mouseover,
  href: navigation target,
  on: {
    click: code executed on click,
    tick: code executed every second,
  },
}, ...);

Use links.prepend instead of links.append to add the links at the start instead of the end.

• .id is the ID of the link, used internally to refer to that link. No two links may share an ID; this is enforced by code.

• .text is the human-readable text of the link.

• .tooltip is the text displayed in that tooltip thing that appears when you mouse over the link. Implemented using the HTML title attribute.

• .href is the target of the link (that is, where you go when the link is clicked).

• .on contains event-handling functions:

  • .on.click is executed when the link is clicked. If specified, this overrides .href on a left-click (think e.preventDefault()). Called with one parameter - the jQuery click event.
  • .on.tick is executed every second. This can be useful, say, for updating a clock. Called with one parameter - the current date, adjusted for skew between you and SE.
  • .on.floating and .on.fullWidth are executed when the corresponding SETT.topbar methods are called. Called with one parameter - the corresponding method's return value.

  In all cases, the handler's this is set to an object containing the element in question as elem and the abstraction object as object.

Link object methods

SETT.links(link ID).[...];

The link ID is the same one that was used as the .id option when the link was added.

Change text

link.text(new text);

Pulse color

link.pulse(success);

Call this method on your link to indicate the success (pass true) or failure (pass false) of whatever it was meant to be doing, or just to notify something (no argument). Close to useless on links without any .on handlers.

Change unread counter-bubble

link.unread(count);

A falsy value (like 0 or null) will cause the bubble to be hidden. Any other value will show the bubble containing that text; it will stay shown until hidden again.

Remove

link.remove();

Changing link color globally

SETT.links.color(new foreground color);

Supply a string containing any color accepted by CSS (for example, '#26D8D8').

RHS links supplied by SE

All of the following can be referred to by an ID equivalent to their names.

• help dropdown (when logged in)
  You can't really do much with this, though. Dropdown support isn't yet implemented.
• review
• tools