Help:CentralNotice

From Meta, a Wikimedia project coordination wiki
Jump to: navigation, search
CentralNotice
This is a technical manual to use Special:CentralNotice on Wikimedia. For the extension itself, see the Extension:CentralNotice page on www.mediawiki.org website.
Comment Before using CentralNotice, you should be very familiar with the content on this page. Changes to Special:CentralNotice affect all Wikimedia wikis, and should be done with extreme care and only if you know what you're doing.

The CentralNotice extension is the software mechanism that distributes global messages throughout Wikimedia. These messages are widely translated and typically relate to matters that concern the community at large, such as the 2009 shift to the CC-BY-SA 3.0 license, the annual Wikimania events, and the 2009 Strategy planning initiative.

CentralNotice admin is the interface used for the creation of CentralNotice banners and campaigns. How the CentralNotice admin works and how to use it are the primary concerns of this page. The CentralNotice admin is located at Special:CentralNotice and can only be used by Meta administrators or central notice administrators.

Campaigns[edit]

In order to display banners you must create a campaign. Campaigns allows fine grained control over what countries, languages and Wikimedia projects will see a set of banners in a given time period. Specifically a campaign has the following properties:

  • Enabled: When checked the campaign will be used to display banners.
  • Start date/time: Specified in UTC, if the campaign is Enabled banners will start to be displayed at this time.
  • End date/time: Specified in UTC, banners will stop being displayed at this time.
  • Priority: Priority levels dicate what campaigns will be shown when multiple campaigns target the same project, language, country, and user state (logged in/out). A lower priority campaign will never be shown; but if two or more campaigns share the same level the banner weights will be combined and share the allocation. See below in 'banner weights' for more detail.
  • Projects: Only selected Wikimedia projects will see the banners. Note that only desktop browsers can, at this time, recieve banners.
  • Languages: Only selected languages will see the banners.
    • For example if Projects is set to 'wikipedia' and language is set to 'es' only visitors to es.wikipedia.org will receive a banner.
    • The Top 10 Languages link will select the top ten languages that Wikimedia serves.
  • Geotargeted: Optional Only users in selected countries will see the banners.
    • To select banners the 'Geotargeted' checkbox must be selected.
    • Geotargeting is inexact and may occasionally locate a user to an incorrect country, or may fail to locate at all. In cases where location is not possible at all the following special countries are provided for targeting:
Country Code Name Description
XX Unknown/Non-Geolocatable Given when the data could not be processed or information simply does not exist.
A1 Unknown/Anonymous Proxy Given when the user is accessing Wikimedia sites through a known anonomizing service.
A2 Unknown/Satellite Provider Given when the user is accessing Wikimedia sites via a satellite connection.
O1 Unknown/Other Given in very rare cases when information exists, but not in sufficient quantity to determine a location.
EU Unknown/European Union Region Given in cases where a user could not be narrowed geographically down any further than the EU.
AP Unknown/Asia Pacific Region Given in cases where a user could not be narrowed geographically down any further than somewhere in the Asia Pacific region.
  • Bucketing: Optional
  • Locked: Optional No properties may be changed on a locked campaign unless the lock is removed first.

Manage campaigns[edit]

On Special:CentralNotice, one is immediately presented with a list of campaigns currently in use. The campaigns highlighted in green are currently active. Campaigns which are preferred are given precedence over other campaigns in situations where more than one campaign may be targeting the same wiki. If you wish to get rid of a campaign altogether, select "Remove". Once you are done making changes, click "Submit" at the bottom of the list.

The CentralNotice main page

Each item above links to a page containing details about a given campaign.

Editing a campaign[edit]

After clicking on the name of specific campaign, you will be presented with a page containing all the settings for that campaign, such as start date and end date, which wikis it is targeted to, etc. When you are done editing a campaign, click "Submit" at the bottom of the page.

The campaign below is targeted only to the Arabic Wikipedia within Egypt. It is enabled, preferred, and locked.

This campaign is enabled, preferred, and locked.

Creating a new campaign[edit]

To create a new campaign, scroll to the bottom of Special:CentralNotice and fill in the following form.

Add a campaign

Banners[edit]

Each campaign is assigned banners. Banners actually carry the message text, whereas the campaigns are topical categories for the banners. For example, during the 2008–2009 fundraiser, the "fundraiser_all_projects" campaign was assigned a variety of "please donate" and "personal appeal from Jimmy Wales" banners, each containing a unique message:

2008_scales
2008_scales
2008_jimmy_letter
2008_jimmy_letter

