[Mediawiki-l] Skin system new features, changes (1.18): Autoloading, Legacy skins, RequestContext, Relevant Users and Titles, Login/createaccount links, content_navigation, BaseTemplate, and more... (+1.19 preview)

[Daniel Friesen]

The format of $wgValidSkinNames has been changed. Previously it had been
`$wgValidSkinNames[key] = name;` but now it's `$wgValidSkinNames[key] =
ClassNamePostfix;`
In essence the code that creates a skin class has now been changed to
try to create a class named "Skin{$wgValidSkinNames[$key]}".
This change is because of a bug with skins that are autoloaded.
Previously when you defined a skin like `$wgValidSkinNames["bluebook"] =
"BlueBook";` MW would try to load SkinBluebook rather than SkinBlueBook.
This worked in core because we didn't autoload skins and instead did a
`require_once( "{$wgStyleDirectory}/{$wgValidSkinNames[$key]}.php" );`,
because php's class system is case-insensitive SkinMonoBook always
loaded fine, however this wasn't the case for extension based skins
which used our case-sensitive autoloader.
Keep this in mind when making autoloaded skins if you want pre-1.18
compatibility you may have to add two autoloader lines, one for
SkinBlueBook and another for SkinBluebook.

Legacy skins are depreciated. The old skin system inside 'Skin' that
powered the old skins CologneBlue, Nostalgia, and Standard/Classic has
been dropped and replaced by a deprecated SkinLegacy system based mostly
on SkinTemplate. New skins should all be SkinTemplate based, SkinLegacy
only exists to support the 3 core skins that were ported, it may be
eliminated from core in the near future along with the legacy skins.
Note that this means a lot of methods like Skin::editThisPage() that
were never meant to be used by SkinTemplate are no longer available, if
you used $sk-> methods check over your skin to make sure it's not
throwing errors because you were using outdated methods.

We now have a context system, if building a skin for 1.18+ please ensure
that you use ->getUser(), ->getLang(), ->getRequest(), and
->getOutput(), instead of $wgUser, $wgLang, $wgRequest, and $wgOut.

The linker is now static, skins wishing to use linker methods should
migrate away from calling them on $sk-> and use Linker:: properly.
Note that doEditSectionLink is now explicitly part of Skin, it's no
longer a Linker method, if you're using it take note of that. As a
result of this and some parser changes skins can now customize the
editsection link within their own skin by overloading the
doEditSectionLink method. Note that if you did this before 1.18 you
would pollute the cache and end up with other skins having your
customizations sometimes, and your skin losing it's customization
sometime. Make note of that if you override doeEditSectionLink as you
may want to include a conditional to leave it alone if your skin is used
in a release before 1.18.

We have two new pieces of information for skin, a relevant title and
relevant user. Relevant title is used when doing things like generating
tabs, special pages like Special:Movepage use it to make skins display
the tabs for pages they are relevant to instead of making them suddenly
disappear on the user (1.19 or later may have a more robust way of
handling tabs though). Relevant user is similar, pages like
Special:Contributions use it so things like the block link in the
toolbar are the same as when visiting a userpage.

The specialpageattributes key is no longer needed in your skin if it's
meant for 1.18+, there's better code in core now handling lang/dir for
the body.

The printfooter and debughtml have been pulled out of bodytext and are
now in separate printfooter and debughtml keys (I think I need to make
not of that in my own skins).
((I have some issues with this change (not mine), the situation may
change a little before release if I try to backport something))

The "Login / create account" link can now be split into two separate
"Login" and "Create account" links by user configuration using
$wgUseCombinedLoginLink. For now it defaults to the same behavior as
before. Skins which have a reason to need one behavior or another (eg:
turning the links into buttons and wanting to make sure they're both
there) can override the useCombinedLoginLink method and return either
true (combined) or false (split) to override the configuration.

A great one now. Sort of replacing content_actions we have a new
content_navigation tplkey. The Vector code generating it's own
hierarchical content_actions has been pulled out of vector and merged
into SkinTemplate, any skin that wants to take advantage of the better
organized namespace/variants/views/actions categorization of our tabs
can now use content_navigation to take advantage of them. Skins using
content_actions will still work, the content_actions array is created
based on content_navigation now, the content_navigation arrays are
annotated with information like 'primary' (vector uses this to stop
collapsing of tabs into the menu on small screens) and 'redundant' for
tabs like 'read' which tells the content_actions code that the tab is
redundant and shouldn't be included in content_actions.
Extensions which used SkinTemplateTabs and didn't add a
SkinTemplateNavigation hook will stop working as the
SkinTemplateNavigation hook has completely replaced SkinTemplateTabs
(ok, I admit I think there's an old SkinLegacy hack that still uses
SkinTemplateTabs for the tabs in legacy code). Extensions that had
issues with vector's code not including replacements for the
SkinTemplateBuildContentActionUrlsAfterSpecialPage and
SkinTemplateContentActions hooks will be happy to know that
content_actions now has equivalent replacement hooks
SkinTemplateNavigation::SpecialPage and
SkinTemplateNavigation::Universal which you can add. If you use these
hooks in new code, and don't need pre-1.18-non-vector compat, and aren't
worrying about SkinLegacy still using a SkinTemplateTabs hack you don't
need to include the old hooks since content_actions is extracted from
content_navigation.

There is new message fallback code in the i18n system. Many of the
messages for tabs like 'move' can be overridden per-skin with messages
like 'vector-action-move', 'modern-action-move', etc... If not defined
they will fallback to the normal message. Vector had some message
customizations before because of changes from monobook in how it handled
tabs so this was added so we'd have a way to keep those without doing it
in an ugly hacky way. Other skins can now include similar customizations
and individual wiki can include per-skin message overrides if there are
things like the edit button you want to customize the message for but
have an issue where it looks fine in one skin but messes up the
intuitiveness of another.

Skin QuickTemplates now have a $this->getSkin() method they can use
instead of fumbling around with $this->data['skin'].

We have a new BaseTemplate class that extends QuickTemplate, it includes
a number of helpers for skins and you can start to take advantage of
them in a 1.18 skin by extending from BaseTemplate instead of directly
from QuickTemplate.
This can kill a lot of ugly boilerplate from skins like the huge
boilerplate for personal_urls and content_{actions,navigation}. Links
and list items for many of the common tpl key arrays we have (ie:
content_{actions,navigation}, etc...) where there are arrays like
personal_urls that aren't in a format these helpers can handle we have
helpers like getPersonalTools that will give you an array in the right
format. The search input and search button have helpers to simplify them
too (I couldn't come up with a good helper for the search form opening
code though). You can replace the mess of bottomscripts, reporttime, and
debug trail in your skin now with a simple `$this->printTrail();`. And
those remembering my footerlinks and footericons code just introduced in
1.17 will be happy to know there are helpers here to simplify the
boilerplate for those. Also that horrible ugly massive boilerplate for
the toolbox you have to copy into any skin, we now have a getToolbox
helper that returns an array that will work with the mageListItem
helper, it also has a new hook BaseTemplateToolbox that will work on
that rather than have you output raw html not customized by skin. So
please do start using it in skins, it would be nice to deprecate those
html hooks and have extensions stop using them.
----
1.19 is in active development so there isn't much added yet, but I do
have a nice quick note on what is in there now.

Vector contains a pile of css for content styling which was basically
copied from Monobook and modified slightly. That css has now been
stripped out and put into three stylesheets in common/:
commonElements.css: This stylesheet contains all your basic elements;
Paragraphs, Links, Headers, etc... If you want anything from the common
styles you'll want this at least.
commonContent.css: This stylesheet contains more complex things which
are contained within the content area, right now it contains things like
the TOC and the frames that are wrapped around images. These are things
you might not want default styles for in your skin and might want to
customize in ways that having pre-existing styles could get in the way
of (it's easier to override simple styles by commonElements than it is
do undo the styling of the entire toc for example).
commonInterface.css: This stylesheet contains some extra common stuff
between MonoBook and Vector. These are tied to patterns in ids and
classes for things like the usermessage, catlinks, etc... which are
outside of the bodytext and the skin may decide on the ids and classes
for. If you're making a skin that sticks with the MonoBook/Vector
patterns of laying out and id/classing the content area you can include
this stylesheet to get some of the common styles.
There are a few notes on opting-in to this in your skins:
- I haven't figured out how to deal with the icons for external links
(the https, audio, etc... icons) yet, MonoBook and Vector use different
icons so while the pattern is common the images aren't. So they aren't
actually the same stylesheet wise. This may end up as a separate to
include stylesheet later on.
- When opting in you'll need to add a class="mw-body" somewhere into
your skin to define the area where content css stylings for things like
links will apply. In MonoBook this is on the same element as
#bodyContent and in Vector it's #content.
- To use these stylesheets include them into your ResourceLoader
'styles' array, that way it all gets combined into a single css file for
your skin.
-- I didn't make this a separate module because we include
&skin=skinname into the /load.php call, that means that even if I make
these modules they aren't reused between different skins. Hence there is
no value in having them in a separate module and it's better to include
them in the skin's own module where they'll be combined into a single
css file.
- With link styles and one or two minor changes from MonoBook to Vector
the Vector difference was preferred since Vector has replaced MonoBook,
MonoBook is now essentially outdated, and new skins will likely be
Vector based rather than MonoBook based. If you want things to look a
little more old and monobook like you may want to add some overriding
css in your own styles like the rules that monobook adds in it's own css
for links.
- MonoBook and Vector use different bullet images for ul {}, since
they're embedded images and would end up inlined in skins that might
override them I opted out of including them in the elements stylesheet.
If you want a list bullet image you'll have to embed one into your own
stylesheet. We have an old .gif that looks like the one in MonoBook
inside common, but the Vector one right now is only in vector. Though I
may contemplate moving that to common.

-- 
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]