addresses #7652: deep linking for tabs and browser history update

docs/pages/tabs.md

@@ -138,4 +138,50 @@ Add the attribute `data-active-collapse="true"` to a tabstrip to collapse active
     <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
   </div>
 </div>
+```
+
+---
+
+## Tabs and URLs
+
+### Browser history
+
+The current state of the tabset is now recorded by adding a hash with the tab panel ID to the browser URL when a tab is opened. By default, tabs replace the browser history. Modify this behavior by using attribute `data-update-history="true"` to *append* to the browser history. In the latter case the browser back button will track each click that opens a tab panel.
+
+By using deep linking (see below), the open state of a page's tabset may be shared by copy-pasting the browser URL.
+
+### Deep linking
+
+Add the attribute `data-deep-link="true" to a tabstrip to allow anchoring to and opening a tab panel at page load.
+
+```html_example
+<ul class="tabs" data-deep-link="true" data-tabs id="deeplinked-tabs">
+  <li class="tabs-title is-active"><a href="#panel1c" aria-selected="true">Tab 1</a></li>
+  <li class="tabs-title"><a href="#panel2d">Tab 2</a></li>
+  <li class="tabs-title"><a href="#panel3d">Tab 3</a></li>
+  <li class="tabs-title"><a href="#panel4d">Tab 4</a></li>
+</ul>
+
+<div class="tabs-content" data-tabs-content="collapsing-tabs">
+  <div class="tabs-panel is-active" id="panel1d">
+    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
+  </div>
+  <div class="tabs-panel" id="panel2d">
+    <p>Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus.</p>
+  </div>
+  <div class="tabs-panel" id="panel3d">
+    <img class="thumbnail" src="assets/img/generic/rectangle-3.jpg">
+  </div>
+  <div class="tabs-panel" id="panel4d">
+    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
+  </div>
+</div>
+```
+
+For example, <a href="#panel3d">http://example.com/#panel3d</a> will open the third tab panel at page load.
+
+When linking directly to a tab panel, it might not be obvious that the content appears within a tab panel. An additional attribute `data-deep-link-smudge` rolls the page up slightly after deep linking (to a horizontal tabset) so that the tabstrip is at the top of the viewport.
+
+```html_example
+<ul class="tabs" data-deep-link="true" data-deep-link-smudge="true" data-deep-link-smudge-delay="600" data-tabs id="deeplinked-tabs-with-smudge">
 ```

js/foundation.tabs.js

@@ -72,6 +72,30 @@ class Tabs {
       if(isActive && _this.options.autoFocus){
         $link.focus();
       }
+
+      //use browser to open a tab, if it exists in this tabset
+      if (_this.options.deepLink) {
+        var anchor = window.location.hash;
+        //need a hash and a relevant anchor in this tabset
+        if (anchor.length && $elem.find('[href="'+anchor+'"]').length) {
+
+          _this.selectTab($(anchor));
+
+          //roll up a little to show the titles
+          if (_this.options.deepLinkSmudge) {
+            $(window).load(function() {
+              var offset = $elem.offset();
+              $('html, body').animate({ scrollTop: offset.top }, _this.options.deepLinkSmudgeDelay);
+            });
+          }
+
+          /**
+            * Fires when the zplugin has deeplinked at pageload
+            * @event Tabs#deeplink
+            */
+          this.$element.trigger('deeplink.zf.tabs', [$target]);
+        }
+      }
     });
 
     if(this.options.matchHeight) {
@@ -208,14 +232,21 @@ class Tabs {
     //open new tab
     this._openTab($target);
 
-
+    //either replace or update browser history
+    var anchor = $target.find('a').attr('href');
+    if (this.options.updateHistory) {
+      history.pushState({}, "", anchor);
+    } else {
+      history.replaceState({}, "", anchor);
+    }
+
     /**
      * Fires when the plugin has successfully changed tabs.
      * @event Tabs#change
      */
     this.$element.trigger('change.zf.tabs', [$target]);
 
-	//fire to children a mutation event
+	  //fire to children a mutation event
 	  $targetContent.find("[data-mutate]").trigger("mutateme.zf.trigger");
   }
 
@@ -332,8 +363,37 @@ class Tabs {
 }
 
 Tabs.defaults = {
+  /**
+   * Allows the window to scroll to content of pane specified by hash anchor
+   * @option
+   * @example false
+   */
+  deepLink: false,
+
+  /**
+   * Adjust the deep link scroll to make sure the top of the tab panel is visible
+   * @option
+   * @example false
+   */
+  deepLinkSmudge: false,
+
+  /**
+   * Animation time (ms) for the deep link adjustment
+   * @option
+   * @example 300
+   */
+  deepLinkSmudgeDelay: 300,
+
+  /**
+   * Update the browser history with the open tab
+   * @option
+   * @example false
+   */
+  updateHistory: false,
+
   /**
    * Allows the window to scroll to content of active pane on load if set to true.
+   * Not recommended if more than one tab panel per page.
    * @option
    * @example false
    */