Implement functionality for external container config

- Set a new `externalFrame` property when the external container config is provided.
- Use the new instance var is over the existing `frame` var.
	- This was done to isolate the new usage from the existing usage of `frame`
	- The existing usage of `frame` applies control over the sidebar frame, which works against what we want with `externalFrame`
- Make the uses of `frame` conditional.
	- These are the statements that are not invoked when the external container is specified.
	- The one case where we do want to use either frame is when emitting `onLayoutChange`
- Refactor the Sidebar tests to test for the added implementation and usage

src/annotator/host.coffee

@@ -41,6 +41,15 @@ module.exports = class Host extends Guest
     .attr('src', sidebarAppSrc)
     .addClass('h-sidebar-iframe')
 
+    externalContainer = null
+
+    if config.externalContainerSelector
+      # Use the native method to also validate the input
+      externalContainer = document.querySelector(config.externalContainerSelector)
+
+    if externalContainer
+      @externalFrame = $(externalContainer)
+    else
       @frame = $('<div></div>')
       .css('display', 'none')
       .addClass('annotator-frame annotator-outer')
@@ -52,11 +61,11 @@ module.exports = class Host extends Guest
 
     super
 
-    app.appendTo(@frame)
+    app.appendTo(@frame || @externalFrame)
 
     this.on 'panelReady', =>
       # Show the UI
-      @frame.css('display', '')
+      @frame?.css('display', '')
 
     this.on 'beforeAnnotationCreated', (annotation) ->
       # When a new non-highlight annotation is created, focus
@@ -66,5 +75,5 @@ module.exports = class Host extends Guest
         app[0].contentWindow.focus()
 
   destroy: ->
-    @frame.remove()
+    @frame?.remove()
     super

src/annotator/sidebar.coffee

@@ -162,8 +162,9 @@ module.exports = class Sidebar extends Host
     # container.
 
     if @onLayoutChange
-      rect = @frame[0].getBoundingClientRect()
-      computedStyle = window.getComputedStyle(@frame[0])
+      frame = @frame || @externalFrame
+      rect = frame[0].getBoundingClientRect()
+      computedStyle = window.getComputedStyle(frame[0])
       width = parseInt(computedStyle.width)
       leftMargin = parseInt(computedStyle.marginLeft)
 
@@ -198,6 +199,8 @@ module.exports = class Sidebar extends Host
       })
 
   onPan: (event) =>
+    return unless @frame
+
     switch event.type
       when 'panstart'
         # Initialize the gesture state
@@ -241,6 +244,7 @@ module.exports = class Sidebar extends Host
   show: ->
     @crossframe.call('sidebarOpened')
 
+    if @frame
       @frame.css 'margin-left': "#{-1 * @frame.width()}px"
       @frame.removeClass 'annotator-collapsed'
 
@@ -255,10 +259,10 @@ module.exports = class Sidebar extends Host
     this._notifyOfLayoutChange(true)
 
   hide: ->
+    if @frame
       @frame.css 'margin-left': ''
       @frame.addClass 'annotator-collapsed'
 
-
     if @plugins.Toolbar?
       @plugins.Toolbar.hideCloseBtn();
       @plugins.Toolbar.showExpandSidebarBtn();
@@ -269,7 +273,11 @@ module.exports = class Sidebar extends Host
     this._notifyOfLayoutChange(false)
 
   isOpen: ->
-    !@frame.hasClass('annotator-collapsed')
+    if @frame
+      return !@frame.hasClass('annotator-collapsed')
+    else
+      # Assume it will always be open for an external frame
+      return true
 
   setAllVisibleHighlights: (shouldShowHighlights) ->
     @crossframe.call('setVisibleHighlights', shouldShowHighlights)

src/annotator/test/sidebar-test.coffee

@@ -7,6 +7,8 @@ rafStub = (fn) ->
 
 Sidebar = proxyquire('../sidebar', { raf: rafStub })
 
+DEFAULT_WIDTH = 350
+DEFAULT_HEIGHT = 600
 EXTERNAL_CONTAINER_SELECTOR = 'test-external-container'
 
 describe 'Sidebar', ->
