tell-them 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57fcbb4894e21105e91f9d0a1b9bd03db6c72488
-  data.tar.gz: ef79de9024e1c7123157b804b52d33269b1d1d59
+  metadata.gz: d432d6888bcade75af163344773ac696555f5e8a
+  data.tar.gz: 4f7f8fa63b1729a69120501b82c1f16ae9c72c4e
 SHA512:
-  metadata.gz: 478ba1fd87a296f7a7aeea5850746568bec309767bace103aeb5b0383794fc520bf92f096d808e97ba75c57a22511cf2b38e61122d11bcf01a65d69ee0261e6a
-  data.tar.gz: c995c555664c41604994589058be470c730bfdc5c31a2dc4d3767be25ca5ce7be6da02733ccea182a32225a33f8fe12b0eaf394d1e4322c9952d05bd2d8404b3
+  metadata.gz: c5099bbe8569dc8d24ef7d7a4dcb55e68d0710989a4d328128fdd3f8cc561adedf675513f92963e788b3b5094c105d0676d882dd8b09f9a3b352b4ee97eb2d3a
+  data.tar.gz: 6819f981782d8b6fedb86e006f95365d63a7de144a3a511d1db62e3d0f93e3d4093e1908a667349c4123d5f792eaea7fe1532bc6153960194e8d864ce03162ab

data/README.md

@@ -25,25 +25,17 @@ Or install it yourself as:
 
 ## Usage
 
-You'll need to include the tell-them style file in app/assets/stylesheets/application.scss,
-
-```
- //= require tell-them
-```
-
-...and add a line into your layout (say in apps/views/layouts/application.html.erb) that will insert the necessary HTML:
+You'll need to add a line into your layout (say in apps/views/layouts/application.html.erb) that will insert the necessary HTML, along with JS and CSS links (I've assumed that because this is development only, JS and CSS pipeline optimisation is probably unnecessary):
 
 ```
 <%= TellThem.html %>
 ```
 
