Fix Bug 1102508: Link Syntax to Syntax Help Article

Added javascript to detect syntaxbox and twopartsyntaxbox and create a link to help articles based on if there is a CSS class identifying the language, falling back to the language the section is in if there is not.

Added CSS to style the link.

media/redesign/js/wiki.js

@@ -188,6 +188,108 @@
         doc.body.appendChild(syntaxScript);
     })();
 
+    /*
+        Add link to syntax explanations
+    */
+    (function(){
+        // possible syntax languages and links to resources for reading them
+        var syntaxSections = {
+            css:  {
+                link: 'docs/Web/CSS/Value_definition_syntax',
+                title: 'How to read CSS syntax.', // how do I localize this
+                urlTest: '/docs/Web/CSS/',
+                classTest: 'brush:css'
+            },
+            /* these languages do not have syntax articles yet but it's important
+                to have the classTest and section tests available when deciding
+                if there is a matching language for the purposes of creating the
+                link, adding a link and title later will cause them to be linked */
+            html: {
+                urlTest: '/docs/Web/HTML/',
+                classTest: 'brush:html'
+            },
+            js: {
+                urlTest: '/docs/Web/JavaScript/',
+                classTest: 'brush:js'
+            },
+            api: {
+                urlTest: '/docs/Web/API/',
+                classTest: 'brush:js'
+            }
+        };
+
+        // check if there is any syntax on the page to add links to
+        var $boxes = $('.syntaxbox, .twopartsyntaxbox');
+
+        if($boxes.length) {
+            /* run the section and page matching logic
+               - isLinkMatch becomes true if we're already on one of the syntax articles
+               - sectionMatch becomes the link to a wiki article if we're in a section of
+                 the site that has a matching wiki syntax article
+             */
+            var isLinkMatch = false;
+            var sectionMatch;
+            for (var section in syntaxSections) {
+                var sectionLink = syntaxSections[section].link;
+                var sectionTest = syntaxSections[section].urlTest;
+                if(window.location.href.indexOf(sectionLink) > -1) {
+                    isLinkMatch = true;
+                }
+                if(window.location.href.indexOf(sectionTest) > -1) {
+                    sectionMatch = syntaxSections[section];
+                }
+            }
+
+            // if we're not already reading an article on syntax...
+            if(!isLinkMatch){
+                // loop through boxes
+                $boxes.each(function() {
+                    var $thisBox = $(this);
+
+                    // determine language
+                    var syntaxLanguage;
+
+                    // pick CSS if it has class twopartsyntaxbox, this should only ever have CSS in it
+                    if($thisBox.hasClass('twopartsyntaxbox')) {
+                        syntaxLanguage = syntaxSections.css;
+                    }
+
+                    // check if there is a class on the box matching a language (sets to last match)
+                    // overrides .twopartsyntaxbox, that's good
+                    for (var section in syntaxSections) {
+                        var classTest = syntaxSections[section].classTest;
+                        if($thisBox.hasClass(classTest)) {
+                            syntaxLanguage = syntaxSections[section];
+                        }
+                    }
+
+                    // if we still don't have a match fall back to the language the section is in
+                    if (!syntaxLanguage && sectionMatch) {
+                        syntaxLanguage = sectionMatch;
+                    }
+
+                    // check we have identified matching help text and links
+                    if(syntaxLanguage) {
+                        // check that we have the objects we need to add the help text for this language
+                        if(syntaxLanguage.link && syntaxLanguage.title) {
+                            var syntaxLink = syntaxLanguage.link;
+                            var syntaxTitle = syntaxLanguage.title;
+
+                            // add the help text and link to the page
+                            var $helpLink = $('<a href="' + syntaxLink + '" class="syntaxbox-help icon-only" lang="en"><i aria-hidden="true" class="icon-question-sign"></i><span>' + syntaxTitle + '</span></a>');
+                            $thisBox.before($helpLink);
+
+                            // show help text on mouseover (CSS handles focus)
+                            $thisBox.on('mouseenter', function(){$helpLink.addClass('isOpaque');});
+                            $thisBox.on('mouseleave', function(){$helpLink.removeClass('isOpaque');});
+                        }
+                    }
+                });
+            }
+        }
+    })();
+
+
     /*
         Set up the scrolling TOC effect
     */

media/redesign/stylus/wiki-syntax-syntaxbox.styl

@@ -21,3 +21,24 @@ pre.twopartsyntaxbox code[class*="language-"] {
     white-space: pre-line;
 }
 
+.syntaxbox-help {
+    height: 1.2em;
+    float: left;
+    font-size: $larger-font-size;
+    margin-left: -1.1em; /* width of icon */
+    margin-top: -4px;
+    opacity: 0;
+    overflow: hidden;
+    position: relative;
+    text-align: center;
+    width: 1.1em;
+
+    &.isOpaque,
+    &:hover,
+    &:focus {
+        opacity: 1;
+    }
+}
+
+/* show on hover */
+/* show when tabbed to, make focusable */