Merge pull request #2953 from stephaniehobson/BUG-1102508-syntax

Fix Bug 1102508: Link syntaxboxes to Syntax Help Article

media/js/syntax-prism.js

@@ -10,7 +10,7 @@
     var defaultBrush = 'html';
 
     // Treat and highlight PRE elements!
-    $('article pre').each(function() {
+    $('article pre:not(.twopartsyntaxbox):not(.syntaxbox)').each(function() {
         var $pre = $(this);
         var klass = $.trim($pre.attr('class'));
 

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: gettext('How to read CSS syntax.'),
+                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/base/elements/typography.styl

@@ -117,10 +117,11 @@ blockquote {
 
 pre,
 code {
-    font-family: 'Courier New', 'Andale Mono', monospace;
+    font-family: Consolas, Monaco, 'Andale Mono', monospace; /* match Prism */
     margin-bottom: $content-block-margin;
 }
 
+/* pre is a block element so it gets a bit more fancy styling */
 pre {
     set-font-size($base-font-size);
     line-height: 19px;
@@ -130,11 +131,11 @@ pre {
     overflow: auto;
 }
 
+/* code may appear inline in headings, we want to match the font weight of the element its nested in */
 code {
     font-weight: inherit;
 }
 
-
 @media $media-query-mobile {
     h1, h2, h3, h4, h5, h6 {
         code {

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

@@ -1,4 +1,5 @@
 @require 'includes/vars';
+@require 'includes/mixins';
 /*
     Syntax boxes are used for short, non-functional code snippets.
     .syntaxbox is used anywhere (DOM, JS, CSS, ...)
@@ -8,6 +9,7 @@
 pre.syntaxbox,
 pre.twopartsyntaxbox {
     background: $code-block-background-alt-color;
+    @extend $code-block;
 }
 
 pre.twopartsyntaxbox {
@@ -21,3 +23,26 @@ pre.twopartsyntaxbox code[class*="language-"] {
     white-space: pre-line;
 }
 
+.syntaxbox-help {
+    height: 1.2em;
+    float: left;
+    font-size: $larger-font-size;
+    width: 1.1em;
+    margin-left: @width * -1;
+    margin-top: -4px;
+    opacity: 0;
+    overflow: hidden;
+    position: relative;
+    text-align: center;
+
+
+
+    /* show on hover and focus, and when triggered by JS adding class */
+    &.isOpaque,
+    &:hover,
+    &:focus {
+        opacity: 1;
+    }
+}
+
+