Extension:CentralNotice

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
CentralNotice

Release status: stable

Centralnotice-notice.png
Implementation Special page, API
Description Adds a central sitenotice
Author(s) Matthew Walker, Adam Roses Wight

Historical: Brion Vibber, Tomasz Finc, Trevor Parscal, Ryan Kaldari

License GPLv2
Download
Parameters
  • $wgNoticeInfrastructure
  • $wgNoticeLang
  • $wgNoticeProject
  • $wgNoticeProjects
  • $wgCentralDBname
  • $wgCentralPagePath
  • $wgCentralNoticeLoader
  • $wgNoticeCookieDomain
  • $wgNoticeCounterSource
Added rights
  • centralnotice-admin
Hooks used
BeforePageDisplay

LoadExtensionSchemaUpdates
MakeGlobalVariablesScript
SiteNoticeAfter
SkinAfterBottomScripts
UnitTestsList
User

Translate the CentralNotice extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

CentralNotice allows central distribution of small bits of translatable content (a.k.a banners) to subscribing wikis from one central infrastructure wiki. If you only need to post one global message (sitenotice) to a single wiki, consider using MediaWiki:Sitenotice instead.

Installation[edit | edit source]

Note: CentralNotice is developed, tested, and known to be deployed only on wikis that do not use table prefixing. If your setup uses table prefixing there is no guarantee this plugin will work.

For all wikis[edit | edit source]

  1. Download the latest snapshot and extract it to your extensions directory.
  2. Add
    require_once( "$IP/extensions/CentralNotice/CentralNotice.php" );
    or similar (depending on where your extension directory is located) to LocalSettings.php.

The infrastructure wiki[edit | edit source]

  1. From the command line, go to the wiki root and run php maintenance/update.php
  2. Edit LocalSettings.php and set ...
    1. $wgNoticeInfrastructure to true
    2. $wgNoticeProjects to be an array of projects that will subscribe to the central wiki. For example array( 'wikipedia', 'wiktionary' )
  3. By default the sysop group is the only group with the ability to administer CentralNotice. If additional groups are needed, assign them the centralnotice-admin and edit-interface permissions.

Subscribing wikis[edit | edit source]

Edit LocalSettings.php and set...

  1. $wgNoticeInfrastructure to false
  2. $wgNoticeProject to be an entry in $wgNoticeProjects
  3. $wgCentralHost to the protocol (potentially neutral) and domain of the central wiki. For example //meta.wikimedia.org
  4. $wgCentralPagePath to the public script path on the central wiki. For example //meta.wikimedia.org/w/index.php
  5. $wgCentralBannerDispatcher to the URL of Special:BannerRandom on the central wiki. For example: //meta.wikimedia.org/w/index.php/Special:BannerRandom
  6. $wgCentralBannerRecorder to the URL of Special:RecordImpression on the central wiki. For example: //meta.wikimedia.org/w/index.phpSpecial:RecordImpression

(For more information about these and other settings, please see CentralNotice.php.)

Getting help[edit | edit source]

The wikimedia fundraising team are the maintainers of CentralNotice. For questions about installation, bug reports, or usage of CentralNotice please send an email to wikitech-l@lists.wikimedia.org or join us on Freenode in channel #wikimedia-fundraising.

Permissions[edit | edit source]

  • centralnotice-admin — Permission required to modify campaigns and banners. Relevant only to the infrastructure wikis (see also bugzilla:26377).
    • edit-interface is required to edit banner content.

Design concepts[edit | edit source]

