Add department colours to components

CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+
+* Add department colours to components (PR #296)
+
 # 7.1.0
 
 * Add subscription links component (PR #290)

app/assets/stylesheets/govuk_publishing_components/_all_components.scss

@@ -7,6 +7,8 @@
 @import "typography";
 @import "colours";
 
+@import "components/helpers/organisation-colours";
+
 @import "components/back-link";
 @import "components/button";
 @import "components/document-list";

app/assets/stylesheets/govuk_publishing_components/components/helpers/_organisation-colours.scss

@@ -0,0 +1,20 @@
+@import "colours/organisation";
+
+// this uses the colours from govuk_frontend_toolkit
+// https://github.com/alphagov/govuk_frontend_toolkit/blob/master/stylesheets/colours/_organisation.scss
+
+@mixin organisation-brand-colour() {
+  @each $organisation in $all-organisation-brand-colours {
+    .brand--#{nth($organisation, 1)} {
+      .brand__color {
+        color: nth($organisation, 3);
+      }
+
+      .brand__border-color {
+        border-color: nth($organisation, 2);
+      }
+    }
+  }
+}
+
+@include organisation-brand-colour;

app/views/govuk_publishing_components/components/_document_list.html.erb

@@ -2,17 +2,21 @@
   items ||= []
   margin_top_class = " gem-c-document-list--top-margin" if local_assigns[:margin_top]
   margin_bottom_class = " gem-c-document-list--bottom-margin" if local_assigns[:margin_bottom]
+
+  brand ||= false
+  brand_helper = GovukPublishingComponents::Presenters::BrandHelper.new(brand)
 %>
 <% if items.any? %>
-  <ol class="gem-c-document-list<%= margin_bottom_class %><%= margin_top_class %>">
+  <ol class="gem-c-document-list<%= margin_bottom_class %><%= margin_top_class %> <%= brand_helper.get_brand %>">
     <% items.each do |item| %>
       <li class="gem-c-document-list__item">
         <h3 class="gem-c-document-list__item-title">
           <%=
             link_to(
               item[:link][:text],
               item[:link][:path],
-              data: item[:link][:data_attributes]
+              data: item[:link][:data_attributes],
+              class: brand_helper.get_brand_element("color")
             )
           %>
         </h3>

app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -76,3 +76,20 @@ examples:
           text: 'Become an apprentice'
           path: '/become-an-apprentice'
           description: 'Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.'
+  with_branding:
+    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/master/docs/component_branding.md) for more details.
+    data:
+      brand: 'attorney-generals-office'
+      items:
+      - link:
+          text: 'School behaviour and attendance: parental responsibility measures'
+          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
+        metadata:
+          public_updated_at: 2017-01-05 14:50:33
+          document_type: 'Statutory guidance'
+      - link:
+          text: 'School exclusion'
+          path: '/government/publications/school-exclusion'
+        metadata:
+          public_updated_at: 2017-07-19 15:01:48
+          document_type: 'Statutory guidance'

docs/component_branding.md

@@ -0,0 +1,47 @@
+# Component branding
+
+## Overview
+
+Organisation pages in whitehall ([example](https://www.gov.uk/government/organisations/attorney-generals-office)) have department-specific branding on them. This includes specific colours for links and borders. These pages are being migrated out of whitehall and will use components for their frontend, which means some components need a sensible way of displaying these colours.
+
+This work follows [this RFC](https://github.com/alphagov/govuk_publishing_components/pull/287) to discuss the approach taken.
+
+## Adding to a component
+
+To add colours to a component, modify the component to follow the example below.
+
+```
+<%
+  brand ||= false
+  brand_helper = GovukPublishingComponents::Presenters::BrandHelper.new(brand)
+%>
+
+<div class="gem-c-component <%= brand_helper.get_brand %>">
+  <div class="gem-c-component__title <%= brand_helper.get_brand_element("border-color") %>">
+    Example element that requires a coloured border
+  </div>
+
+  <a href="#" class="<%= brand_helper.get_brand_element("color") %>">
+    Example element that requires coloured text
+  </a>
+</div>
+```
+
+Note that the helper must be called for each element that needs a border or link colour applying. This allows for flexibility if one is required but not the other.
+
+For borders, the applied class only adds a `border-color` attribute. You will need to add the rest of the border style attributes to the component itself, for example:
+
+```
+.gem-c-component__title {
+  border-style: solid;
+  border-width: 5px;
+}
+```
+
+The component can then be passed a string matching the required brand, for example:
+
+```
+<%= render "govuk_publishing_components/components/example-component", {
+  brand: 'attorney-generals-office'
+} %>
+```

lib/govuk_publishing_components.rb

@@ -1,5 +1,6 @@
 require "govuk_publishing_components/config"
 require "govuk_publishing_components/engine"
+require "govuk_publishing_components/presenters/brand_helper"
 require "govuk_publishing_components/presenters/contextual_navigation"
 require "govuk_publishing_components/presenters/related_navigation_helper"
 require "govuk_publishing_components/presenters/step_by_step_nav_helper"

lib/govuk_publishing_components/presenters/brand_helper.rb

@@ -0,0 +1,17 @@
+module GovukPublishingComponents
+  module Presenters
+    class BrandHelper
+      def initialize(brand)
+        @brand = brand if brand
+      end
+
+      def get_brand
+        "brand--#{@brand}" if @brand
+      end
+
+      def get_brand_element(attribute)
+        "brand__#{attribute}" if @brand
+      end
+    end
+  end
+end