govuk_navigation_helpers 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4176c900f1ecc9f326253506091426c84a04185
-  data.tar.gz: 1382b484bfbdf27857da344c9eab90ea44f6cecb
+  metadata.gz: ae03499e445926565f940d61ac2ca8a9e6566f40
+  data.tar.gz: e4b3be57785db7c30e2846cb9b2d410d1b3f4309
 SHA512:
-  metadata.gz: 8382fe5f7de451bdba0ca038f1e0a481ede4a19d9e05231178e5c7e2fa166783e11896755ae7c999330760f73c3b5ac0bf6a18b56391f054803d88c467f103a7
-  data.tar.gz: f8862c700764b6e0fea0cc61a6307b5f2661d255ef99ec350620f4233913b0dde4d83d2f996c53ee814c85825d300fb088bc4c95aa8ad365f78766792098d078
+  metadata.gz: 08da4b0086ef29b400da2c05c5b87bbc5219656cefa84fbdf139beefc73e8e150a95ac81c7d4ee08aa412ead50289bff2df652149aa3d8cacb1091d61ce0d5a3
+  data.tar.gz: 3dd946e21c66b799ad1119e2a97a8db3d1cefb3d022e7fc04e6b9542d7d05a409f44d2d429815eaeaab70775738ea8e322fa09a713cda3c927aed34be8916a85

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.0.0
+
+* Functionality to generate data for the related items component
+* Breadcrumbs are now returned in a hash so that they can be passed to
+  `govuk_components` directly.
+
 ## 1.0.0
 
 * Functionality to generate data for the breadcrumb component

data/README.md

@@ -36,7 +36,11 @@ end
 Render the component:
 
 ```ruby
-<%= render partial: 'govuk_component/breadcrumbs', locals: { breadcrumbs: @navigation.breadcrumbs }
+<%= render partial: 'govuk_component/breadcrumbs', locals: @navigation.breadcrumbs %>
+```
+
+```ruby
+<%= render partial: 'govuk_component/related_items', locals: @navigation.related_items %>
 ```
 
 ### Running the test suite
@@ -53,4 +57,4 @@ To run a Yard server locally to preview documentation, run:
 
 ## Licence
 
-    [MIT License](LICENCE.txt)
+[MIT License](LICENCE.txt)

data/govuk_navigation_helpers.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "govuk-lint", "~> 1.2.1"
   spec.add_development_dependency "pry-byebug", "~> 3.4"
   spec.add_development_dependency "yard", "~> 0.8"
-  spec.add_development_dependency "govuk_schemas", "~> 0.1"
+  spec.add_development_dependency "govuk_schemas", "~> 1.0"
 
   spec.required_ruby_version = ">= 2.3.1"
 end

data/lib/govuk_navigation_helpers/breadcrumbs.rb

@@ -20,7 +20,9 @@ module GovukNavigationHelpers
 
       ordered_parents << { title: "Home", url: "/" }
 
-      ordered_parents.reverse
+      {
+        breadcrumbs: ordered_parents.reverse
+      }
     end
 
   private

data/lib/govuk_navigation_helpers/content_item.rb

@@ -0,0 +1,47 @@
+module GovukNavigationHelpers
+  # Simple wrapper around a content store representation of a content item. Works
+  # for both the main content item and the expanded links in the links hash.
+  #
+  # @private
+  class ContentItem
+    attr_reader :content_store_response
+
+    def initialize(content_store_response)
+      @content_store_response = content_store_response
+    end
+
+    def parent
+      parent_item = content_store_response.dig("links", "parent", 0)
+      return unless parent_item
+      ContentItem.new(parent_item)
+    end
+
+    def mainstream_browse_pages
+      content_store_response.dig("links", "mainstream_browse_pages").to_a.map do |link|
+        ContentItem.new(link)
+      end
+    end
+
+    def title
+      content_store_response.fetch("title")
+    end
+
+    def base_path
+      content_store_response.fetch("base_path")
+    end
+
+    def content_id
+      content_store_response.fetch("content_id")
+    end
+
+    def related_links
+      content_store_response.dig("links", "ordered_related_items").to_a.map do |link|
+        ContentItem.new(link)
+      end
+    end
+
+    def external_links
+      content_store_response.dig("details", "external_related_links").to_a
+    end
+  end
+end