Right now, because the fundraiser has ended, fundraiser_all_projects is assigned only the post-fundraiser "thank you" note from Jimmy Wales:

2008_jimmy_thank_you_b
2008_jimmy_thank_you_b

If we click on a banner link, we are led on to another page from which we can edit the banner and insert translations of the message text. In 2008_jimmy_thank_you_b, we see the following directly below the Preview:

Messages and languages of 2008_jimmy_thank_you_b
Settings of a banner

"letter-url" and "personal-appeal" link to the MediaWiki-space pages at which the message text is contained: MediaWiki:Centralnotice-2008 jimmy thank you b-letter-url and MediaWiki:Centralnotice-2008 jimmy thank you b-personal-appeal are respectively the English translations. Altering the text here will automatically edit the relevant MediaWiki pages. We are able to insert new translations for the message text by selecting a language in the drop-down box below "Change translation language". The MediaWiki page for a message mmm in a template ttt in a non-English language qqq is at MediaWiki:Centralnotice-ttt-mmm/qqq. For example, the MediaWiki page for the Russian (ru) translation of the "personal-appeal" component of "2008 jimmy thank you b" is at MediaWiki:Centralnotice-2008 jimmy thank you b-personal-appeal/ru.

Beneath the language options is the banner settings. This allows you define whether the banners are seen by anonymous users, logged in users or both. The This is a fundraising banner enables the banner to point to multiple pages which the banner will link to randomly of equal weights. When enabling this option it forces the banner to go through LandingCheck. LandingCheck makes using localized and geotargeted landing pages easy. It was created as a replacement for the GeoLite extension.

It requires a base landing page which, when the LP is called, the extension checks to see if a version of the landing page exists for the user's language and country. If not, it looks for a version localized for the user's language. If that doesn't exist either, it looks for the English version. If any of those exist, it then redirects the user. An exception to these rules is when the user comes from a country that handles its own fundraising:

  • France (FR)
  • Germany (DE)
  • Switzerland (CH)
  • United Kingdom (GB)

In these instances, the language/COUNTRY system is switched to COUNTRY/language with the corresponding priorities switched as well. The banner enables tracking of banners/campaigns/landing pages through the use of utm url data.

Further down, we see the raw code for 2008_jimmy_thank_you_b – its look, colour, size, and formatting, and where the message snippets ("letter-url" and "personal-appeal") are located. It is inadvisable to edit the text in this box without purpose and without having a good knowledge of CSS.

The raw code for 2008_jimmy_thank_you_b

If we wish to assign more banners to "fundraiser_all_projects" campaign, we can return to the campaign's main page, tick "Add" for the banners we want under "Available banners", and click submit at the bottom of the page.

Available banners
Bottom of page
Submit

If we wish to create an entirely new banner, we go to the top of Special:CentralNotice, click "Banners", scroll to the bottom, and click "Add a banner":

Banners selected: Special:CentralNotice
"Banners" selected
Banners selected: Special:NoticeTemplate
"Banners" selected
Bottom of Special:NoticeTemplate
Add a banner

From Special:NoticeTemplate, we are also able to view, click on, and remove all banners currently available.

Targeting user groups[edit]

Each banner can be targeted to logged in users, anonymous users, or both. To target a group, select the checkbox next to it in the banner editing interface.

Targeting with Buckets[edit]

