Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

ResourceLoader: Document the clientPrefs system and make Skin option

Browse source 
Move parts of implementation code comments into something that is
discoverable and understable to a general audience of MW core and skin
developers (not hidden in code mostly seen by maintainers
and contributors to ResourceLoader internals).

Most notably, that the system is turned off by default (and how to
turn it on), that it is limited to requests by unregistered users,
and that the class must follow a certain pattern.

$wgResourceLoaderClientPreferences is removed as part of this.

This is not considered a breaking change as the feature is now
automatically on in the skins needs it (via skin.json), and previously
it was marked experimental and off by default.

Skins are naturally required to have knowledge of this system, as they
need to call into it to persist classes for feature toggles. By removing
the need to also enable it at the site-level we get a few benefits:

1) make skins like Vector easier to correctly install and configure.
2) ease maintenance for skin devs by removing the need to manually
   export and check $wgResourceLoaderClientPreferences before calling
   mw.user.clientPrefs or otherwise hinting in UI or docs that the
   feature persists when it might not be turned on on a given MW site
   or WMF wiki.
3) ease browser testing in CI.

Bug: T344069
Depends-On: If9b83dd559cda2dac315afcb65a4761b9e97f319
Change-Id: Ib0b5ee29ec7accb7b291830d2ab6566fe4f4c0c5
This commit is contained in:
Timo Tijhof 2023-08-09 23:26:09 +01:00 committed by Roan Kattouw
parent 785dd9f89d
commit c7ee0dbf96
11 changed files with 64 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/config-schema.yaml
View file

@ -3215,16 +3215,6 @@ config-schema:
via the `useskin` query parameter. To uninstall a skin, remove its inclusion
from LocalSettings.php.
@see \SkinFactory::getAllowedSkins
ResourceLoaderClientPreferences:
default: false
description: |-
Enable client-side preferences for unregistered users.
This is only supported for unregistered users. For registered users, skins
and extensions must use user preferences (e.g. hidden or API-only options)
and swap class names server-side through the Skin interface.
@warning EXPERIMENTAL!
@since 1.40
@see \MediaWiki\ResourceLoader\ClientHtml
DisableOutputCompression:
default: false
description: 'Disable output compression (enabled by default if zlib is available)'

6
docs/config-vars.php
View file

@ -1975,12 +1975,6 @@ $wgFallbackSkin = null;
*/
$wgSkipSkins = null;
/**
* Config variable stub for the ResourceLoaderClientPreferences setting, for use by phpdoc and IDEs.
* @see MediaWiki\MainConfigSchema::ResourceLoaderClientPreferences
*/
$wgResourceLoaderClientPreferences = null;
/**
* Config variable stub for the DisableOutputCompression setting, for use by phpdoc and IDEs.
* @see MediaWiki\MainConfigSchema::DisableOutputCompression

6
includes/MainConfigNames.php
View file

@ -1990,12 +1990,6 @@ class MainConfigNames {
*/
public const SkipSkins = 'SkipSkins';
/**
* Name constant for the ResourceLoaderClientPreferences setting, for use with Config::get()
* @see MainConfigSchema::ResourceLoaderClientPreferences
*/
public const ResourceLoaderClientPreferences = 'ResourceLoaderClientPreferences';
/**
* Name constant for the DisableOutputCompression setting, for use with Config::get()
* @see MainConfigSchema::DisableOutputCompression

15
includes/MainConfigSchema.php
View file

@ -5163,21 +5163,6 @@ class MainConfigSchema {
'type' => 'map',
];
/**
* Enable client-side preferences for unregistered users.
*
* This is only supported for unregistered users. For registered users, skins
* and extensions must use user preferences (e.g. hidden or API-only options)
* and swap class names server-side through the Skin interface.
*
* @warning EXPERIMENTAL!
* @since 1.40
* @see \MediaWiki\ResourceLoader\ClientHtml
*/
public const ResourceLoaderClientPreferences = [
'default' => false,
];
/**
* Disable output compression (enabled by default if zlib is available)
*/

2
includes/OutputPage.php
View file