data/lib/govuk_navigation_helpers/grouped_related_links.rb

@@ -0,0 +1,47 @@
+module GovukNavigationHelpers
+  # Take a content item and group the related links according to an algorithm
+  # that is intended to display the related links into three groups, depending
+  # on how much they have in common with the main content item.
+  #
+  # @private
+  class GroupedRelatedLinks
+    attr_reader :content_item
+
+    def initialize(content_item)
+      @content_item = content_item
+    end
+
+    # This will return related items that are tagged to the same mainstream
+    # browse page as the main content item.
+    def tagged_to_same_mainstream_browse_page
+      return [] unless content_item.parent
+
+      @tagged_to_same_mainstream_browse_page ||= content_item.related_links.select do |related_item|
+        related_item.mainstream_browse_pages.map(&:content_id).include?(content_item.parent.content_id)
+      end
+    end
+
+    # This will return related items whose parents are tagged to the same mainstream
+    # browse page as the main content item's parent.
+    def parents_tagged_to_same_mainstream_browse_page
+      return [] unless content_item.parent && content_item.parent.parent
+
+      common_parent_content_ids = tagged_to_same_mainstream_browse_page.map(&:content_id)
+
+      @parents_tagged_to_same_mainstream_browse_page ||= content_item.related_links.select do |related_item|
+        next if common_parent_content_ids.include?(related_item.content_id)
+        related_item.mainstream_browse_pages.map(&:parent).map(&:content_id).include?(content_item.parent.parent.content_id)
+      end
+    end
+
+    # This will return related links that are tagged to mainstream browse
+    # pages unrelated to the main content item.
+    def tagged_to_different_mainstream_browse_pages
+      all_content_ids = (tagged_to_same_mainstream_browse_page + parents_tagged_to_same_mainstream_browse_page).map(&:content_id)
+
+      @tagged_to_different_mainstream_browse_pages ||= content_item.related_links.reject do |related_item|
+        all_content_ids.include?(related_item.content_id)
+      end
+    end
+  end
+end

data/lib/govuk_navigation_helpers/related_items.rb

@@ -0,0 +1,92 @@
+require 'govuk_navigation_helpers/grouped_related_links'
+require 'govuk_navigation_helpers/content_item'
+
+module GovukNavigationHelpers
+  # Generate data for the "Related Items" component
+  #
+  # http://govuk-component-guide.herokuapp.com/components/related_items
+  #
+  # The procedure to group the links is quite complicated. In short, related links
+  # are grouped by how related they are to the current page.
+  #
+  # The wiki page on related items has more information:
+  #
+  # https://gov-uk.atlassian.net/wiki/pages/viewpage.action?pageId=99876878
+  class RelatedItems
+    def initialize(content_item)
+      @content_item = ContentItem.new(content_item)
+    end
+
+    def related_items
+      {
+        sections: [
+          tagged_to_same_mainstream_browse_page_section,
+          parents_tagged_to_same_mainstream_browse_page_section,
+          tagged_to_different_mainstream_browse_pages_section,
+          related_external_links_section,
+        ].compact
+      }
+    end
+
+  private
+
+    attr_reader :content_item
+
+    def tagged_to_same_mainstream_browse_page_section
+      return unless grouped.tagged_to_same_mainstream_browse_page.any?
+
+      items = grouped.tagged_to_same_mainstream_browse_page.map do |related_item|
+        {
+          title: related_item.title,
+          url: related_item.base_path
+        }
+      end
+
+      { title: content_item.parent.title, url: content_item.parent.base_path, items: items }
+    end
+
+    def parents_tagged_to_same_mainstream_browse_page_section
+      return unless grouped.parents_tagged_to_same_mainstream_browse_page.any?
+
+      items = grouped.parents_tagged_to_same_mainstream_browse_page.map do |related_item|
+        {
+          title: related_item.title,
+          url: related_item.base_path
+        }
+      end
+
+      { title: content_item.parent.parent.title, url: content_item.parent.parent.base_path, items: items }
+    end
+
+    def tagged_to_different_mainstream_browse_pages_section
+      return unless grouped.tagged_to_different_mainstream_browse_pages.any?
+
+      items = grouped.tagged_to_different_mainstream_browse_pages.map do |related_item|
+        {
+          title: related_item.title,
+          url: related_item.base_path
+        }
+      end
+
+      { title: "Elsewhere on GOV.UK", items: items }
+    end
+
+    def related_external_links_section
+      return unless content_item.external_links.any?
+
+      items = content_item.external_links.map do |h|
+        {
+          title: h.fetch("title"),
+          url: h.fetch("url"),
+          rel: "external"
+        }
+      end
+
+      { title: "Elsewhere on the web", items: items }
+    end
+
+    def grouped
+      @grouped ||= GroupedRelatedLinks.new(content_item)
+    end
+  end
+end