@@ -20,6 +22,11 @@ describe 'Sidebar', ->
     element = document.createElement('div')
     return new Sidebar(element, config)
 
+  createExternalContainer = ->
+    externalFrame = $('<div class="' + EXTERNAL_CONTAINER_SELECTOR + '"></div>')
+    externalFrame.width(DEFAULT_WIDTH).height(DEFAULT_HEIGHT)
+    return externalFrame[0]
+
   beforeEach ->
     sandbox.stub(Sidebar.prototype, '_setupGestures')
 
@@ -307,10 +314,6 @@ describe 'Sidebar', ->
   describe 'layout change notifier', ->
 
     layoutChangeHandlerSpy = null
-    sidebar = null
-    frame = null
-    DEFAULT_WIDTH = 350
-    DEFAULT_HEIGHT = 600
 
     assertLayoutValues = (args, expectations) ->
       expected = Object.assign {
@@ -321,6 +324,9 @@ describe 'Sidebar', ->
 
       assert.deepEqual args, expected
 
+    describe 'with the frame set up as default', ->
+      sidebar = null
+      frame = null
       beforeEach ->
         layoutChangeHandlerSpy = sandbox.spy()
         sidebar = createSidebar { onLayoutChange: layoutChangeHandlerSpy, sidebarAppUrl: '/' }
@@ -369,6 +375,67 @@ describe 'Sidebar', ->
         sidebar.onPan({type: 'panright', deltaX: 50})
         assertLayoutValues layoutChangeHandlerSpy.lastCall.args[0], { width: 300 }
 
+    describe 'with the frame in an external container', ->
+      sidebar = null
+      externalFrame = null
+
+      beforeEach ->
+        externalFrame = createExternalContainer()
+        Object.assign externalFrame.style, {
+          display: 'block',
+          width: DEFAULT_WIDTH + 'px',
+          height: DEFAULT_HEIGHT + 'px',
+          position: 'fixed',
+          top: 0,
+          left: 0,
+        }
+        document.body.appendChild externalFrame
+
+        layoutChangeHandlerSpy = sandbox.spy()
+        layoutChangeExternalConfig = {
+          onLayoutChange: layoutChangeHandlerSpy,
+          sidebarAppUrl: '/',
+          externalContainerSelector: '.' + EXTERNAL_CONTAINER_SELECTOR,
+        }
+        sidebar = createSidebar layoutChangeExternalConfig
+
+        # remove info about call that happens on creation of sidebar
+        layoutChangeHandlerSpy.reset()
+
+      afterEach ->
+        externalFrame.remove()
+
+      it 'notifies when sidebar changes expanded state', ->
+        sidebar.show()
+        assert.calledOnce layoutChangeHandlerSpy
+        assertLayoutValues layoutChangeHandlerSpy.lastCall.args[0], {expanded: true}
+
+        sidebar.hide()
+        assert.calledTwice layoutChangeHandlerSpy
+        assertLayoutValues layoutChangeHandlerSpy.lastCall.args[0], {
+          expanded: false,
+          width: 0,
+        }
+
+  describe 'sidebar frame in an external container', ->
+    sidebar = null
+    externalFrame = null
+
+    beforeEach ->
+      externalFrame = createExternalContainer()
+      document.body.appendChild externalFrame
+
+      sidebar = createSidebar { externalContainerSelector: '.' + EXTERNAL_CONTAINER_SELECTOR }
+
+    afterEach ->
+      externalFrame.remove()
+
+    it 'uses the configured external container as the frame', ->
+      assert.equal(sidebar.frame, undefined)
+      assert.isDefined(sidebar.externalFrame)
+      assert.equal(sidebar.externalFrame[0], externalFrame)
+      assert.equal(externalFrame.childNodes.length, 1)
+
   describe 'config', ->
     it 'does not have the BucketBar plugin if the clean theme is enabled', ->
       sidebar = createSidebar({ theme: 'clean' })