Extension:CentralNotice/Banner mixins (deprecated)

From MediaWiki.org
Jump to: navigation, search

Introduction[edit]

A banner mixin is a reusable component which can be shared by many banners. It is a way of packaging source code, similar to ResourceLoader.

The goal is to push common tasks and challenges faced when writing CentralNotice banners into libraries that are available to everyone.

Maturity: This feature is currently beta quality and subject to further development. Proceed with caution.

Administrative interface[edit]

In Special:CentralNotice, navigate to the edit page for your banner. Find the Mixins section and select checkboxes for each mixin you wish to enable.

CentralNotice banner mixin admin.png

Once you save your changes, any new magic words provided by the mixins will appear in the listing above the banner content.

CentralNotice banner mixin magic words.png

Implementation[edit]

There are three categories of behavior provided by mixins, and they may all be combined in a single mixin.

Preload rule[edit]

A javascript snippet which is executed before the banner is displayed, and determines whether to show or hide the banner.

Example usage: The banner cookie diet checks whether a reader has already seen this banner, and if so, prevents display.

Server computation[edit]

PHP functions which substitute dynamic values for placeholders can be included in a MediaWiki extension or in CentralNotice itself. These placeholders are formed using triple-braces e.g., "{{{variable-name}}}". Each is calculated by a function, which may take arguments passed using the syntax, "{{{variable-name:arg1|arg2|arg3}}}".

Example usage: daily and cumulative thermometers for the total given during a fundraising campaign, and core donation form HTML.

ResourceLoader bundle[edit]

JS and CSS which will be loaded using MediaWiki's Resource Loader. This will benefit from caching, RTL support, and minification, as usual.

Example usage: dropdown donation form logic and styles.

List of mixins[edit]

There is one mixin available, as a proof of concept:

BannerDiet 
code Basic cookie-counting scheme which will limit the number of times a viewer sees banners from each group. Operation is dependent on two variables, "hide-cookie-name", which defines the group that the banner belongs to, and "hide-cookie-max-count", which is the maximum number of times a person should see the banner.

Writing mixins[edit]

Mixins are packaged as part of CentralNotice, or in another MediaWiki extension. Append your mixin definition to $wgNoticeMixins, the data structure may have the following keys:

$wgNoticeMixins['ScheduledBanner'] = array(
    'localBasePath' => __DIR__ . '/mixins/ScheduledBanner',

    'preloadJs' => 'CheckScheduledVisibility.js',
    'php' => 'SchedulingLibrary.php',
    'resourceLoader' => 'ext.scheduledBanner.calendarStyles',
);

If you want to propose a new mixin, please write to centralnotice-admins@lists.wikimedia.org with your idea, or submit a patch to CentralNotice for review.