search

ebiwd / EBI-Framework

The EMBL-EBI Visual Framework for websites and services.
https://www.ebi.ac.uk/style-lab/websites/
19 stars 16 forks source link

Sample migration from v1.1 to v1.2 #85

Closed khawkins98 closed 7 years ago

khawkins98 commented 7 years ago

This issue will do a series of step-by-step diffs to migrate https://ebiwd.github.io/EBI-Pattern-library/sample-site/

Background on changes

Not all of these structural changes are necessary for the look and feel of the site, but they provide a better html architecture that separates the areas of EMBL-EBI's content and your site/service's content -- which will now all be inside of div#content. These changes increase the code size and speed, and — most importantly — make it easier to develop apps for modern JS frameworks, like Angular and React.

Here's how it looks as v1.1: image

khawkins98 commented 7 years ago

Step 1

Swap the CSS and JS URL references from v1.1 to v1.2 

-  <link rel="icon" type="image/x-icon" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/favicon.ico" />
-  <link rel="icon" type="image/png" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/favicon-32x32.png" />
-  <link rel="icon" type="image/png" sizes="192×192" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/android-chrome-192x192.png" /> <!-- Android (192px) -->
-  <link rel="apple-touch-icon-precomposed" sizes="114x114" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/apple-icon-114x114.png" /> <!-- For iPhone 4 Retina display (114px) -->
-  <link rel="apple-touch-icon-precomposed" sizes="72x72" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/apple-icon-72x72.png" /> <!-- For iPad (72px) -->
-  <link rel="apple-touch-icon-precomposed" sizes="144x144" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/apple-icon-144x144.png" /> <!-- For iPad retinat (144px) -->
-  <link rel="apple-touch-icon-precomposed" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/apple-icon-57x57.png" /> <!-- For iPhone (57px) -->
-  <link rel="mask-icon" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/safari-pinned-tab.svg" color="#ffffff" /> <!-- Safari icon for pinned tab -->
+  <link rel="icon" type="image/x-icon" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/favicon.ico" />
+  <link rel="icon" type="image/png" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/favicon-32x32.png" />
+  <link rel="icon" type="image/png" sizes="192×192" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/android-chrome-192x192.png" /> <!-- Android (192px) -->
+  <link rel="apple-touch-icon-precomposed" sizes="114x114" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/apple-icon-114x114.png" /> <!-- For iPhone 4 Retina display (114px) -->
+  <link rel="apple-touch-icon-precomposed" sizes="72x72" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/apple-icon-72x72.png" /> <!-- For iPad (72px) -->
+  <link rel="apple-touch-icon-precomposed" sizes="144x144" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/apple-icon-144x144.png" /> <!-- For iPad retinat (144px) -->
+  <link rel="apple-touch-icon-precomposed" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/apple-icon-57x57.png" /> <!-- For iPhone (57px) -->
+  <link rel="mask-icon" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/safari-pinned-tab.svg" color="#ffffff" /> <!-- Safari icon for pinned tab -->
-  <meta name="msapplication-TileImage" content="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/images/logos/EMBL-EBI/favicons/mstile-144x144.png" />
+  <meta name="msapplication-TileImage" content="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/images/logos/EMBL-EBI/favicons/mstile-144x144.png" />
-  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/libraries/foundation-6/css/foundation.css" type="text/css" media="all" />
-  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/css/ebi-global.css" type="text/css" media="all" />
-  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Icon-fonts/v1.1/fonts.css" type="text/css" media="all" />
+  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/libraries/foundation-6/css/foundation.css" type="text/css" media="all" />
+  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/css/ebi-global.css" type="text/css" media="all" />
+  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Icon-fonts/v1.2/fonts.css" type="text/css" media="all" />
-  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/css/theme-embl-petrol.css" type="text/css" media="all" />
+  <link rel="stylesheet" href="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/css/theme-embl-petrol.css" type="text/css" media="all" />
-  <script defer="defer" src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/js/script.js"></script>
+  <script defer="defer" src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/js/script.js"></script>
-  <script src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/libraries/foundation-6/js/foundation.js"></script>
-  <script src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.1/js/foundationExtendEBI.js"></script>
+  <script src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/libraries/foundation-6/js/foundation.js"></script>
+  <script src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/js/foundationExtendEBI.js"></script>

image

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/0961f2acfd5166c6c2533dfc34095863e82bf9ab

khawkins98 commented 7 years ago

Step 2

Remove references to these JS files:

-  <!-- All JavaScript at the bottom, except for Modernizr -->
-  <script src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/libraries/modernizr/modernizr.custom.49274.js"></script>
-  <script defer="defer" src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/js/cookiebanner.js"></script>
-  <script defer="defer" src="https://www.ebi.ac.uk/web_guidelines/EBI-Framework/v1.2/js/foot.js"></script>

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/6b0451fa41505183c3553c6e98e0b87bd41e0ba1

khawkins98 commented 7 years ago

Step 3

Move the .row class from div#content and place it on the child section.

So what was:

  <div id="content" role="main" class="row">
      <!-- Suggested layout containers -->
      <section>

becomes

  <div id="content">
      <!-- Suggested layout containers -->
      <section id="main-content-area" class="row" role="main">

As a diff:

-  <div id="content" role="main" class="row">
+  <div id="content">
-      <section>
+      <section id="main-content-area" class="row" role="main">

For now, this won't have any visible changes.

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/97cc791b1756eea3b543acd6435537cb113154c8