From a user facing perspective, the high level CentralNotice objects are campaigns (a.k.a. notices) and banners (a.k.a. templates). These are affected by the back end concepts of selectors and allocation.

  • Banner — a single block of translatable html/wikitext/css/javascript that will display at the top of Manual:$wgContentNamespaces pages. The user status, device type, UI language selectors are applied to banners.
    • Banners may be grouped by category. All banners in a category share user side cookies, such as the hiding cookie that is set when a user clicks a banner close button.
  • Campaign — a collection of banners. The project, country and content language selectors apply at the campaign level. The system allows as many active campaigns at the same time as you want dynamically calculating an allocation for each banner in an active campaign. Campaigns are defined as active if the central wiki time is greater than the campaign start time, less than the campaign end time, and the campaign is marked as enabled.
    • Banners in a campaign are assigned a bucket and weight. Buckets are yet another selector, and weight affects the relative allocation of banners inside a campaign.
    • There are four priority levels in CentralNotice. Higher priority campaigns will get a greater allocation of page views.
    • Campaigns may be locked which will prevent editing and deletion of the campaign; but not the banners inside a campaign.
  • Selector — any property which may be filtered on for the purposes of allocation. This allows, for example, different banners to be shown to logged in versus logged out users in Argentina browsing Wikipedia in English.
    • A selection vector is the complete set of selectors a user presents to the central wiki when requesting a banner.
  • Allocation — The chance a banner will be shown to a user under a given selection vector.

Design documents[edit | edit source]

Usage[edit | edit source]

Full usage instructions can be found at meta:Help:CentralNotice.

New Banner[edit | edit source]

  1. Load Special:CentralNoticeBanners
  2. Click on the add banner link at the bottom of the page (must be logged in as an admin).
  3. Enter in a name and the raw HTML for the given banner.
    1. If this banner is going to be translated then enclose any text to be translated with triple parens - {{{FOO}}}.
  4. Submit

(TODO: move and expand this snippet)

  • Each banner has its banner definition stored in MediaWiki:Centralnotice-template-<name>
  • All of its messages are stored below the banner def ala MediaWiki:Centralnotice-template-<name>-<message>/<language_code>

New Campaign[edit | edit source]

  1. Load Special:CentralNotice
  2. Add a campaign with a given start time at the bottom portion of the page, leave a comment, and click submit.
    1. If this campaign is only run on a specific wiki and or language then select it from the pull downs.
  3. Click on the new campaign and add the banners you want within this running campaign and their respective weights.
  4. If all looks well then set this campaign to enabled and it will show at the corresponding time.

Overriding selection[edit | edit source]

Add any of the following URL parameters to preview a specific banner, defeat "diet" schemes, or debug pseudorandom banner selection.

banner
You can test a banner directly on any wiki by adding ?banner=<bannername> to the end of the URL.
random
A decimal number between 0 and 1, which will be used as the "random" seed for choosing a campaign and banner.
country
Override the country code, before filtering to geotargeted campaigns. Accepts two-character ISO 3166-1 codes.
uselang
Its usual meaning in MediaWiki, this determines which banners you may be shown. Beware of content language vs. user language.
force
Override any banner hiding code, show the banner.
reset
Zero out any cookies being used to customize banner display (e.g. delivered impression count).

For example,

   http://en.wikipedia.org/wiki/Special:Random?banner=B14WMDE_141009_germany&uselang=en&force=1
   
   https://it.wikisource.org/wiki/Speciale:RandomRootpage?random=0.142

API[edit | edit source]

CentralNotice adds an API call centralnoticeallocations. This call returns the expected allocation of banners for both anonymous and logged in users in a given country, language, and project group.

It accepts three arguments

  • project - The project to filter on, ie: 'wikipedia' or 'wikibooks'
  • country - The ISO country code to filter on, ie: 'US' or 'RU'
  • language - The ISO language code to filter on, ie: 'en' or 'es'

As of this time, the XML output of this API does not work.

Development[edit | edit source]

See also[edit | edit source]

CentralNotice CentralNotice/Allocation history CentralNotice/Allocation system
CentralNotice/Allocation system/Notes CentralNotice/BannerController Events CentralNotice/Banner loading
CentralNotice/Banner mixins CentralNotice/Buckets CentralNotice/Caching Overhaul -- Edge Side Includes
CentralNotice/Database schema
CentralNotice/Phase 2 CentralNotice/Phase 3 CentralNotice/Phase 3/Open questions
CentralNotice/Slots CentralNotice/Special:RecordImpression