@ -3393,7 +3393,7 @@ class OutputPage extends ContextSource {
$config = $this->getConfig();
$clientPrefEnabled = (
$config->get( MainConfigNames::ResourceLoaderClientPreferences ) &&
$this->getSkin()->getOptions()['clientPrefEnabled'] &&
!$this->getUser()->isRegistered()
);
$clientPrefCookiePrefix = $config->get( MainConfigNames::CookiePrefix );

4
includes/ResourceLoader/ClientHtml.php
View file

@ -60,8 +60,8 @@ class ClientHtml {
* @param array $options [optional] Array of options
* - 'target': Parameter for modules=startup request, see StartUpModule.
* - 'safemode': Parameter for modules=startup request, see StartUpModule.
* - 'clientPrefEnabled': See $wgResourceLoaderClientPreferences.
* - 'clientPrefCookiePrefix': See $wgResourceLoaderClientPreferences.
* - 'clientPrefEnabled': See Skin options.
* - 'clientPrefCookiePrefix': See $wgCookiePrefix.
*/
public function __construct( Context $context, array $options = [] ) {
$this->context = $context;

1
includes/config-schema.php
View file

@ -640,7 +640,6 @@ return [
'FallbackSkin' => 'fallback',
'SkipSkins' => [
],
'ResourceLoaderClientPreferences' => false,
'DisableOutputCompression' => false,
'FragmentMode' => [
0 => 'html5',

36
includes/skins/Skin.php
View file

@ -257,8 +257,35 @@ abstract class Skin extends ContextSource {
* When an array is passed:
* - `name`: Internal skin name, generally in lowercase to comply with conventions
* for interface message keys and CSS class names which embed this value.
* - `scripts`: An array of ResourceLoader script modules.
* - `styles`: An array of ResourceLoader style modules to load on all pages.
*
* - `styles`: ResourceLoader style modules to load on all pages. Default: `[]`
*
* - `scripts`: ResourceLoader script modules to load on all pages. Default: `[]`
*
* - `toc`: Whether a table of contents is included in the main article content
* area. If your skin has place a table of contents elsewhere (for example, the sidebar),
* set this to `false`.
*
* See ParserOutput::getText() for the implementation logic.
*
* Default: `true`
*
* - `bodyClasses`: An array of extra class names to add to the HTML `<body>` element.
* Default: `[]`
*
* - `bodyOnly`: Whether the skin is takes control of generating the `<html>`, `<head>` and
* `<body>` elements. This is for SkinTemplate subclasses only. For SkinMustache, this is
* always true and ignored.
*
* Default: `false`
*
* - `clientPrefEnabled`: Enable support for mw.user.clientPrefs.
* This instructs OutputPage and ResourceLoader\ClientHtml to include an inline script
* in web responses for unregistered users to switch HTML classes as needed.
*
* Since: MW 1.41
* Default: `false`
*
* - `responsive`: Whether the skin supports responsive behaviour and wants a viewport meta
* tag to be added to the HTML head. Note, users can disable this feature via a user
* preference.
@ -2343,8 +2370,9 @@ abstract class Skin extends ContextSource {
// the <html>, <head> and <body> tags. For SkinMustache this is always true and
// ignored.
'bodyOnly' => false,
// Does the skin support the temporary user banner?
// If it does the temporary user banner is displayed at the top of the page.
'clientPrefEnabled' => false,
'responsive' => false,
'link' => [],
'tempUserBanner' => false,
'menus' => [
// Legacy keys that are enabled by default for backwards compatibility

1
maintenance/jsduck/categories.json
View file

@ -28,6 +28,7 @@
"mw.storage",
"mw.storage.session",
"mw.user",
"mw.user.clientPrefs",
"mw.util",
"mw.plugin.*",
"mw.cookie",

30
resources/src/mediawiki.user.js
View file

@ -24,6 +24,7 @@
/**
* Save the feature value to the client preferences cookie.
*
* @private
* @param {string} feature
* @param {string} value
*/
@ -45,9 +46,11 @@
}
/**
* Checks if the feature name is composed of valid characters.
* Check if the feature name is composed of valid characters.
*
* A valid feature name may contain letters, numbers, and "-" characters.
*
* @private
* @param {string} value
* @return {boolean}
*/
@ -56,8 +59,9 @@
}
/**
* Checks if the value is composed of valid characters.
* Check if the value is composed of valid characters.
*
* @private
* @param {string} value
* @return {boolean}
*/
@ -311,7 +315,27 @@
},
/**
* Client preferences store's management
* Manage client preferences
*
* For skins that enable the `clientPrefEnabled` option (see Skin class in PHP),
* this feature allows you to store preferences in the browser session that will
* switch one or more the classes on the HTML document.
*
* This is only supported for unregistered users. For registered users, skins
* and extensions must use user preferences (e.g. hidden or API-only options)
* and swap class names server-side through the Skin interface.
*
* This feature is limited to page views by unregistered users. For logged-in requests,
* store preferences in the database instead, via UserOptionsManager or mw.Api#saveOption
* (may be hidden or API-only to exclude from Special:Preferences), and then include the
* desired classes directly in Skin::getHtmlElementAttributes.
*
* Classes toggled by this feature must be named as `<feature>-clientpref-<value>`,
* where `value` contains only alphanumerical characters (a-zA-Z0-9), and `feature`
* can also include hyphens.
*
* @class mw.user.clientPrefs
* @singleton
*/
clientPrefs: {
/**

5
tests/phpunit/includes/ResourceLoader/ClientHtmlTest.php
View file

@ -3,7 +3,6 @@
namespace MediaWiki\Tests\ResourceLoader;
use HashConfig;
use MediaWiki\MainConfigNames;
use MediaWiki\Request\FauxRequest;
use MediaWiki\ResourceLoader\ClientHtml;
use MediaWiki\ResourceLoader\Context;
@ -347,9 +346,7 @@ class ClientHtmlTest extends \PHPUnit\Framework\TestCase {
}
private static function makeContext( $extraQuery = [] ) {
$conf = new HashConfig( [
MainConfigNames::ResourceLoaderClientPreferences => false
] );
$conf = new HashConfig( [] );
return new Context(
new ResourceLoader( $conf, null, null, [
'loadScript' => '/w/load.php',