Adding a new fix

To add a new fix to SOUP, you need to add an entry into the fixes list. A simple fix could look like this:

fixes.hello_world = {
	title:	"Hello, World!",
	url:	"http://www.example.com/hello_world",
	credit:	"Ilmari Karonen",
	script:	function () {
		$('#content').prepend('<div id="soup-hello">Hello, World!</div>');
	},
	css:	".soup-hello { text-align: center; color: green;" +
			" border: 1px solid red; margin: 5px 0 }"
};

Each fix needs a unique identifier (like hello_world above). By convention, the identifiers are based on the URL of the fix, which normally points to a bug report or a feature request describing the issue on Meta Stack Exchange or on one of the per-site metas.

Specifically, the identifier usually is:

• for issues reported on Meta Stack Exchange or Meta Stack Overflow, mse or mso followed by the question ID number of the report (e.g. mse123456), or
• for issues reported on one of the other per-site metas, the site host name followed by the question ID there (e.g. math12345 for a report on Meta Mathematics Stack Exchange).

The JS object literal encoding the fix may contain the following properties:

Metadata fields:

• title: A descriptive title of the fix; often the title of the bug report or feature request describing the issue being fixed.

• url: A URL to a page describing the issue in more detail. Typically a shortcut ("share") URL to the relevant bug report or feature request on Meta Stack Exchange or one of the per-site metas. The fix ID is typically based on its URL, although this is just a convention.

• credit: If the fix is fully or partially based on code written by someone other than the main SOUP devs (currently just me, Ilmari Karonen), this free-form string can be used to give credit where credit is due.

These metadata fields are not currently used for anything, except to keep the code self-documenting. (In the future, they might be used e.g. for a control panel allowing users to toggle individual fixes on and off.) Nonetheless, you should provide at least a title and a descriptive URL for your fix.

CSS / JS code:

• css: A snippet of CSS code in a string, to be injected into the page as soon as it begins to load. Note that, due to the early injection, CSS rules specified here will normally be overridden by conflicting SE CSS rules of equal precedence; thus, specificity hacks like prepending body to selectors may sometimes be necessary.

  If a fix can be implemented using pure CSS, it usually should be. Note that CSS fixes may be applied even if the user has disabled JavaScript for the page (or even if a bug causes the SE JS framework to crash), so fixes containing both CSS and JavaScript should be designed to degrade gracefully if only the CSS portion is applied.

• script: A JavaScript function to be injected to the page and executed using the StackExchange.ready() mechanism after the DOM, jQuery and the Stack Exchange JS framework have finished loading. (On SE chat, which doesn't have the standard SE JS framework, these scripts are executed using jQuery.ready() instead.) This is where most non-CSS fixes do their work.

• early: Same as script, except that any JS code given here will be injected and executed immediately after the soupInit function. Note that this (usually) happens before the DOM is fully built up and before any page JS is executed. Thus, pretty much the only useful thing you can do here is attach early event handlers to window or document to catch events generated while the page is loading.

• mathjax: JS code to be injected as a MathJax config script, allowing you to patch MathJax or tweak its settings before the initial math typeset pass. Note that, at this early stage, jQuery and the SE framework may not be ready yet, so you should use native JavaScript for any DOM manipulation you may need to do here. On sites that don't use MathJax, the code will be injected but will never run.

• jqinit: JS code to be executed as soon as SOUP detects that jQuery has loaded. Useful for fixes that need to patch jQuery functions.

To be useful, a fix needs to contain at least one of the five properties above. Technically, that's all that's needed, although you should still specify at least a title and a URL too.

The normal execution order of the different JS sections is early → (mathjax) → jqinit → script. This is not 100% reliable, however. In particular, MathJax init code might get called long after other scripts have run if MathJax loading is delayed for some reason. Also, some user script managers may fail to properly implement @run-at document-start, in which case all fixes might get delayed until after the page has already fully loaded. (This can also happen if the user has SOUP disabled and re-enables it while viewing a page.)

Site filter regexps:

• sites: A regular expression which needs to match against location.hostname for the fix to be applied. Useful for site-specific fixes.

• exclude: Same as sites, except that the fix will not be applied if this regexp matches the hostname. If both sites and exclude are given and match, exclude wins.

• path: Same as sites, but matched against location.pathname instead. Useful for fixes that only affect specific parts of the site, such as review.

These properties can be used to control which sites and pages the fix is applied to. A fix that fails one of these filters will be skipped, and none of its CSS or JS parts will be applied.