-[OPTIONAL] add the script files in app/assets/javascripts/application.js (TellThem doesn't need the javascript to work, but it enables a few nice features like saved prefs, choosing the position of the pop-up debugging box and allowing you to pin it open)
+Once that's done, TellThem is ready to use! 
 
-```
- //= require tell-them
-```
+### Data
 
-When all that's done, TellThem is ready to use! Whenever you want to expose internal data from the controller to the developer in the webpage, just add it as one or more key:value pairs using a map:
+Whenever you want to expose internal data from the controller to the developer in the webpage, just add it as one or more key:value pairs using a map:
 
 ```
 TellThem.add(this: 'this is some data!', :'Become Admin' => '/become_admin?source=tell-them')
@@ -54,4 +46,30 @@ This data will now appear in a little pop-up box on the webpage. Note that the p
 * No data? No box
 * In production/staging/test? No box
 
-If the value of any item will parse as a URI, TellThem will wrap it in a link so that it's clickable.
+If the value of any item will parse as a URI, TellThem will wrap it in a link so that it's clickable.
+
+### Media Indicators
+
+If you would like TellThem to help you debug your breakpoints and responsive behaviour, it can do that too. Using an array of maps, you can enable a set of CSS-styled indicators to appear on the box. Supply a `min` and/or `max` selector to match your breakpoints, and a `name` item that will display in the box header when the specified breakpoint is active. If you also add an `initial` item the ? in the TellThem box will be replaced, so that you don't have to open or pin the box to see the current breakpoint.
+
+```
+TellThem.enable_media_queries([
+  { initial: "M", name: 'mobile', max: '767px' },
+  { initial: "T", name: 'tablet', min: '768px', max: '889px' },
+  { initial: "S", name: 'screen', min: '890px', max: '1249px' },
+  { initial: "W", name: 'wide', min: '1250px' },
+])
+```
+
+### Grid overlays
+
+If you would like TellThem to help you debug grid layout as well, you can add column count, width, and spacing to the media query block. It will add a "Grid" button to the controls to toggle grid visibility, or in non-js land the grid will always be visible.
+
+```
+TellThem.enable_media_queries([
+  { initial: "M", name: 'mobile', max: '767px', columns: 1, margins: '20px' },
+  { initial: "T", name: 'tablet', min: '768px', max: '889px', columns: 18, column_width: '20px', column_space: '15px' },
+  { initial: "S", name: 'screen', min: '890px', max: '1249px', columns: 24, column_width: '20px', column_space: '15px' },
+  { initial: "W", name: 'wide', min: '1250px', columns: 36, column_width: '20px', column_space: '15px' },
+])
+```

data/app/assets/javascripts/tell-them.js.coffee

@@ -5,6 +5,10 @@ load_prefs = ->
   if prefs.pinned == 1
   	$('#tell-them-box').addClass('pinned')
   	$('#tell-them-box .controls .pin').text('Unpin')
+  $('#tell-them-box').removeClass('grid-on')
+  if prefs.grid == 1
+    $('#tell-them-box').addClass('grid-on')
+    $('#tell-them-box .controls .pin').text('No Grid')
   $('#tell-them-box').addClass(prefs.corner)
   $('#tell-them-box .controls .corners button').removeClass('current')
   $('#tell-them-box .controls .corners button[data-target-corner=' + prefs.corner +  ']').addClass('current')
@@ -13,10 +17,12 @@ save_prefs = ->
   pin_value = 0
   if $('#tell-them-box').hasClass('pinned')
   	pin_value = 1
-  prefs = {
+  grid_value = 0
+  if $('#tell-them-box').hasClass('grid-on')
+    grid_value = 1
+  prefs =
   	corner: $('#tell-them-box .controls .corners button.current').data('target-corner'),
-  	pinned: pin_value
-  }
+  	pinned: pin_value,
   localStorage.setItem("tellThemPrefs", JSON.stringify(prefs))
 
 change_corners = (e) ->
@@ -34,8 +40,17 @@ toggle_pin = (e) ->
   	$('#tell-them-box .controls .pin').text('Pin')
   save_prefs()
 
+toggle_grid = (e) ->
+  $('#tell-them-box').toggleClass('grid-on')
+  if $('#tell-them-box').hasClass('grid-on')
+    $('#tell-them-box .controls .grid').text('No Grid')
+  else
+    $('#tell-them-box .controls .grid').text('Grid')
+  save_prefs()  
+
 $ ->
   load_prefs()
   $('#tell-them-box .controls .corners button').on 'click', change_corners
-  $('#tell-them-box .controls .pin').on 'click', toggle_pin
+  $('#tell-them-box .controls .grid').on 'click', toggle_grid
+  $('#tell-them-box .controls .pin').on 'click', toggle_pin  
   $('#tell-them-box .controls').css('display', 'block')

data/app/assets/stylesheets/grid-overlay.sass

@@ -0,0 +1,19 @@
+#tell-them-box:hover+#grid-overlay, #tell-them-box.grid-on+#grid-overlay
+  position: fixed
+  top: 0px
+  bottom: 0px
+  left: 0px
+  right: 0px
+  z-index: 500
+  .grid-content
+    font-size: 0
+    height: 100%
+    margin: 0 auto
+    background-color: rgba(181,76,12,0.3)
+  .grid-column
+    height: 100%
+    background-color: rgba(0,0,0,0.2)
+    display: inline-block
+  .grid-space
+    height: 100%
+    display: inline-block

data/app/assets/stylesheets/tell-them.sass

@@ -1,3 +1,5 @@
+@import 'grid-overlay'
+
 =positionable-box($distance)
 	position: fixed
 	bottom: $distance
@@ -88,15 +90,18 @@ $pad: 2%
 				position: absolute
 				top: 40%
 				right: 45%
-			.pin
+			.grid, .pin
 				position: absolute
 				top: 40%
-				right: $pad
 				border-radius: $pad
 				padding: 0.3em 0.3em
 				background-color: white
 				color: black
 				cursor: pointer
+			.grid
+				right: $pad + 10%
+			.pin
+				right: $pad
 		.list
 			margin: $pad
 			border-radius: 1em
@@ -121,3 +126,9 @@ $pad: 2%
 				.pin
 					background-color: black
 					color: white
+	&.grid-on
+		.contents
+			.controls
+				.grid
+					background-color: black
+					color: white

data/lib/tell-them/tell-them.rb

@@ -27,10 +27,18 @@ module TellThem
     TellThemStore.instance.has_media_queries?
   end
 
+  def self.has_media_grid_info?
+    TellThemStore.instance.has_media_grid_info?
+  end
+
   def self.media_queries
     TellThemStore.instance.media_queries
   end
 
+  def self.media_grid_max_columns
+    TellThemStore.instance.media_grid_max_columns
+  end
+
   def self.html
     return '' unless (has_data? || has_media_queries?) && ::Rails.env.development?
     return ActionController::Base.helpers.stylesheet_link_tag('tell-them') + 
@@ -53,6 +61,7 @@ module TellThem
     box += '        <button class="current" data-target-corner="bottom-right"></button>'
     box += '      </div>'
     box += media_queries_flag_html
+    box += '      <button class="grid">Grid</button>'
     box += '      <button class="pin">Pin</button>'
     box += '    </div>'
     box += '    <dl class="list">'
@@ -69,6 +78,7 @@ module TellThem
     box += '    </dl>'
     box += '  </div>'
     box += '</div>'
+    box += media_grid_html
     box
   end
 
@@ -90,6 +100,7 @@ module TellThem
       style_box += "{ \n"
       style_box += "  \#tell-them-box:before { content: \"#{query_data[:initial]}\"; }\n" if query_data[:initial]
       style_box += "  \#tell-them-box .#{query_data[:name]} { display: block; }\n"
+      style_box += media_grid_css(query_data)
       style_box += " } \n"
     end
     style_box += "</style>"
@@ -104,6 +115,52 @@ module TellThem
     flag_div += '</div>'
   end
 
+  def self.media_grid_html
+    return '' unless has_media_grid_info?
+    grid_box =  '  <div id="grid-overlay">' + "\n"
+    grid_box += '    <div class="grid-content">' + "\n"
+    grid_box += "       <div class=\"grid-column #{validity_string}\"></div>" + "\n"
+    (2..media_grid_max_columns).each do |c|
+      grid_box += "       <div class=\"grid-space #{validity_string(c)}\"></div>" + "\n"
+      grid_box += "       <div class=\"grid-column #{validity_string(c)}\"></div>" + "\n"
+    end
+    grid_box += '    </div>' + "\n"
+    grid_box += '  </div>' + "\n"
+  end
+
+  def self.validity_string(columns = nil)
+    validity_string = ""
+    column_array.each { |c| validity_string += "valid-for-#{c} " if columns.nil? || c >= columns }
+    validity_string
+  end
+
+  def self.column_array
+    array = []
+    media_queries.each { |mq| array << mq[:columns] }
+    array
+  end
+
+  def self.media_grid_css(query_data)
+    return '' unless has_media_grid_info?
+    grid_css =  "  \#grid-overlay .grid-content .grid-column { display: none !important; }\n"
+    grid_css += "  \#grid-overlay .grid-content .grid-space { display: none !important; }\n"
+    grid_css += "  \#grid-overlay .grid-content { margin-top: #{query_data[:margin_top]} !important; }\n" if query_data.has_key?(:margin_top)
+
+    if query_data[:columns] == 1
+      grid_css += "  \#grid-overlay .grid-content { margin-left: #{query_data[:margins]} !important; margin-right: #{query_data[:margins]} !important }\n"
+      grid_css += "  \#grid-overlay .grid-content .grid-column.valid-for-1 { display: inline-block; width: 100%; }\n"
+    else
+      units = query_data[:column_width].gsub(/[0-9]/,'')
+      total_c_width = query_data[:column_width].gsub(units,'').to_i * query_data[:columns]
+      total_s_width = query_data[:column_space].gsub(units,'').to_i * (query_data[:columns] - 1)
+      total_width = (total_c_width + total_s_width).to_s + units
+      grid_css += "  \#grid-overlay .grid-content { width: #{total_width}; }\n"
+      grid_css += "  \#grid-overlay .grid-content .grid-column.valid-for-#{query_data[:columns]} { display: inline-block !important; width: #{query_data[:column_width]} }\n"
+      grid_css += "  \#grid-overlay .grid-content .grid-space.valid-for-#{query_data[:columns]} { display: inline-block !important; width: #{query_data[:column_space]} }\n"
+    end
+  end
+
+
   class TellThemStore
     include Singleton
 
@@ -136,8 +193,24 @@ module TellThem
       @media_queries.any?
     end
 
+    def has_media_grid_info?
+      return false unless has_media_queries?
+      @media_queries.each do |mq|
+        next unless mq.has_key?(:columns)
+        return true if mq[:columns] == 1 && mq.has_key?(:margins)
+        return true if mq[:columns] > 1 && mq.has_key?(:column_width) && mq.has_key?(:column_space)
+      end
+      false
+    end
+
     def media_queries
       @media_queries
     end
+
+    def media_grid_max_columns
+      columns = 0
+      media_queries.each { |mq| columns = [columns, mq[:columns]].max }
+      columns
+    end
   end
 end

data/lib/tell-them/version.rb

@@ -1,5 +1,5 @@
 module TellThem
   module Rails
-    VERSION = "0.3.2"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tell-them
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - K M Lawrence
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-27 00:00:00.000000000 Z
+date: 2016-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -99,6 +99,7 @@ files:
 - README.md
 - Rakefile
 - app/assets/javascripts/tell-them.js.coffee
+- app/assets/stylesheets/grid-overlay.sass
 - app/assets/stylesheets/tell-them.sass
 - bin/console
 - bin/setup