govuk_tech_docs 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52f8eae7cd727358efc55feadd52cbbfdfae7e79
-  data.tar.gz: d8268e894f4a7d2c39750fca552f94d3b414e598
+  metadata.gz: d445bcd8c1daf9778f0a3e0d8cb352fab848b46c
+  data.tar.gz: d7fbb83f2f8e7f339033063acb560ad555fae7ce
 SHA512:
-  metadata.gz: ec6710814517280e5a6d9887088802ab45326db1ad60726f8eca1f9bafbf9fa04d127045d3341ce635ce966eb0d8a07b6fd65d603afcf5f7636fb685e2f077a9
-  data.tar.gz: 2584e62bd114d6f6623a5e64685681b3cd8ddd94efa80a0e668f36d531edb747d308066cbaac7e692581612f3a48dff29ff14d13802579dee637dd89edf8b77a
+  metadata.gz: 5708cfb64dd99b8741711fcea030bffbcf81c7da49dfaed23a99215fae6140e07200a390760ff0e2334555787ffc9af191c454be96f74a679d74b93cf2723996
+  data.tar.gz: 42eb4aa9614ae826b2214ebfc4db24aae6c089e1d571986858baf348527382600940b3c7dc80c2fa864477397aca3752a2b8c4972185685f190173fe6ca72988

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.4.0
+
+Adds multiple page navigation support and collapsible top level navigation
+items. When enabled the table of contents will display other pages on the site.
+
+More info:
+- https://github.com/alphagov/tech-docs-gem/pull/27
+
 ## 1.3.1
 
 Minor update to Google Analytics tracking

data/docs/configuration.md

@@ -49,6 +49,22 @@ Example:
 host: https://docs.cloud.service.gov.uk
 ```
 
+## `collapsible_nav`
+
+Enable collapsible navigation in the sidebar. Defaults to false;
+
+```yaml
+collapsible_nav: true
+```
+
+## `multipage_nav`
+
+Enable multipage navigation in the sidebar. Defaults to false;
+
+```yaml
+multipage_nav: true
+```
+
 ## `max_toc_heading_level`
 
 Table of contents depth – how many levels to include in the table of contents. If your ToC is too long, reduce this number and we'll only show higher-level headings.

data/docs/frontmatter.md

@@ -110,6 +110,17 @@ title: My beautiful page
 ---
 ```
 
+## `weight`
+
+Affects the order a page is displayed in the sidebar navigation tree. Lower
+weights float to the top. Higher weights sink to the bottom.
+
+```yaml
+---
+weight: 20
+---
+```
+
 ## `parent`
 
 The page that should be highlighted as ‘active’ in the navigation.

data/example/config/tech-docs.yml

@@ -17,6 +17,12 @@ header_links:
 # Tracking ID from Google Analytics (e.g. UA-XXXX-Y)
 ga_tracking_id:
 
+# Enable multipage navigation in the sidebar
+multipage_nav: true
+
+# Enable collapsible navigation in the sidebar
+collapsible_nav: true
+
 # Table of contents depth – how many levels to include in the table of contents.
 # If your ToC is too long, reduce this number and we'll only show higher-level
 # headings.

data/lib/assets/javascripts/_modules/collapsible-navigation.js