Bucketing allows easy A/B testing of banners. In the current configuration four buckets are available to place banners in. However, only the first two buckets will be randomly assigned to new users (a bucket will be assigned on first page view and is sticky for 7 days.) The 'C' and 'D' buckets must have users manually placed into them. This allows conditional testing of users (ie: they've seen more than 10 banners.)

To manually place a user into a bucket use code equivilant to the following. Keep in mind that in JavaScript buckets are represented as numbers; A: 0, B:1, etc.

// Get/set/modify the current bucket
mw.centralNotice.data.bucket = 2;
 
// Set the bucket
var expectedValidityString = mw.config.get( 'wgNoticeNumberOfBuckets' ) + '.' + mw.config.get( 'wgNoticeNumberOfControllerBuckets' );
$.cookie(
  'centralnotice_bucket', mw.centralNotice.data.bucket + '-' + expectedValidityString,
  { expires: mw.config.get( 'wgNoticeBucketExpiry' ), path: '/' }
);

Designing banners[edit]

Central Notice banners are composed of five different pieces:

  1. CSS
  2. JavaScript
  3. HTML
  4. Images
  5. MediaWiki messages (for localization)

CSS[edit]

When setting up any new banner it is vital that whatever CSS is used is isolated to just that banner. For instance B_1021_US1_Jimmy is an excellent example of good isolation. All of its css is prefaced with the specific identifier #B_1021_US1_Jimmy which corresponds to the id of the banner div.

Examples of bad banner css are selectors like a and div which would affect all text within the body of the page.

Since the z-index for the drop-down search suggestions is 1099, make sure that none of the elements in your banner have a z-index higher than that. Typically, banner elements are given z-indexes of 100 or less.

JavaScript[edit]

Some banners feature a custom set of JS for added functionality. 2009_Notice30 is an example of one that has an added goToDonationPage function which allows the destinaton url to be further randomized without the need for multiple banners.

Close button[edit]

Since the ability to dismiss a banner is core to the functionality of CentralNotice, the JavaScript code for it is located within the extension itself.

Since April 2014, it's also possible for a banner to dismissed on all wikis at once, so that users visiting multiple wikis don't have to dismiss it hundreds times.

Making a call to hideBanner() will hide the centralNotice div and set a cookie to hide subsequent banners of the same type for two weeks. This function can be inserted automatically by clicking on the 'Insert close button' link in the banner editing interface. The cookie for hiding banners only hides banners that are in the same banner group as the one that hideBanner() was called from. Currently there are two banner groups: fundraising and default. To put a banner in the fundraising group, check the checkbox that says "This is a fundraising banner".

Use of document.write() discouraged[edit]

Because CentralNotice banners are often not written into the page until after the page has finished loading, document.write() or document.writeln() statements within banners will sometimes overwrite the entire page rather than just inserting content within the page. To avoid this problem, insert dynamic content using the DOM rather than document.write().

For example, instead of doing:

Hello <script type="text/javascript">document.write( mw.config.get( 'wgUserName' ) );</script>!
Welcome to <script type="text/javascript">document.write( mw.config.get( 'wgSiteName' ) );</script>.

Use DOM insertion instead:

Hello <span id="cn-username"></span>! Welcome to <span id="cn-sitename"></span>.
<script type="text/javascript">
$('#cn-username').prepend(mw.config.get( 'wgUserName' ));
$('#cn-sitename').prepend(mw.config.get( 'wgSiteName' ));
</script>

HTML[edit]

When creating the actual structure of the banner, pay particular attention to keeping the design as simple as possible. Design them as if it was 1998 and use the lowest amount of complexity possible. 2009_Notice31 is a good example of very simple layout. All items are controlled through their own divs to allow for maximum customization while keeping the HTML simple.

Images[edit]

When using images in CSS or raw <img> tags, do not use a full URL like http://upload.wikimedia.org/... -- your banners will be loaded over HTTPS for users on the secure interfaces, and this can cause a warning message to display in some browsers.

Instead use the protocol-relative URL form like //upload.wikimedia.org/... instead; this will let the browser select HTTP or HTTPS as appropriate.

 #mobileSurvey2011-logo {
   position: absolute;
   top: 20px;
   left: 25px;
   background-image: url(//upload.wikimedia.org/wikipedia/commons/thumb/1/12/Wikimedia_logo_text_RGB.svg/60px-Wikimedia_logo_text_RGB.svg.png);
   height: 60px;
   width: 60px;
   background-repeat: no-repeat;
 }

MediaWiki messages[edit]

We utilize triple bracket mediawiki messages in order to allow for translations. In order to add a new message you simply add:

{{{varname}}}

and after the form submission you will see the new message show up in the template translation window. To add a new language translations change the language option under Language to the desired setting and add the new translation.

Shared message namespace[edit]

A convenient reuse available in the system is the ability to re-use messages from other banners. This allows us to not have to re-input the exact same message set that a collection of banners might use. An example would be:

 {{int:Centralnotice-2009_Notice1-donate-text2}}

What this means is that we are pulling the donate-text2 variable from the 2009_Notice1 banner and re-using its content. This is very helpful when you have multiple banners all needing to point to one url. By keeping it set on one banner you only have to change it in one place.

Many commonly used messages are available from the shared banner.

Magic messages[edit]

If you insert {{{amount}}} into the body of the banner, it creates a special message that gets the current fundraising total (in millions of dollars) as a token. The token is referenced with the string '$1'. So if you wanted a banner to display the current fundraising amount as '$12.1M' you would use '$$1M' as the English translation for the amount message. If you just want the raw number (for Javascript calculations), use '$1' as the translation. This is commonly used for controlling the animation of "thermometer banners".

You can also get the daily fundraising total using {{{daily-amount}}}. This returns the total for the current day (UTC) in thousands of dollars. It is also referenced with the token '$1'.

You can use the magic message {{{campaign}}} to insert the name of the campaign, or the magic message {{{banner}}} to insert the name of the banner. Neither of these require translation.

Creating a new banner[edit]

If one is lucky then the banner you are trying to add already has a close approximate in the system. Copy the existing body into a new banner by following the link at the bottom of the Banners tab labeled 'Add a new banner' . Add the appropriate new messaging and load the inline preview to validate that all is well.

Note: Do not try to clone the banner via the "Create a copy of the banner" option, this is not what you want. That duplicates the banner entirely, including all of the translations.

Working with Translations[edit]

New Translation System -- Stand in documentation

QA testing[edit]

Campaigns[edit]

You can simulate loading a wiki page from any country (to test campaign geotargeting) by adding ?country=<countrycode> to the end of the URL. (Use the 2-letter ISO 3166-1 code.)

Banners[edit]

Once a banner is configured in the CentralNotice system it is up to the editor to make sure it looks correct across all of our supported browsers. There are currently four steps to verify a banner:

  1. After saving your html/css/js, use the inline preview to verify that the content is as it should be.
  2. If the inline preview looks OK, then select the option labeled Preview all available translations of banner. If you have any translations other then English you should see them now. Pay close attention to spacing and text that is too long and either adjust the messaging or html/css to accommodate it as best as possible.
  3. Next, go to the Main Page of one of the wikis that you are going to run the banner on. Add ?banner=<bannername> to the end of the URL and reload. You should then be able to see the banner as it will appear when it goes live. Because there are local CSS quirks on every wiki, you may want to test the banner on all of the high-traffic wikis that you are going to run the banner on. It is also important to test on multiple browsers as we have a diverse set of users who use ie6+, firefox2+ and many others.
  4. If all has gone well, you're likely ready to push it into production. Please clear the messaging that is used on the banner with the respective communities before enabling anything. Having gotten approval, add your banner to the correct campaign and load it on the wiki in question. You may need to do a hard refresh to see the new banner since the banner list is cached.

Do not rely on the NoticeTemplate view to be an accurate representation of the banner. The only way to see a completely accurate preview is use ?banner=<bannername>

Specific tips[edit]

General[edit]

  • Link to a page to translate the banner, it's best to have that be a subpage of CentralNotice (see the others for examples).
    • However, if this banner is being shown to all users, it's best to omit that link. (Vandalism frequently occurs in these cases, and we don't want bad words showing at the top of all of our wikis.)
  • Links are necessary, but remember that we can't use wikitext, so be sure to use <a href= instead.