data/lib/govuk_navigation_helpers/version.rb

@@ -1,3 +1,3 @@
 module GovukNavigationHelpers
-  VERSION = "1.0.0".freeze
+  VERSION = "2.0.0".freeze
 end

data/lib/govuk_navigation_helpers.rb

@@ -1,5 +1,6 @@
 require "govuk_navigation_helpers/version"
 require "govuk_navigation_helpers/breadcrumbs"
+require "govuk_navigation_helpers/related_items"
 
 module GovukNavigationHelpers
   class NavigationHelper
@@ -9,11 +10,20 @@ module GovukNavigationHelpers
 
     # Generate a breacrumb trail
     #
-    # @return [Array<Hash>] Each item is a hash containing `:title` and `:url` for one link in the breadcrumb
+    # @return [Hash] Payload for the GOV.UK breadcrumbs component
+    # @see http://govuk-component-guide.herokuapp.com/components/breadcrumbs
     def breadcrumbs
       Breadcrumbs.new(content_item).breadcrumbs
     end
 
+    # Generate a related items payload
+    #
+    # @return [Hash] Payload for the GOV.UK Component
+    # @see http://govuk-component-guide.herokuapp.com/components/related_items
+    def related_items
+      RelatedItems.new(content_item).related_items
+    end
+
   private
 
     attr_reader :content_item

data/spec/breadcrumbs_spec.rb

@@ -1,17 +1,11 @@
 require 'spec_helper'
-require 'govuk_navigation_helpers'
-require 'govuk_schemas'
 
 RSpec.describe GovukNavigationHelpers::Breadcrumbs do
   describe "#breadcrumbs" do
     it "can handle any valid content item" do
       generator = GovukSchemas::RandomExample.for_schema("placeholder", schema_type: "frontend")
 
-      50.times do
-        expect {
-          described_class.new(generator.payload).breadcrumbs
-        }.to_not raise_error
-      end
+      expect { GovukNavigationHelpers::Breadcrumbs.new(generator.payload).breadcrumbs }.to_not raise_error
     end
 
     it "returns the root when parent is not specified" do