khawkins98 commented 7 years ago

Step 4

  1. Delete your exisisting header open and close tags
  2. Swap the div#global-masthead for: 
    <header id="masthead-black-bar" class="clearfix masthead-black-bar">
<nav class="row">
  <ul id="global-nav" class="menu">
    <!-- set active class as appropriate -->
    <li class="home-mobile"><a href="//www.ebi.ac.uk"></a></li>
    <li class="home active"><a href="//www.ebi.ac.uk">EMBL-EBI</a></li>
    <li class="services"><a href="//www.ebi.ac.uk/services">Services</a></li>
    <li class="research"><a href="//www.ebi.ac.uk/research">Research</a></li>
    <li class="training"><a href="//www.ebi.ac.uk/training">Training</a></li>
    <li class="about"><a href="//www.ebi.ac.uk/about">About us</a></li>
    <li class="search">
      <a href="#" data-toggle="search-global-dropdown"><span class="show-for-small-only">Search</span></a>
      <div id="search-global-dropdown" class="dropdown-pane" data-dropdown data-options="closeOnClick:true;">
      <!-- The dropdown menu will be programatically added by script.js -->
      </div>
    </li>
    <li class="float-right show-for-medium embl-selector">
      <button class="button float-right" type="button" data-toggle="embl-dropdown">Hinxton</button>
      <!-- The dropdown menu will be programatically added by script.js -->
    </li>
  </ul>
</nav>
</header>

Don't forget to set your .active <li> tab; in this example it's the li.home.

Your page should now begin to look more normal: image

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/94214a42e4ffcaf4dc927c42f16a27ce3cc0ca51

khawkins98 commented 7 years ago

Step 5

If you use the meta tags:

update them to

This won't have a visible effect yet.

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/7e05742ffdaec16ce6f5ae000a4abbe8e39a4398

khawkins98 commented 7 years ago

Step 6

Move div.masthead.row inside div#content

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/e264002ff1cc33cc8d49069fc9209de428632a7b

khawkins98 commented 7 years ago

Step 7

We now need to make the masthead 'sticky' (if you use the stick container) and wrap and add a div.masthead-inner.

So what is currently:

    <div class="masthead row">

Becomes:

    <div data-sticky-container>
      <div id="masthead" class="masthead" data-sticky data-sticky-on="large" data-top-anchor="main-content-area:top" data-btm-anchor="main-content-area:bottom">
        <div class="masthead-inner row">

Don't forget to add the two new </div> closing tags.

Your masthead should now span the full screen width and stick to the top properly, like so: image

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/fa3a711bddc21fa01b83cff0284552fdc7757092

khawkins98 commented 7 years ago

Step 8

Remove your old data-sticky-container and div#masthead, this bit (and don't forget the closing divs). 

-  <div data-sticky-container>
-    <div id="masthead" data-sticky data-sticky-on="large" data-top-anchor="180" data-btm-anchor="300000">
         <header id="masthead-black-bar" class="clearfix masthead-black-bar">
           <nav class="row">
...
           </nav>
         </header>
-      </div>
-  </div>

If you're setting your masthead background image or colour through the meta tags, it will now show — otherwise this won't have any visible effect. image

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/c917a8592fd5be81aabe362ff003c1859ec7643d

khawkins98 commented 7 years ago

Step 9

You may have noticed we've been adding class names to our divs that previously only had IDs, that is the div#masthead now also has the class .masthead. This helps ensure that CSS styling is properly inherited.

We also need to do this to the <footer>. 

-      <div id="local-footer">
+      <footer id="local-footer" class="local-footer">
-      <div id="global-footer">
+      <div id="global-footer" class="global-footer">
-        <nav id="global-nav-expanded" class="row">
+        <nav id="global-nav-expanded" class="row global-nav-expanded">
-        <section id="ebi-footer-meta" class="row">
+        <section id="ebi-footer-meta" class="row ebi-footer-meta">

Your footer should now be styled properly.

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/4684d0d199f6f6df64d236b4f5669778263412e5

khawkins98 commented 7 years ago

Step 10

If you have a div.local-footer, move it inside div#content just before the closing </div>

This won't have a visible impact.

Details: https://github.com/ebiwd/EBI-Pattern-library/commit/b2cdef53b534461a2f7898331a05b7a386fb4263

khawkins98 commented 7 years ago

That's it, you should be finished now.

Again, not all of these structural changes are necessary for the look and feel of the site, but they provide a better html architecture that separates the areas of EMBL-EBI's content and your site/service's content -- which will now all be inside of div#content.

The structure now follows:

<body>
  <header id="masthead-black-bar" class="clearfix masthead-black-bar">
    <nav class="row">
      <ul id="global-nav" class="menu">
      EBI CONTROLLED STUFF
      </ul>
    </nav>
  </header>

  <div id="content">
    <div data-sticky-container>
      <header id="masthead" class="masthead" data-sticky>
        <div class="masthead-inner row">
          YOUR MENU AND PAGE TITLE
        </div>
      </header>
    </div>

    <footer id="main-content-area" class="row" role="main">
      YOUR PAGE CONTENT
    </footer>
  </div>

  <footer>
    <div id="global-footer" class="global-footer">
    EBI CONTROLLED STUFF
    </div>
  </footer>
</body>

And here's a visualisation of the improved structure between v1.1 and v1.2: structure View it bigger here

If you have questions, post them below or, if it's a question specific to your site's migration, open a new ticket.