Customization:Explaining skins

From Meta, a Wikimedia project coordination wiki
Annotated Wikipedia Vector skin interface (logged-out)

A quick explanation of what a 'Skin' really is[edit]

A 'Skin' in MediaWiki is a PHP class containing functions (or methods) designed to gather the information needed to generate the HTML that your browser displays for each page in the wiki.

Each skin exists as a separate class that extends the parent 'Skin' class. In other words, each individual skin inherits all methods found in the main 'Skin' class, and may define additional methods specific to that skin needed to draw the page.

How this is applied in MediaWiki[edit]

In version 1.3 of MediaWiki, the includes directory defines 4 different types of class which extend Skin; SkinCologneBlue, SkinNostalgia, SkinStandard and SkinPHPTal. 4 classes then extend SkinPHPTal; SkinDaVinci, SkinMono, SkinMonoBook and SkinMySkin, although SkinDaVinci and SkinMono are not avaliable in the list of validSkinNames defined at the start of Skin.php.

SkinPHPTal uses the PHPTAL library to generate pages using the TAL defined in the xhtml_slim.pt page in the templates directory, but in each of the defined subclasses, a different style sheet is used to change the look and feel. The classes not inherited from SkinPHPTal all generate their output directly in the traditional way.

In version 1.4 of MediaWiki, things have changed somewhat, and a new Class has appeared called SkinTemplate, which inherits from Skin. SkinDaVinci and SkinMono are gone and a few new disabled classes have appeared; SkinMonoBookTal, SkinAmethyst, SkinChick and SkinWikimediawiki. SkinMonoBook now extends SkinTemplate instead of SkinPHPTal, although SkinTemplate is almost identical to the old SkinPHPTal file.

At a quick glance, the idea now is that SkinTemplate is a class where the process of interpreting the contents of the TAL xhtml_slim.pt page have been replaced by a generated PHP page. This means that the TAL page needs only be interpreted once, rather than every time a page is to be displayed.

How the skins lay out the page[edit]

The original means of generating the output page used a large table. The function central to this is outputPage which generates the HTML using 3 primary functions, headElement, beforeContent and afterContent, and the class variable mBodytext. The afterContent function calls the quickBar function which generates the quickbar menu, which is enclosed in a div block with an id "quickbar".

A new means of generating the HTML pages has been implemented using PHPTal. This involves a PHPTal specification file, in xhtml format, where HTML tags are marked with attributes which indicate to a parser how it can manipulate the contents of the file to end up with a page still in the original template. In version 1.3.10 the SkinPHPTal class extends Skin, and the outputPage function simply sets up variables in the PHPTal object, then runs the parser. In version 1.4beta6 this has moved to SkinTemplate. I've not looked at this in depth, but I believe some of the PHPTal interpretive code has been rewritten so as to have the same effect by simply calling code that is now in the skins directory.

How the stylesheet controls the new layout[edit]

The new template HTML page template consists of a number of div sections that are each identified by either or both of an id and class attribute in the div tag, but contain data. The stylesheet then controls how each div block is drawn and where on the page it is positioned.

Major style blocks by name[edit]

The following are important identifiers in the stylesheet.

  • column-one contains p-personal, p-logo, p-cactions, p-navigation, p-search and p-tb (the toolbox)
    • column-one also controls the amount of space between the main logo and first portlet, p-navigation (navigation box), in the left side column.[1]
  • column-content overall space within the margins of which the content exists. Column-content contains the blocks:
    • content, the white background, thin bordered box which contains the main page content.
    • firstHeading, the heading tag at the top of every page
    • bodyContent contains the main page content within the content box, and
    • contentSub block contains the message telling the user where he has been redirected from to the current page
  • siteSub defines the style of text which would indicate the name of the wiki immediately underneath the main heading, but above the body text
  • visualClear CSS style which creates a clear break across the screen. <br style="clear:both" /> [2]

Portlets[edit]

The portlet class is the style used by all the div blocks for the main content. The following are blocks use the portlet class.

Left:
p-logo block
p-search block
p-navigation default link block, edited at MediaWiki:Sidebar.
p-tb default toolbox block, →MediaWiki:Sidebar.
Top:
p-cactions edit block
p-personal user's block
  • mw-js-message (optional, for displaying notifications sent to the current user)
  • siteNotice (optional, includes the centralNotice for global notifications across wikis)
  • firstHeading: Page name
  • The wiki code editor, or the VisualEditor (only when editing pages)
  • bodyContent: actual content of the page or preview when editing pages
    • siteSub: From Name of the Wiki (may be hidden)
    • contentSub: Page content (or preview and diffs in the wiki code editor)
    • Sorted list of pages or subcategories categorized in the current category (only in category pages)
    • Categories of the current page

Footer: Last modification date
Licencing info
Links to Privacy policy, About this wiki, Warnings, Developers space, Mobile version, and logos of Wikimedia Foundation and Powered by MediaWiki

If the name of the section is changed by editing that page, then the corresponding CSS ID is also changed and your CSS will no longer apply unless you change the corresponding section in the style sheet. Example: if you edit MediaWiki:Sidebar to change the word 'navigation' to 'navigating', the section is now ID'd '#p-navigating'

To further complicate the issue, the Sidebar can even be split into multiple blocks based upon the structuring of MediaWiki:Sidebar. Each of these blocks will have separate CSS IDs.

Section names containing characters which are not allowed in an id get pseudo-UTF-8-encoded in the same way as section names in the content, with a . before each hexadecimal number; for example, the if the name is navigáció, the id will be p-navig.C3.A1ci.C3.B3 The dot has a special meaning in CSS selectors, so if you want to use such an id, you have to escape it like this: #p-navig\.C3\.A1ci\.C3\.B3

Footer[edit]

The footer at the bottom of the page includes blocks with the following ids:

  • footer is the entire footer block
  • w-poweredbyico is the powered by mediawiki image that normally resides to the right of the page
  • f-list is the id for the list that contains all the bits of text at the bottom of the page.

CSS Code[edit]

  • float: none !important: The float property sets where an image or a text will appear in another element.[3]
    • Values: left, right, none
  • inline-block: Vertical alignment of several fields.
  • overflow: visible: The overflow declaration tells the browser what to do with content that doesn't fit in a box.
    • overflow: hidden: the overflowing content is completely hidden, not accessible to the user.
    • overflow: visible: the content flows out of the box.[4]
  • padding-bottom: The padding-bottom property sets the bottom padding (space) of an element.
    • Negative values are not allowed.[5]
  • ul: Bullet lists in HTML come in 2 varieties:
    • Ordered lists in which line begins with a number
    • Unordered lists each lines begin with the same bullet or image.
  • z-index: The z-index property sets the stack order of an element. An element with greater stack order is always in front of another element with lower stack order.
    • Elements can have negative stack orders.
    • Z-index only works on elements that have been positioned (e.g. position:absolute;)[6] [7]

Notes[edit]

See also[edit]

External links[edit]