@@ -0,0 +1,93 @@
+(function($, Modules) {
+  'use strict';
+
+  Modules.CollapsibleNavigation = function () {
+
+    var $contentPane;
+    var $nav;
+    var $topLevelItems;
+    var $headings;
+    var $listings;
+
+    var $openLink;
+    var $closeLink;
+
+    this.start = function ($element) {
+      $contentPane = $('.app-pane__content');
+      $nav = $element;
+      $topLevelItems = $nav.find('> ul > li');
+      $headings = $topLevelItems.find('> a');
+      $listings = $topLevelItems.find('> ul');
+
+      // Attach collapsible heading functionality,on mobile and desktop
+      collapsibleHeadings();
+      openActiveHeading();
+      $contentPane.on('scroll', _.debounce(openActiveHeading, 100, { maxWait: 100 }));
+
+    };
+
+    function collapsibleHeadings() {
+      for (var i = $topLevelItems.length - 1; i >= 0; i--) {
+        var $topLevelItem = $($topLevelItems[i]);
+        var $heading = $topLevelItem.find('> a');
+        var $listing = $topLevelItem.find('> ul');
+        // Only add collapsible functionality if there are children.
+        if ($listing.length == 0) {
+          continue;
+        }
+        $topLevelItem.addClass('collapsible');
+        $listing.addClass('collapsible__body')
+        .attr('aria-expanded', 'false');
+        $heading.addClass('collapsible__heading')
+        .after('<button class="collapsible__toggle"><span class="collapsible__toggle-label">Expand ' + $heading.text() + '</span><span class="collapsible__toggle-icon" aria-hidden="true"></button>')
+        $topLevelItem.on('click', '.collapsible__toggle', function(e) {
+          e.preventDefault();
+          var $parent = $(this).parent();
+          toggleHeading($parent);
+        });
+      }
+    }
+
+    function toggleHeading($topLevelItem) {
+      var isOpen = $topLevelItem.hasClass('is-open');
+      var $heading = $topLevelItem.find('> a');
+      var $body = $topLevelItem.find('collapsible__body');
+      var $toggleLabel = $topLevelItem.find('.collapsible__toggle-label');
+
+      $topLevelItem.toggleClass('is-open', !isOpen);
+      $body.attr('aria-expanded', isOpen ? 'true' : 'false');
+      $toggleLabel.text(isOpen ? 'Expand ' + $heading.text() : 'Collapse ' + $heading.text());
+    }
+
+    function openActiveHeading() {
+      var $activeElement;
+      var currentPath = window.location.pathname;
+      var isActiveTrail = '[href*="' + currentPath + '"]';
+      // Add an exception for the root page, as every href includes /
+      if(currentPath == '/') {
+        isActiveTrail = '[href="' + currentPath + window.location.hash + '"]'
+      }
+      for (var i = $topLevelItems.length - 1; i >= 0; i--) {
+        var $element = $($topLevelItems[i]);
+        var $heading = $element.find('> a');
+        // Check if this item href matches
+        if($heading.is(isActiveTrail)) {
+          $activeElement = $element;
+          break;
+        }
+        // Otherwise check the children
+        var $children = $element.find('li > a');
+        var $matchingChildren = $children.filter(isActiveTrail);
+        if ($matchingChildren.length) {
+          $activeElement = $element;
+          break;
+        }
+      }
+      if($activeElement && !$activeElement.hasClass('is-open')) {
+        toggleHeading($activeElement);
+      }
+    }
+
+
+  };
+})(jQuery, window.GOVUK.Modules);

data/lib/assets/javascripts/_modules/in-page-navigation.js