Elections[edit]

  • Don't link directly to the voting page, link to some page explaining the vote first. Otherwise, people are more likely to be confused and just vote without knowing what they're voting for.
  • If possible, try to restrict the campaign to only show to people it relates to (see example js).

See also[edit]

  • CentralNotice – A translation landing page for current CentralNotices.


Links to other help pages[edit]

Help contents
Meta · Wikinews · Wikipedia · Wikiquote · Wiktionary · Commons: · Wikidata · MediaWiki · Wikibooks · Wikisource · MediaWiki: Manual · Google
Versions of this help page (for other languages see further)
What links here on Meta or from Meta · Wikipedia · MediaWiki
Reading
Go · Search · Stop words · Namespace · Page name · Section · Backlinks · Redirect · Category · Image page · Special pages · Printable version
Tracking changes
Recent changes (enhanced) | Related changes · Watching pages · Diff · Page history · Edit summary · User contributions · Minor edit · Patrolled edit
Logging in and preferences
Logging in · Preferences · User style
Editing
Starting a new page · Advanced editing · Editing FAQ · Edit toolbar · Export · Import · Shortcuts · Edit conflict · Page size
Referencing
Links · URL · Piped links · Interwiki linking · Footnotes
Style and formatting
Wikitext examples · CSS · Reference card · HTML in wikitext · Formula · List · Table · Sorting · Colors · Images and file uploads
Fixing mistakes
Show preview · Testing · Reverting edits
Advanced functioning
Expansion · Template · Advanced templates · Parser function · Parameter default · Variable · System message · Substitution · Array · Calculation · Embed page
Others
Special characters · Renaming (moving) a page · Preparing a page for translation · Talk page · Signatures · Sandbox · Legal issues for editors
Languages: English