Extension:CentralNotice: Difference between revisions
Update documentation to reflect r83754 |
|||
Line 8: | Line 8: | ||
|hook3 = MakeGlobalVariablesScript |
|hook3 = MakeGlobalVariablesScript |
||
|hook4 = LoadExtensionSchemaUpdates |
|hook4 = LoadExtensionSchemaUpdates |
||
|hook5 = SkinAfterBottomScripts |
|||
|license = GPL |
|license = GPL |
||
|author = [[User:Brion VIBBER|Brion Vibber]], [[User:Tfinc|Tomasz Finc]], [[User:Trevor Parscal|Trevor Parscal]], [[User:Kaldari|Kaldari]] |
|author = [[User:Brion VIBBER|Brion Vibber]], [[User:Tfinc|Tomasz Finc]], [[User:Trevor Parscal|Trevor Parscal]], [[User:Kaldari|Kaldari]] |
||
|parameters = |
|parameters = |
||
⚫ | |||
* $wgNoticeLang |
* $wgNoticeLang |
||
* $wgNoticeProject |
* $wgNoticeProject |
||
* $wgNoticeProjects |
* $wgNoticeProjects |
||
⚫ | |||
* $wgCentralDBname |
* $wgCentralDBname |
||
* $wgCentralPagePath |
|||
* $wgCentralNoticeLoader |
* $wgCentralNoticeLoader |
||
* $wgNoticeCookieDomain |
|||
* $wgNoticeTestMode |
|||
* $wgNoticeEnabledSites |
|||
* $wgNoticeTimeout |
|||
* $wgNoticeServerTimeout |
|||
* $wgNoticeCounterSource |
* $wgNoticeCounterSource |
||
|rights = |
|rights = |
||
* centralnotice-admin |
|||
* centralnotice_admin_rights |
|||
}} |
}} |
||
Line 37: | Line 36: | ||
The CentralNotice system consists of both '''campaigns''' (a.k.a. notices) and '''banners''' (a.k.a. templates). |
The CentralNotice system consists of both '''campaigns''' (a.k.a. notices) and '''banners''' (a.k.a. templates). |
||
*'''Banner''' |
*'''Banner''' β a single block of text/css/image that will display at the top of all set wiki pages. |
||
*'''Campaign''' |
*'''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''' |
*'''Preferred''' β A campaign with preferred set will always replace any other campaigns that happens to have the same language & wiki combo. |
||
*'''Locked''' |
*'''Locked''' β A locked notice can not be deleted unless it is unlocked. |
||
*'''Enabled''' |
*'''Enabled''' β only campaigns that are enabled will show banners. |
||
CentralNotice may work on a single wiki, but [[:meta:Help:CentralNotice|Wikimedia]] has a centralized setup, having CentralNotice extension installed on all wikis, |
|||
but the designated wiki instance (currently [[:meta:|Meta]]) is used to provide management interface as well. This designated wiki is called '''infrastructure wiki''' and has <code>$wgNoticeInfrastructure</code> set to "true". All sister wikis use |
|||
should have <code>$wgCentralDBname</code> 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 |
|||
<code>$wgCentralPagePath</code> (this is also [[:meta:|Meta]] in case of Wikimedia wikis). |
|||
== |
=== Settings === |
||
⚫ | |||
⚫ | |||
* '''<code>$wgCentralPagePath</code>''' β [[$wgScriptPath|Script path]] to the wiki serving actual banners. Should be adjusted if secure connection is used. |
|||
* '''<code>$wgCentralNoticeLoader</code>''' (default: true) β enable actual hooks. |
|||
* '''<code>$wgNoticeLang</code>''', '''<code>$wgNoticeProject</code>''' (default: [[$wgLanguageCode]] and "wikipedia") β Determines which banners will be selected for this project. |
|||
* '''<code>$wgNoticeProjects</code>''' β The infrastructure wiki uses this as a liste of possible <code>$wgNoticeProjects</code> that banners can be assigned to. |
|||
* '''<code>$wgNoticeCookieDomain</code>''' β Domain to have cookies set by the Special:HideBanner feature. |
|||
* '''<code>$wgNoticeCounterSource</code>''' β Full URL to the script that returns amount of money donated to the WMF. |
|||
=== |
===Permissions=== |
||
* '''<code>centralnotice-admin</code>''' β Permission required to modify campaigns and banners. Relevant only to the infrastructure wikis (see also [[:bug:26377]]). |
|||
⚫ | |||
⚫ | |||
===New Banner=== |
===New Banner=== |
||
Line 73: | Line 84: | ||
===Testing=== |
===Testing=== |
||
You can test-load any banner on any wiki by adding ?banner=<bannername> to the end of the URL. |
You can test-load any banner on any wiki by adding <code>?banner=''<bannername>''</code> 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.) |
You can simulate loading a wiki page from any country (to test campaign geotargeting) by adding ?<code>country=''<countrycode>''</code> to the end of the URL. (Use the 2-letter [[:w:ISO 3166-1|ISO 3166-1]] code.) |
||
==File descriptions== |
==File descriptions== |
||
CentralNotice includes the following files: |
CentralNotice includes the following files: |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.alias.php?view=log CentralNotice.alias.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.alias.php?view=log CentralNotice.alias.php] β the aliases for all of the [[special pages]] |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.db.php?view=log CentralNotice.db.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.db.php?view=log CentralNotice.db.php] β static functions for retrieving campaigns and banners from the database |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.i18n.php?view=log CentralNotice.i18n.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.i18n.php?view=log CentralNotice.i18n.php] β localized messages |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.php?view=log CentralNotice.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.php?view=log CentralNotice.php] β configuration, special page registration, hook functions |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.sql?view=log CentralNotice.sql] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/CentralNotice.sql?view=log CentralNotice.sql] β database set-up (updates handled by [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/patches/ patch files]) |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerAllocation.php?view=log SpecialBannerAllocation.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerAllocation.php?view=log SpecialBannerAllocation.php] β special page for viewing banner allocation, enabled if <code>$wgNoticeInfrastructure</code> is true |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerController.php?view=log SpecialBannerController.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerController.php?view=log SpecialBannerController.php] β generates Javascript file which controls banner selection on the client side, served from the local wiki |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerListLoader.php?view=log SpecialBannerListLoader.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerListLoader.php?view=log SpecialBannerListLoader.php] β generates JSON list of banners currently assigned to a particular wiki, served from the local wiki |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerLoader.php?view=log SpecialBannerLoader.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialBannerLoader.php?view=log SpecialBannerLoader.php] β generates Javascript which inserts a banner into the page (via insertBanner callback function), accessed via <code>$wgCentralPagePath</code> |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialCentralNotice.php?view=log SpecialCentralNotice.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialCentralNotice.php?view=log SpecialCentralNotice.php] β interface for admins to create and administer banner campaigns, enabled if <code>$wgNoticeInfrastructure</code> is true |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialHideBanners.php?view=log SpecialHideBanners.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialHideBanners.php?view=log SpecialHideBanners.php] β used to set cross-site cookies for hiding banners after someone has donated |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialNoticeTemplate.php?view=log SpecialNoticeTemplate.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/SpecialNoticeTemplate.php?view=log SpecialNoticeTemplate.php] β interface for admins to create and administer banners, enabled if <code>$wgNoticeInfrastructure</code> is true |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/TemplatePager.php?view=log TemplatePager.php] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/TemplatePager.php?view=log TemplatePager.php] β provides paging functionality for viewing banner lists in administrative interface |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/centralnotice.css?view=log centralnotice.css] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/centralnotice.css?view=log centralnotice.css] β CSS for administrative interface |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/centralnotice.js?view=log centralnotice.js] |
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/centralnotice.js?view=log centralnotice.js] β Javascript for administrative interface |
||
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CentralNotice/README?view=log README] β A document describing caching architecture of the extension |
|||
== Development == |
== Development == |
Revision as of 12:55, 12 March 2011
CentralNotice Release status: stable |
|
---|---|
Implementation | Special page |
Description | Adds a central sitenotice |
Author(s) | Brion Vibber, Tomasz Finc, Trevor Parscal, Kaldari |
Latest version | 2.6.1 |
MediaWiki | >= 1.42 |
Database changes | Yes |
License | GPL |
Download | |
|
|
|
|
Quarterly downloads | 27 (Ranked 117th) |
Public wikis using | 1,012 (Ranked 228th) |
Translate the CentralNotice extension if it is available at translatewiki.net | |
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
- Download the latest snapshot and extract it to your extensions directory.
- From the wiki root, run php maintenance/sql.php extensions/CentralNotice/CentralNotice.sql
- Add to LocalSettings.php.
require_once( "$IP/extensions/CentralNotice/CentralNotice.php" );
- The extension should now be active.
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 CentralNotice extension installed on all wikis,
but the designated wiki instance (currently Meta) is used to provide management interface as well. This designated wiki is called infrastructure wiki and has $wgNoticeInfrastructure
set to "true". All sister wikis use
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).
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 liste of possible$wgNoticeProjects
that banners can be assigned to.$wgNoticeCookieDomain
β Domain to have cookies set by the Special:HideBanner feature.$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 bug:26377).
New Banner
- Load Special:NoticeTemplate
- Click on the add banner link at the bottom of the page (must be logged in as an admin).
- Enter in a name and the raw HTML for the given banner.
- If this banner is going to be translated then enclose any text to be translated with triple parens - {{{FOO}}}.
- 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>
- Load Special:CentralNotice
- Add a campaign with a given start time at the bottom portion of the page and click submit.
- If this campaign is only run on a specific wiki and or language then select it from the pull downs.
- Click on the new campaign and add the banners you want within this running campaign and their respective weights.
- If all looks well then set this campaign to enabled and it will show at the corresponding time.
It was quickly realized that we were duplicating work when messages were copied over for such strings as Hide to each banner. Instead of this, the accepted practice to is to use a shared message for commonly used messages. Then use the following to reference it:
{{int:centralnotice-shared-message-name}}
Note only 2 curly brackets.
If there is a need to only do this for two banners then you might want to use the clone feature at the bottom of any banner page.
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
Development
See also
- Help:CentralNotice on meta
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
- Stable extensions
- Special page extensions
- Extensions with unknown license
- Extensions in Wikimedia version control
- Extensions which add rights
- BeforePageDisplay extensions
- SiteNoticeAfter extensions
- MakeGlobalVariablesScript extensions
- LoadExtensionSchemaUpdates extensions
- SkinAfterBottomScripts extensions
- All extensions
- Extensions used on Wikimedia
- Extensions for data exchange with other local wikis