@@ -19,7 +13,7 @@ RSpec.describe GovukNavigationHelpers::Breadcrumbs do
       breadcrumbs = breadcrumbs_for(content_item)
 
       expect(breadcrumbs).to eq(
-        [
+        breadcrumbs: [
           { title: "Home", url: "/" },
         ]
       )
@@ -30,7 +24,7 @@ RSpec.describe GovukNavigationHelpers::Breadcrumbs do
       breadcrumbs = breadcrumbs_for(content_item)
 
       expect(breadcrumbs).to eq(
-        [
+        breadcrumbs: [
           { title: "Home", url: "/" },
         ]
       )
@@ -48,7 +42,7 @@ RSpec.describe GovukNavigationHelpers::Breadcrumbs do
       breadcrumbs = breadcrumbs_for(content_item)
 
       expect(breadcrumbs).to eq(
-        [
+        breadcrumbs: [
           { title: "Home", url: "/" },
           { title: "A-parent", url: "/a-parent" }
         ]
@@ -77,7 +71,7 @@ RSpec.describe GovukNavigationHelpers::Breadcrumbs do
       breadcrumbs = breadcrumbs_for(content_item)
 
       expect(breadcrumbs).to eq(
-        [
+        breadcrumbs: [
           { title: "Home", url: "/" },
           { title: "Another-parent", url: "/another-parent" },
           { title: "A-parent", url: "/a-parent" }

data/spec/related_items_spec.rb

@@ -0,0 +1,267 @@
+require "spec_helper"
+
+RSpec.describe GovukNavigationHelpers::RelatedItems do
+  def payload_for(content_item)
+    generator = GovukSchemas::RandomExample.for_schema("placeholder", schema_type: "frontend")
+    fully_valid_content_item = generator.merge_and_validate(content_item)
+    GovukNavigationHelpers::NavigationHelper.new(fully_valid_content_item).related_items
+  end
+
+  describe "#related_items" do
+    it "can handle randomly generated content" do
+      generator = GovukSchemas::RandomExample.for_schema("placeholder", schema_type: "frontend")
+
+      expect { payload_for(generator.payload) }.to_not raise_error
+    end
+
+    it "returns nothing if there are no related links" do
+      nothing = payload_for(
+        "details" => {
+          "external_related_links" => []
+        },
+        "links" => {
+        }
+      )
+
+      expect(nothing).to eql(sections: [])
+    end
+
+    it "returns an elswhere on GOV.UK section for related items with no browse pages in common" do
+      payload = payload_for(
+        "details" => {
+          "external_related_links" => []
+        },
+        "links" => {
+          "ordered_related_items" => [
+            {
+              "title" => "Foo",
+              "content_id" => "fdbf634c-06f5-43ea-915a-53b34b660353",
+              "base_path" => "/foo",
+              "locale" => "en"
+            }
+          ]
+        }
+      )
+
+      expect(payload).to eql(
+        sections: [
+          {
+            title: "Elsewhere on GOV.UK",
+            items: [
+              { title: "Foo", url: "/foo" },
+            ]
+          },
+        ]
+      )
+    end
+
+    it "returns the external related links" do
+      payload = payload_for(
+        "details" => {
+          "external_related_links" => [
+            { "title" => "Foo", "url" => "https://example.org/foo" },
+            { "title" => "Bar", "url" => "https://example.org/bar" }
+          ]
+        },
+        "links" => {
+        }
+      )
+
+      expect(payload).to eql(
+        sections: [
+          {
+            title: "Elsewhere on the web",
+            items: [
+              { title: "Foo", url: "https://example.org/foo", rel: "external" },
+              { title: "Bar", url: "https://example.org/bar", rel: "external" },
+            ]
+          },
+        ]
+      )
+    end
+
+    it "returns a primary section for related items tagged to the same mainstream browse page as the item" do
+      payload = payload_for(
+        "details" => {
+          "external_related_links" => []
+        },
+        "links" => {
+          "parent" => [
+            {
+              "title" => "Foo's parent",
+              "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+              "base_path" => "/foo-parent",
+              "locale" => "en"
+            }
+          ],
+          "ordered_related_items" => [
+            {
+              "content_id" => "9effaabe-346d-4ad0-9c1b-baa49bc084d6",
+              "title" => "Foo",
+              "base_path" => "/bar",
+              "locale" => "en",
+              "links" => {
+                "mainstream_browse_pages" => [
+                  {
+                    "title" => "Foo's parent",
+                    "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+                    "base_path" => "/foo-parent",
+                    "locale" => "en"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      )
+
+      expect(payload).to eql(
+        sections: [
+          {
+            title: "Foo's parent",
+            url: "/foo-parent",
+            items: [
+              { title: "Foo", url: "/bar" },
+            ]
+          },
+        ]
+      )
+    end
+
+    it "returns a secondary section for related items tagged to the same mainstream browse page as the item's parent" do
+      payload = payload_for(
+        "details" => {
+          "external_related_links" => []
+        },
+        "links" => {
+          "parent" => [
+            {
+              "title" => "Foo's parent",
+              "content_id" => "67c28e19-9934-462c-b174-db5b8e566384",
+              "base_path" => "/foo-parent",
+              "locale" => "en",
+              "links" => {
+                "parent" => [
+                  {
+                    "title" => "Foo's grandparent",
+                    "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+                    "base_path" => "/foo-grand-parent",
+                    "locale" => "en",
+                  }
+                ]
+              }
+            }
+          ],
+          "ordered_related_items" => [
+            {
+              "content_id" => "9effaabe-346d-4ad0-9c1b-baa49bc084d6",
+              "title" => "Foo",
+              "base_path" => "/bar",
+              "locale" => "en",
+              "links" => {
+                "mainstream_browse_pages" => [
+                  {
+                    "title" => "Some sibling of foo-parent",
+                    "content_id" => "c34672dc-2ff3-4d28-92fd-bcba382e8a0b",
+                    "base_path" => "/foo-sibling",
+                    "locale" => "en",
+                    "links" => {
+                      "parent" => [
+                        {
+                          "title" => "Foo's grandparent",
+                          "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+                          "base_path" => "/foo-grand-parent",
+                          "locale" => "en",
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      )
+
+      expect(payload).to eql(
+        sections: [
+          {
+            title: "Foo's grandparent",
+            url: "/foo-grand-parent",
+            items: [
+              { title: "Foo", url: "/bar" },
+            ]
+          },
+        ]
+      )
+    end
+
+    it "returns only related items in the primary section where they are tagged to the same mainstream browse pages as both the item and the item's parent" do
+      payload = payload_for(
+        "details" => {
+          "external_related_links" => []
+        },
+        "links" => {
+          "parent" => [
+            {
+              "title" => "Foo's parent",
+              "content_id" => "67c28e19-9934-462c-b174-db5b8e566384",
+              "base_path" => "/foo-parent",
+              "locale" => "en",
+              "links" => {
+                "parent" => [
+                  {
+                    "title" => "Foo's grandparent",
+                    "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+                    "base_path" => "/foo-grand-parent",
+                    "locale" => "en",
+                  }
+                ]
+              }
+            }
+          ],
+          "ordered_related_items" => [
+            {
+              "content_id" => "9effaabe-346d-4ad0-9c1b-baa49bc084d6",
+              "title" => "Foo",
+              "base_path" => "/bar",
+              "locale" => "en",
+              "links" => {
+                "mainstream_browse_pages" => [
+                  {
+                    "title" => "Foo's parent",
+                    "content_id" => "67c28e19-9934-462c-b174-db5b8e566384",
+                    "base_path" => "/foo-parent",
+                    "locale" => "en",
+                    "links" => {
+                      "parent" => [
+                        {
+                          "title" => "Foo's grandparent",
+                          "content_id" => "a9c6f24a-92a1-4ead-a776-532d1d99123c",
+                          "base_path" => "/foo-grand-parent",
+                          "locale" => "en",
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      )
+
+      expect(payload).to eql(
+        sections: [
+          {
+            title: "Foo's parent",
+            url: "/foo-parent",
+            items: [
+              { title: "Foo", url: "/bar" },
+            ]
+          },
+        ]
+      )
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,3 +1,6 @@
+require 'govuk_navigation_helpers'
+require 'govuk_schemas'
+
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
 # The generated `.rspec` file contains `--require spec_helper` which will cause

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_navigation_helpers
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-26 00:00:00.000000000 Z
+date: 2016-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
 description: Gem to transform items from the content-store into payloads for GOV.UK
   components
 email:
@@ -142,8 +142,12 @@ files:
 - jenkins.sh
 - lib/govuk_navigation_helpers.rb
 - lib/govuk_navigation_helpers/breadcrumbs.rb
+- lib/govuk_navigation_helpers/content_item.rb
+- lib/govuk_navigation_helpers/grouped_related_links.rb
+- lib/govuk_navigation_helpers/related_items.rb
 - lib/govuk_navigation_helpers/version.rb
 - spec/breadcrumbs_spec.rb
+- spec/related_items_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/alphagov/govuk_navigation_helpers
 licenses:
@@ -171,4 +175,5 @@ specification_version: 4
 summary: Gem to transform items from the content-store into payloads for GOV.UK components
 test_files:
 - spec/breadcrumbs_spec.rb
+- spec/related_items_spec.rb
 - spec/spec_helper.rb