Extension:CentralNotice

MediaWiki extensions manual - list

CentralNotice Release status: stable
Implementation	Special page, API
Description	Adds a central sitenotice
Author(s)	Brion Vibber, Tomasz Finc, Trevor Parscal, Kaldari
License	GPL
Download	Download snapshot (Git master) Git [?]: repo summary tree code changes
Parameters $wgNoticeInfrastructure $wgNoticeLang $wgNoticeProject $wgNoticeProjects $wgCentralDBname $wgCentralPagePath $wgCentralNoticeLoader $wgNoticeCookieDomain $wgNoticeCounterSource
Added rights centralnotice-admin
Hooks used BeforePageDisplay LoadExtensionSchemaUpdates MakeGlobalVariablesScript SiteNoticeAfter SkinAfterBottomScripts UnitTestsList User
Check usage and version matrix

CentralNotice adds the possibility to manage sitenotices from one central wiki. If you only need to post one global message (sitenotice) to a single wiki, you may want to use MediaWiki:Sitenotice instead.

Installation

Note: CentralNotice assumes you are not using table prefixes in your database. If you are, it is likely to not work.

1. Download the latest snapshot and extract it to your extensions directory.
2. Add
   require_once( "$IP/extensions/CentralNotice/CentralNotice.php" );
   to LocalSettings.php.
3. From the command line, go to the wiki root and run php maintenance/update.php
4. The extension should now be active.

Settings

• $wgNoticeInfrastructure (default: true) — Set to true on the infrastructure wiki (the wiki you will be managing the campaigns from). Set to false on your target wikis.
• $wgCentralDBname (default: $wgDBname) — The name of the database for the infrastructure wiki. (This is needed so that the target wikis can retrieve banners from the controller wiki.)
• $wgCentralPagePath — Script path to the wiki serving actual banners. Should be adjusted if secure connection is used.
• $wgCentralNoticeLoader (default: true) — enable actual hooks.
• $wgNoticeLang, $wgNoticeProject (default: $wgLanguageCode and "wikipedia") — Determines which banners will be selected for this project.
• $wgNoticeProjects — The infrastructure wiki uses this as a list of possible $wgNoticeProjects that banners can be assigned to.
• $wgNoticeCookieDomain — Domain to have cookies set by the Special:HideBanner feature.
• $wgNoticeHideBannersExpiration - When the cookie set by Special:HideBanner should expire
• $wgNoticeCounterSource — Full URL to the script that returns amount of money donated to the WMF.

Permissions

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

Design

The CentralNotice system consists of both campaigns (a.k.a. notices) and banners (a.k.a. templates).

• Banner — a single block of text/css/image that will display at the top of all set wiki pages.
• Campaign — a collection of banners that are set to show according to a specified weight. You can configure as many campaigns at the same time as you want and each one will show with its configured banners at their own weighted percentages.
• Preferred — A campaign with preferred set will always replace any other campaigns that happens to have the same language & wiki combo.
• Locked — A locked notice can not be deleted unless it is unlocked.
• Enabled — only campaigns that are enabled will show banners.

CentralNotice may work on a single wiki, but Wikimedia has a centralized setup, having the CentralNotice extension installed on all wikis, but the designated wiki instance (currently Meta) is used to provide the management interface. This designated wiki is called the infrastructure wiki and has $wgNoticeInfrastructure set to "true". All sister wikis should have $wgCentralDBname set to the database name of the infrastructure wiki in order to be able to roll out the centrally defined campaigns. Actual banners are served from the central wiki, as defined by $wgCentralPagePath (this is also Meta in case of Wikimedia wikis).

Other technical articles are broken out by category:

• Banner allocation algorithm
• Database schema / table layout

Usage

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

New Banner

1. Load Special:NoticeTemplate
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

New Campaign

• 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>

1. Load Special:CentralNotice
2. Add a campaign with a given start time at the bottom portion of the page 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.

Testing

You can test-load any banner on any wiki by adding ?banner=<bannername> to the end of the URL.

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.)

File descriptions

CentralNotice includes the following files:

• CentralNotice.alias.php — the aliases for all of the special pages
• CentralNotice.db.php — static functions for retrieving campaigns and banners from the database
• CentralNotice.i18n.php — localized messages
• CentralNotice.php — configuration, special page registration, hook functions
• CentralNotice.sql — database set-up (updates handled by patch files)
• SpecialBannerAllocation.php — special page for viewing banner allocation, enabled if $wgNoticeInfrastructure is true
• SpecialBannerController.php — generates Javascript file which controls banner selection on the client side, served from the local wiki
• SpecialBannerListLoader.php — generates JSON list of banners currently assigned to a particular wiki, served from the local wiki
• SpecialBannerLoader.php — generates Javascript which inserts a banner into the page (via insertBanner callback function), accessed via $wgCentralPagePath
• SpecialCentralNotice.php — interface for admins to create and administer banner campaigns, enabled if $wgNoticeInfrastructure is true
• SpecialHideBanners.php — used to set cross-site cookies for hiding banners after someone has donated
• SpecialNoticeTemplate.php — interface for admins to create and administer banners, enabled if $wgNoticeInfrastructure is true
• TemplatePager.php — provides paging functionality for viewing banner lists in administrative interface
• centralnotice.css — CSS for administrative interface
• centralnotice.js — Javascript for administrative interface
• README — A document describing caching architecture of the extension

API

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

• /Phase 2 - Completed
• /Phase 3 - Completed
• /Caching Overhaul -- Edge Side Includes
• /Objectivization and ContentHandler
• /BannerController Events

See also

• Help:CentralNotice on meta
• CentralNotice/Optimizing banner loading on wikitech

CentralNotice	CentralNotice/Allocation history	CentralNotice/Allocation system
CentralNotice/BannerController Events	CentralNotice/Banner mixins	CentralNotice/Buckets
CentralNotice/Caching Overhaul -- Edge Side Includes	CentralNotice/Database schema	CentralNotice/Fundraiser2011 Requirements
CentralNotice/Phase 2	CentralNotice/Phase 3	CentralNotice/Phase 3/Open questions
CentralNotice/RFC: Allocation system	CentralNotice/Slots