alongslide 0.9.2 → 0.9.3

data/README.md

@@ -1,6 +1,7 @@
 # Alongslide
 
-Alongslide is a layout engine extending Markdown syntax.
+Alongslide is a layout engine extending Markdown syntax for use in Rails-based
+web applications
 
 It was developed by [Triple Canopy](http://canopycanopycanopy.com/) as a
 text-editable yet sophisticated platform for producing long-form reading
@@ -8,6 +9,8 @@ content on the web.
 
 Try the demo at [alongslide.com](http://alongslide.com) or [read some theory](http://canopycanopycanopy.com/contents/announcing_alongslide) underlying the project.
 
+*Copyright 2013-2014 Canopy Canopy Canopy, Inc.*
+
 ## Dependencies
 
 The Ruby backend uses Redcarpet to extract layout directives from the
@@ -15,10 +18,79 @@ Markdown, Treetop to parse their grammar, and HAML to render them into
 templates.
 
 The CoffeeScript/SASS frontend then scan the resulting HTML for layout
-cues, using Adobe's CSS Regions polyfill to flow the body text, and
-skrollr to build transition animations and respond to user scrolling.
+cues, using a custom CSS Regions polyfill to flow the body text,
+skrollr to build transition animations and respond to user scrolling,
+plus jQuery and underscore.js as utilities.
+
+## Installing
+
+```bash
+gem install alongslide
+```
+
+The gem includes both the Ruby and frontend components.
+
+## Usage
+
+To use Alongslide, begin by setting up your view:
+
+```erb
+<article id="frames">
+	<div class="backgrounds"></div>
+	<div class="flow"></div>
+	<div class="panels"></div>
+</article>
+<div id="content" style="display: none">
+	<%= Alongslide::render(your_markdown_string) %>
+</div>
+```
+
+Where `your_markdown_string` is a string of Alongslide-flavored Markdown.
+
+Note that the Alongslide HTML is rendered into a hidden DOM element. The empty
+elements above are there for Alongslide's JS to write into.
+
+Then, once the page is loaded and ready, you can kick off the Alongslide render:
+
+```javascript
+MIN_WINDOW_WIDTH = 980
+window.alongslide = new Alongslide({
+  source: '#content',
+  to: '#frames'
+})
+frameAspect = FixedAspect.prototype.fitFrame(MIN_WINDOW_WIDTH)
+window.alongslide.render(frameAspect, function({
+	FixedAspect.prototype.fitPanels(frameAspect)
+}))
+```
+
+For RegionFlow (our CSS Regions polyfill) to work properly, it is critical that
+_all_ styles and webfonts be loaded in browser memory before the Alongslide
+render begins. For that reason, it is recommend that you use the included
+`Styles.prototype.doLoad()` utility to force CSS to load (by loading it via
+Ajax and writing it to the DOM) and/or a tool such as
+[webfontloader](https://github.com/typekit/webfontloader).
+
+After the inital render, you can use `window.alongslide.refresh(frameAspect)`
+to update just the scroll positioning (after a window resize for example) without
+incurring the full cost of doing the layout over again. 
+
+### Creating custom templates
+
+You may specify a directory in your application where you can specify your own
+custom Alongslide templates. To do so, create an `alongslide.rb` in
+`config/initializers` with the contents:
+
+```ruby
+Alongslide.configure do |config|
+  config.user_template_dir = Rails.root.join("app/views/alongslide")
+end
+```
+
+Then you may create views in that directory using the YAML frontmatter format
+described below.
 
-*Copyright 2013 Canopy Canopy Canopy, Inc.*
+If these template have JS/CSS components, those may go wherever you like.
 
 ## Syntax
 

data/alongslide.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name    = 'alongslide'
-  gem.version = '0.9.2'
+  gem.version = '0.9.3'
 
   gem.summary = "Create dynamic web layouts with an extended Markdown syntax"
   gem.description = "Create dynamic web layouts with an extended Markdown syntax"

data/app/assets/javascripts/alongslide.coffee

@@ -8,6 +8,10 @@
 #= require prefix
 #= require jquery.fitvids
 # 
+# Utility
+#= require ./styles
+#= require ./fixedAspect
+#
 # Core
 #= require alongslide/alongslide
 #= require alongslide/parser

data/app/assets/javascripts/fixedAspect.coffee

@@ -0,0 +1,145 @@
+# 
+# fixedAspect.coffee: Maintain fixed aspect ratio for given element.
+# 
+# Copyright 2013 Canopy Canopy Canopy, Inc.
+# 
+
+class window.FixedAspect
+
+  # Fit the content elements so that they maintain a consistent aspect ratio
+  # no matter the aspect ratio of the browser window.
+  # 
+  # @param minWidthPx - minimum width in pixels to allow. Don't shrink smaller!
+  # @param marginTopPx - margin top in pixels to leave open.
+  # 
+  # @return frame - bounding rect of content area, expressed as percentages
+  #   relative to the browser window (0.0-1.0).
+  # 
+  fitFrame: (minWidthPx, marginTopPx = 0) ->
+    FRAME_ASPECT = 1.6
+    FRAME_SELECTOR = '#frames > .flow > .frame'
+
+    frameAspect =
+      width: 1.0
+      height: 1.0
+      left: 0
+      top: 0
+
+    # aspect ratio calculations
+    window_aspect = $(window).width() / $(window).height()
+    if window_aspect > FRAME_ASPECT
+      frameAspect.width = FRAME_ASPECT / window_aspect
+      frameAspect.left = (1.0 - frameAspect.width) / 2
+    else
+      frameAspect.height = window_aspect / FRAME_ASPECT
+      frameAspect.top = (1.0 - frameAspect.height) / 2
+
+    # enforce margins, squeezing content down if necessary
+    marginTop = marginTopPx / $(window).height()
+    if frameAspect.top < marginTop
+      frameAspect.top = marginTop
+      scaleDown = (1.0 - frameAspect.top) / frameAspect.height
+      frameAspect.height *= scaleDown
+      frameAspect.width *= scaleDown
+      frameAspect.left = (1.0 - frameAspect.width) / 2
+
+    # enforce minWidthPx
+    frameWidthPx = frameAspect.width * $(window).width()
+    scaleUp = minWidthPx / frameWidthPx
+    if scaleUp > 1.0
+      frameAspect.height *= scaleUp
+      frameAspect.width *= scaleUp
+
+    # write to DOM, except for offset value for ALS
+    Styles::write 'debug-grid-aspect', Styles::formatPercentages('#als-debug-grid', frameAspect)
+    Styles::write 'frame-aspect', Styles::formatPercentages(FRAME_SELECTOR, _(frameAspect).omit('left'))
+
+    # write font-size / line-height
+    scalar = Math.max(1.0, (1.0 / scaleUp))
+    textStyles =
+      'font-size': parseInt($('#content-display').css('font-size')) * scalar
+      'line-height': parseInt($('#content-display').css('line-height')) * scalar
+    Styles::write 'frame-text', Styles::formatPixels('#frames', textStyles)
+
+    return frameAspect
+
+  # Go through all panels and manually turn absolute pixel-based values into
+  # percentage-based values.
+  # 
+  # Do this after render, as once the operation is done, it can't be undone.
+  # 
+  # Because of the complex interrelation between the CSS values (specified in a
+  # long, structural SASS doc) and the frame aspect value (computed on the fly),
+  # there's just no other way to do this but to get dirty and effectively write
+  # part of a CSS engine.
+  # 
+  # Every `.panel` contains a `.contents`. The latter class has top/left/width/height
+  # specified--relative to the `.panel`. We re-derive the percentages from these
+  # relative values, because JS can't easily access CSS percentage values. And this
+  # method of dynamic re-percentifying seemed more sensible than putting large amounts
+  # of style data into JSON.
+  # 
+  fitPanels: (frameAspect) ->
+    $('#frames > .panels > .panel').each (index, panel) =>
+      $panel = $(panel)
+      $contents = $panel.find('> .contents')
+
+      alignment = Alongslide::Layout::panelAlignment($panel)
+
+      innerFrame = $contents.data('innerFrame')
+
+      # If innerFrame isn't already stored, compute it now and store it.
+      unless innerFrame?
+        innerFrame = @innerFrame($panel)
+        $contents.data('innerFrame', innerFrame)
+
+      # .panel
+      # 
+      panelFrame = 
+        width: 1.0
+        height: 1.0
+
+      switch alignment
+        when "left"
+          panelFrame.width = frameAspect.left + (innerFrame.left + innerFrame.width) * frameAspect.width
+        when "right"
+          panelFrame.width = frameAspect.left + (1.0 - innerFrame.left) * frameAspect.width
+        when "top"
+          panelFrame.height = frameAspect.top + (innerFrame.top + innerFrame.height) * frameAspect.height
+        when "bottom"
+          # can't assume that frameAspect is vertically centered,
+          # due to `marginTop` (above). re-compute bottom.
+          frameAspectBottom = 1.0 - frameAspect.top - frameAspect.height
+          panelFrame.height = frameAspectBottom + (1.0 - innerFrame.top) * frameAspect.height
+
+      # .panel .contents
+      # 
+      contentsFrame = 
+        left: (frameAspect.left + innerFrame.left * frameAspect.width) / panelFrame.width
+        top: (frameAspect.top + innerFrame.top * frameAspect.height) / panelFrame.height
+        width: (innerFrame.width * frameAspect.width) / panelFrame.width
+        height: (innerFrame.height * frameAspect.height) / panelFrame.height
+
+      switch alignment
+        when "right"
+          # must use margin-left as skrollr uses left (so right-aligning won't work)
+          panelFrame['margin-left'] = (frameAspect.left + innerFrame.left * frameAspect.width)
+          contentsFrame.left = 0
+        when "bottom"
+          panelFrame.bottom = 0
+          contentsFrame.top = 0
+
+      # burn styles into CSS
+      # 
+      $panel.css Styles::formatPercentageValues panelFrame
+      $contents.css Styles::formatPercentageValues contentsFrame
+
+  # Given a panel, determine its innerFrame.
+  # 
+  innerFrame: ($panel) ->
+    $contents = $panel.find('> .contents')
+
+    left: parseInt($contents.css('left')) / $panel.width()
+    top: parseInt($contents.css('top')) / $panel.height()
+    width: $contents.width() / $panel.width()
+    height: $contents.height() / $panel.height()

data/app/assets/javascripts/styles.coffee

@@ -0,0 +1,57 @@
+# 
+# styles.coffee: Load CSS styles manually to be sure when they're loaded.
+# 
+# Copyright 2013 Canopy Canopy Canopy, Inc.
+# 
+
+class window.Styles
+  urls: []
+
+  # Break open HTML snippet and store href attributes of contained <link>s.
+  # 
+  loadLater: (snippet) ->
+    $(snippet).filter('link').each (index, link) =>
+      @urls.push $(link).attr('href')
+
+  # Load all CSS files, then execute callback.
+  # 
+  # For now, load synchronously, to make sure CSS is loaded in the correct
+  # order. Async loading is a possible optimization, but would have to do
+  # more legwork to keep track of all requests.
+  # 
+  doLoad: (callback) ->
+    styles = $('<style type="text/css"/>').appendTo('body')
+    $.each @urls, (index, url) =>
+      $.ajax url,
+        async: false
+        success: (data, textStatus, jqXHR) =>
+          styles.append data
+    callback()
+
+  # Util: CSS formatter
+  # 
+  formatPercentages: (selector, values) ->
+    declarations = (_.map values, (value, key) => "#{key}: #{@formatPercentageValue(value)}").join(';')
+    return "#{selector} { #{declarations} }"
+
+  # 
+  # 
+  formatPercentageValues: (values) ->
+    _.object _(values).map (percent, key) => [key, @formatPercentageValue percent]  
+
+  # Util.
+  # 
+  formatPercentageValue: (value) ->
+    "#{value * 100}%"
+
+  # Util: CSS formatter
+  # 
+  formatPixels: (selector, values) ->
+    declarations = (_.map values, (value, key) -> "#{key}: #{value}px").join(';')
+    return "#{selector} { #{declarations} }"
+
+  # Util: set CSS by writing <style> to the DOM.
+  # 
+  write: (id, styles) ->
+    $("style##{id}").remove()
+    $('<style type="text/css" id="'+id+'"/>').append(styles).appendTo('body')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alongslide
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
   prerelease: 
 platform: ruby
 authors:
@@ -92,6 +92,8 @@ files:
 - app/assets/javascripts/alongslide/layout.coffee
 - app/assets/javascripts/alongslide/parser.coffee
 - app/assets/javascripts/alongslide/scrolling.coffee
+- app/assets/javascripts/fixedAspect.coffee
+- app/assets/javascripts/styles.coffee
 - app/assets/stylesheets/alongslide.sass
 - app/views/panel/panel.haml
 - app/views/panel/unpin.haml