From: MatmaRex Date: Mon, 22 Oct 2012 18:59:44 +0000 (+0200) Subject: (bug 1) document Skin::buildSidebar per own experience X-Git-Tag: 1.31.0-rc.0~21838^2 X-Git-Url: http://git.cyclocoop.org/url?a=commitdiff_plain;h=3ff74619893384cc5d53f2c5dbd4c3a1f95065fa;p=lhc%2Fweb%2Fwiklou.git (bug 1) document Skin::buildSidebar per own experience Lessons learned from CologneBlue rewrite and bug 40857. Change-Id: If56df0a7ce20bc8f7a73252d06baf97264793069 --- diff --git a/includes/Skin.php b/includes/Skin.php index 24d48bc44c..94845b79c9 100644 --- a/includes/Skin.php +++ b/includes/Skin.php @@ -1132,7 +1132,23 @@ abstract class Skin extends ContextSource { } /** - * Build an array that represents the sidebar(s), the navigation bar among them + * Build an array that represents the sidebar(s), the navigation bar among them. + * + * BaseTemplate::getSidebar can be used to simplify the format and id generation in new skins. + * + * The format of the returned array is array( heading => content, ... ), where: + * - heading is the heading of a navigation portlet. It is either: + * - magic string to be handled by the skins ('SEARCH' / 'LANGUAGES' / 'TOOLBOX' / ...) + * - a message name (e.g. 'navigation'), the message should be HTML-escaped by the skin + * - plain text, which should be HTML-escaped by the skin + * - content is the contents of the portlet. It is either: + * - HTML text () + * - array of link data in a format accepted by BaseTemplate::makeListItem() + * - (for a magic string as a key, any value) + * + * Note that extensions can control the sidebar contents using the SkinBuildSidebar hook + * and can technically insert anything in here; skin creators are expected to handle + * values described above. * * @return array */