Fundraising/Banner documentation

Some technical documentation/style guide on the fundraising banners.

Browser/device support[edit]

CentralNotice banners only get shown when JavaScript is enabled, which is generally for the "Modern" and "Unknown" browsers listed at https://www.mediawiki.org/wiki/Compatibility#Browsers. However since June 2021 we do not show fundraising banners in Internet Explorer. Since February 2023 frb.supportedBrowser in CoreJS tests for ES6 feature support, and banners will be hidden if it is false. That means we can start to use ES6 features.

Try to account for different screen sizes. Remember that "mobile" banners may also be shown on tablets, so should scale up.

WMF has an account at https://browserstack.com/ which might be useful.

Libraries[edit]

jQuery is always available with the alias $. As of April 2024 this is version 3.7.1.

There are various other javascript modules available, listed at https://www.mediawiki.org/wiki/ResourceLoader/Core_modules. However try to keep loading extra stuff to a minimum.

Coding conventions[edit]

We generally try to follow the guidelines at:

with the exception of using 4 spaces instead of a tab (because tabs don't work well in the wiki editor)

Avoid using <p> elements (other than to break up paragraphs in the main message) as MediaWiki styles can have unexpected effects on them.

CSS[edit]

CSS class/id names should be prefixed with "frb-" (fundraising banner). This is important to avoid clashes with other elements in the MediaWiki software or on the page (it's a wiki, so there can be unpredictable class names on the page). Classes are generally preferred to IDs.

All top level banner elements (e.g. the main banner, the "nag", the dialogs) should have class "frb" so they can share CSS resets and variables.

Everything uses box-sizing: border-box; for ease of sizing.

Use px for sizing, except for line-height and letter-spacing. If you are using em for line height and letter-spacing, use the CSS writing style below:

.frb-btn { 
    font-size: 16px; 
    line-height: 1.5; /*24px @16px*/ 
    letter-spacing: 0.031em /*0.5px @16px*/ 
}

The first value in the comment is the calculated px value
The @value in the comment is the context of the em calculation
The line-height property does not need a unit (em)
The letter-spacing property needs a unit (em)

JavaScript[edit]

All javascript functions and variables should be under the "frb" object or wrapped in a closure. Avoid globals.

Images[edit]

Don't load images (or any fonts, code etc.) off non-WMF servers. This is for security and privacy reasons.

Don't load images directly off Wikimedia Commons - they can be edited and overwritten by anyone. Instead either:

include the image inline (using <svg> or data: URI)
upload to donatewiki where access is restricted (include at least a link to the original file in the description)

Only use free/libre images in banners (except for payment method logos, which are allowed under fair use). If an image requires attribution, that should be included somewhere in the banner. Ask Pcoombe if you have any questions about this.

Sources for free images:

Wikimedia Commons (various licenses)

Remember to include alt text with images if necessary.

Design guidelines[edit]

These aren't binding - Fundraising generally has a fair amount of latitude to do "what works". But they can help to make banners fit in with the rest of the site and follow familiar patterns.

"OOUI" (MediaWiki interface toolkit) examples
Wikimedia Design Style Guide - the colour palette is especially useful.
Wikimedia brand guidelines - logos and colours
Codex - the Wikimedia Design System
Google Sheet compiling various colors

Translation[edit]

Some translated messages are included from a central banner location (currently "FR2015_translations")

e.g. {{{FR2015_translations,pm-creditcard}}} includes a translation of "credit card" in the current language.

When targeting other languages, make sure to preview banners and check that all required translations are included.

Watch out for right-to-left wikis e.g. Hebrew. Some CSS may need to be adjusted to account for them, you can use a body.rtl selector.

"Version control"[edit]

If there are changes to the banner due to fixing a bug or something that wins a test, then be sure to update the current best banner and leave a comment in the document.

Bugs[edit]

Bugs/issues should usually be tracked in Phabricator:

Wikimedia-Fundraising-Banners project for Fundraising banners (although internally we usually track with Asana)
Wikimedia-CentralNotice-Administration project for non-Fundraising banners
MediaWiki-extensions-CentralNotice for bugs with CentralNotice itself (optionally tagging Fundraising-Backlog if it's something that will affect Fundraising and needs attention from fr-tech)

Tips[edit]

Since the CentralNotice interface is just a bare text box with no syntax highlighting and other niceties, you might want to install a browser extension like GhostText which allows you to edit banners in your preferred text editor.