@@ -70,8 +70,12 @@
     }
 
     function highlightActiveItemInToc(fragment) {
-      var $activeTocItem = $tocItems.filter('[href="' + fragment + '"]');
-
+      var $activeTocItem = $tocItems.filter('[href="' + window.location.pathname + fragment + '"]');
+      // Navigation items with children don't contain fragments in their url
+      // Check to see if any nav items contain just the path name.
+      if(!$activeTocItem.get(0)) {
+        $activeTocItem = $tocItems.filter('[href="' + window.location.pathname + '"]');
+      }
       if ($activeTocItem.get(0)) {
         $tocItems.removeClass('toc-link--in-view');
         $activeTocItem.addClass('toc-link--in-view');

data/lib/assets/javascripts/_modules/table-of-contents.js

@@ -4,15 +4,23 @@
   Modules.TableOfContents = function () {
     var $html = $('html');
 
+    var $contentPane;
     var $toc;
     var $tocList;
+    var $topLevelItems;
+    var $headings;
+    var $listings;
 
     var $openLink;
     var $closeLink;
 
     this.start = function ($element) {
+      $contentPane = $('.app-pane__content');
       $toc = $element;
       $tocList = $toc.find('.js-toc-list');
+      $topLevelItems = $tocList.find('> ul > li');
+      $headings = $topLevelItems.find('> a');
+      $listings = $topLevelItems.find('> ul');
 
       // Open link is not inside the module
       $openLink = $html.find('.js-toc-show');
@@ -44,7 +52,7 @@
       // scrolling in that direction will scroll the body 'behind' the table of
       // contents. Fix this by preventing ever reaching the top or bottom of the
       // table of contents (by 1 pixel).
-      // 
+      //
       // http://blog.christoffer.me/six-things-i-learnt-about-ios-safaris-rubber-band-scrolling/
       $toc.on("touchstart.toc", function () {
         var $this = $(this),
@@ -62,7 +70,7 @@
 
     function openNavigation() {
       $html.addClass('toc-open');
-      
+
       toggleBackgroundVisiblity(false);
       updateAriaAttributes();
 

data/lib/assets/javascripts/_start-modules.js

@@ -4,6 +4,7 @@
 //= require _modules/navigation
 //= require _modules/page-expiry
 //= require _modules/table-of-contents
+//= require _modules/collapsible-navigation
 
 $(document).ready(function() {
   GOVUK.modules.start();

data/lib/assets/stylesheets/_core.scss

@@ -30,6 +30,7 @@ $desktop-breakpoint: 992px !default;
 @import "modules/contribution-banner";
 @import "modules/technical-documentation";
 @import "modules/toc";
+@import "modules/collapsible";
 
 @import "accessibility";
 

data/lib/assets/stylesheets/modules/_collapsible.scss

@@ -0,0 +1,45 @@
+// Collapsible JS component styling, made for the navigation tree.
+// These classes are added in table-of-contents.js.
+// They should not be applied without the JS.
+
+.collapsible {
+  position: relative;
+}
+.collapsible__body {
+  display: none;
+  .collapsible.is-open & {
+    display: block
+  }
+}
+.collapsible__toggle {
+  position: absolute;
+  top: 0;
+  right: -25px;
+  width: 50px;
+  height: 40px;
+  overflow: hidden;
+  text-indent: -999em;
+  border: 0;
+  background: 0;
+  color: inherit;
+  padding: 0;
+  &:focus {
+    outline: 3px solid $focus-colour;
+  }
+}
+.collapsible__toggle-icon {
+  position: absolute;
+  top: 0;
+  right: 30px;
+  &::after {
+    content: '';
+    display: block;
+    background: no-repeat file-url('arrow-down.svg') center center;
+    background-size: 18px auto;
+    width: 20px;
+    height: 40px;
+  }
+  .collapsible.is-open &::after {
+    background-image: file-url('arrow-up.svg');
+  }
+}

data/lib/assets/stylesheets/modules/_toc.scss

@@ -27,7 +27,7 @@
 
       a:link, a:visited {
         display: block;
-        padding: 8px $gutter-half;
+        padding: 8px 40px 8px $gutter-half;
         margin: 0 $gutter-half * -1;
         border-left: 5px solid transparent;
 
@@ -46,11 +46,6 @@
       }
 
       @include media(tablet) {
-        // Level 2
-        > ul > li > ul {
-          margin-bottom: 20px;
-        }
-
         // Level 3
         li li li {
           a:link, a:visited {

data/lib/govuk_tech_docs/table_of_contents/heading.rb

@@ -1,10 +1,11 @@
 module GovukTechDocs
   module TableOfContents
     class Heading
-      def initialize(element_name:, text:, attributes:)
+      def initialize(element_name:, text:, attributes:, page_url: '')
         @element_name = element_name
         @text = text
         @attributes = attributes
+        @page_url = page_url
       end
 
       def size
@@ -12,7 +13,7 @@ module GovukTechDocs
       end
 
       def href
-        '#' + @attributes['id']
+        @page_url + '#' + @attributes['id']
       end
 
       def title

data/lib/govuk_tech_docs/table_of_contents/headings_builder.rb

@@ -1,8 +1,9 @@
 module GovukTechDocs
   module TableOfContents
     class HeadingsBuilder
-      def initialize(html)
+      def initialize(html, url)
         @html = html
+        @url = url
       end
 
       def headings
@@ -10,7 +11,8 @@ module GovukTechDocs
           Heading.new(
             element_name: element.node_name,
             text: element.content,
-            attributes: convert_nokogiri_attr_objects_to_hashes(element.attributes)
+            attributes: convert_nokogiri_attr_objects_to_hashes(element.attributes),
+            page_url: @url
           )
         end
       end

data/lib/govuk_tech_docs/table_of_contents/helpers.rb

@@ -7,16 +7,63 @@ require 'govuk_tech_docs/table_of_contents/headings_builder'
 module GovukTechDocs
   module TableOfContents
     module Helpers
-      def table_of_contents(html, max_level: nil)
-        headings = HeadingsBuilder.new(html).headings
+      def single_page_table_of_contents(html, url: '', max_level: nil)
+        headings = HeadingsBuilder.new(html, url).headings
 
         if headings.none? { |heading| heading.size == 1 }
-          raise "No H1 tag found. You have to at least add one H1 heading to the page."
+          raise "No H1 tag found. You have to at least add one H1 heading to the page: " + url
         end
 
         tree = HeadingTreeBuilder.new(headings).tree
         HeadingTreeRenderer.new(tree, max_level: max_level).html
       end
+
+      def multi_page_table_of_contents(resources, current_page, config, current_page_html = nil)
+        # Only parse top level html files
+        # Sorted by weight frontmatter
+        resources = resources
+        .select { |r| r.path.end_with?(".html") && (r.parent.nil? || r.parent.url == "/") }
+        .sort_by { |r| [r.data.weight ? 0 : 1, r.data.weight || 0] }
+
+        render_page_tree(resources, current_page, config, current_page_html)
+      end
+
+      def render_page_tree(resources, current_page, config, current_page_html)
+        # Sort by weight frontmatter
+        resources = resources
+        .sort_by { |r| [r.data.weight ? 0 : 1, r.data.weight || 0] }
+        output = '';
+        resources.each do |resource|
+          # Reuse the generated content for the active page
+          # If we generate it twice it increments the heading ids
+          content =
+            if current_page.url == resource.url && current_page_html
+              current_page_html
+            else
+              resource.render(layout: false)
+            end
+          # Avoid redirect pages
+          next if content.include? "http-equiv=refresh"
+          # If this page has children, just print the title and recursively
+          # render the children.
+          # If not, print the heading structure.
+          # We avoid printing the children of the root index.html as it is the
+          # parent of every other top level file.
+          if resource.children.any? && resource.url != "/"
+            output += %{<ul><li><a href="#{resource.url}">#{resource.data.title}</a>\n}
+            output += render_page_tree(resource.children, current_page, config, current_page_html)
+            output += '</li></ul>'
+          else
+            output +=
+              single_page_table_of_contents(
+                content,
+                url: resource.url,
+                max_level: config[:tech_docs][:max_toc_heading_level]
+              )
+          end
+        end
+        output
+      end
     end
   end
 end

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "1.3.1".freeze
+  VERSION = "1.4.0".freeze
 end

data/lib/source/images/arrow-down.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 22.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 34 34" style="enable-background:new 0 0 34 34;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#0B0C0C;}
+</style>
+<polygon class="st0" points="17,25.7 1.6,11.5 4.4,8.5 17,20.3 29.6,8.5 32.4,11.5 "/>
+</svg>

data/lib/source/images/arrow-up.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 22.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 34 34" style="enable-background:new 0 0 34 34;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#0B0C0C;}
+</style>
+<polygon class="st0" points="29.6,25.5 17,13.7 4.4,25.5 1.6,22.5 17,8.3 32.4,22.5 "/>
+</svg>

data/lib/source/layouts/core.erb

@@ -45,7 +45,7 @@
         <div class="app-pane__toc">
           <div class="toc" data-module="table-of-contents">
             <a href="#" class="toc__close js-toc-close" aria-controls="toc" aria-label="Hide table of contents"></a>
-            <nav id="toc" class="js-toc-list toc__list" aria-labelledby="toc-heading">
+            <nav id="toc" class="js-toc-list toc__list" aria-labelledby="toc-heading"<%= " data-module=\"collapsible-navigation\"" if config[:tech_docs][:collapsible_nav] %>>
               <%= yield_content :sidebar %>
             </nav>
           </div>

data/lib/source/layouts/layout.erb

@@ -5,10 +5,12 @@ wrap_layout :core do
   content_for(:toc_module, "in-page-navigation")
 
   content_for :sidebar do
-    table_of_contents(
-      html,
-      max_level: config[:tech_docs][:max_toc_heading_level]
-    )
+    if config[:tech_docs][:multipage_nav] %>
+      <%= multi_page_table_of_contents(sitemap.resources, current_page, config, html) %>
+    <% else %>
+      <%= single_page_table_of_contents(html, max_level: config[:tech_docs][:max_toc_heading_level]) %>
+    <% end %>
+  <%
   end
 
   html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_tech_docs
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-21 00:00:00.000000000 Z
+date: 2018-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -280,6 +280,7 @@ files:
 - lib/assets/javascripts/_analytics.js
 - lib/assets/javascripts/_govuk/modules.js
 - lib/assets/javascripts/_modules/anchored-headings.js
+- lib/assets/javascripts/_modules/collapsible-navigation.js
 - lib/assets/javascripts/_modules/in-page-navigation.js
 - lib/assets/javascripts/_modules/navigation.js
 - lib/assets/javascripts/_modules/page-expiry.js
@@ -314,6 +315,7 @@ files:
 - lib/assets/stylesheets/govuk_frontend_toolkit/design-patterns/_media-player.scss
 - lib/assets/stylesheets/modules/_anchored-heading.scss
 - lib/assets/stylesheets/modules/_app-pane.scss
+- lib/assets/stylesheets/modules/_collapsible.scss
 - lib/assets/stylesheets/modules/_contribution-banner.scss
 - lib/assets/stylesheets/modules/_footer.scss
 - lib/assets/stylesheets/modules/_govuk-logo.scss
@@ -347,6 +349,8 @@ files:
 - lib/source/favicon.ico
 - lib/source/images/anchored-heading-icon-2x.png
 - lib/source/images/anchored-heading-icon.png
+- lib/source/images/arrow-down.svg
+- lib/source/images/arrow-up.svg
 - lib/source/images/gov.uk_logotype_crown-2x.png
 - lib/source/images/gov.uk_logotype_crown.png
 - lib/source/images/gov.uk_logotype_crown_invert_trans.png