Spling quick reference

Stack

Spling is built with Backbone 0.9.1, the docs are http://backbonejs.org/
Spling is written with coffeescript (compiled to js on deploy).
Templates are written in eco (compiled to js on deploy).
Stylesheets are written in less (compiled on deploy).

The views (archetype edition)

There are two views you'll be interested in overriding

The main view (grid)
The spling subview (rendered into the grid)

The namespace

Spling lives in SPLING, overriding these classes will change how your widget is rendered.

views in SPLING.views (e.g SPLING.views.Grid)
collections and models live in SPLING (e.g SPLING.Spling for the spling/link model)

Default DOM elements

All templates are placed within the dom elements generated in the view, this is a backbone idiom

Default Templates

The spling templates work in tandem, with tileSpling.eco being placed within the .content block of tile.eco

tile.eco

<% if (not @model.get 'empty') and @model.get 'processed': %>
  <% if @model.get 'resize' : %>
    <div class="resize"></div>
  <% end %>
  <div class="tooltip" style="display: none;"></div>
  <div class="overlay"></div>

  <div class='content'></div>

  <% if @model.get('editMode') and @model.isOwner(): %>
    <a href="/edit/<%= @model.get('id') || @model.get('spling_id') %>" class="settings">Settings</a>
  <% end %>
<% end %>

tileSpling.eco

<div>
    <a class='link' 
       name='open'
       href="<%= @model['getAbsoluteURL']%>" 
       data-spling="<%= @model['splingURL']%>"
       target='<%= @model['target'] %>'
       title="<%= @model['Title'] %>"
      <% if @model['bypass']: %>data-bypass<% end %>>
      <span class='title'><%= @model['truncated_title']%></span>
    </a>
    <% unless _.isEmpty(@model['Caption']): %>
      <div class='caption'>
        <div class='padding'>
          <span class='info'><%=@model['Caption']%></span>
        </div>
      </div>
    <% end %>
    <img src="<%=@model['thumbnail']%>" alt=''/>
</div>

Default less

#spling{
    position: relative;
    list-style: none;
    margin: 0;
    width: 100%;
    height: 270px;

    li{
        z-index: 2;
        text-align: center;
    }

    a.link,
    img,
    .overlay,
    .resize,
    .caption,
    .text{
        width: 320px;
        height: 242px;
    }

    .overlay{
        display: none;
    }

    a.link{
        position: absolute;
        z-index: 50;
        left: 0;
        text-align: left;
        color: black;
    }

    .title{
        position: relative;
        top: 250px;
        text-align: left;
    }
}

Basic customization

Modify the class attributes Backbone view constructor, tagName, className and id will make styling a lot easier.
Customize the template. Set SPLING.views.Spling.templateSpling to be a function that takes a model instance and returns html

Basic settings

Basic settings can be set from the spling element through data properties.

cells: the layout of the recommendation grid. 0:1x1, 1:1x2, 2:2x1, 3:2x2
size-base: the size of a 1x1 spling thumbnail e.g 160x160
size-step: the size of a 2x2 spling thumbnail (2*spling-base + margin between) e.g 340x340
tags: comma seperated list of tags to return results for

Advanced settings

Below are the advanced settings, all of them are optional.

<script type='text/javascript'>
  var template_function = function(model){
    return ecoTemplates['eco/core/tiles/tile.eco'](model);
  };
  var template_function_spling = function(model){
    return ecoTemplates['eco/core/tiles/tileSpling.eco'](model);
  }
  window.SPLING = {
    'data': {},
    'apiURL':'//archetype-staging.spling.com/api/2/',
    'views': {
      'Grid' : {
        'id': 'splings',
        'tagName': 'ul',
        'className': 'splings',
      },
      'Spling': {
        'tagName': 'li',
        'className': '',
        // Functions that returns html
        'template': template_function,
        'templateSpling': template_function_spling
      }
    }
  };
  var spCb = function(d){SPLING['data'] = d;};
  (function($) {
    var ts=[], l=0, 
        ot=($('#spling').data('spling-tags')+'').split(','),
        cs=($('#spling').data('spling-cells')+'').replace(/(\||\\n)/,',').split(','),
        sb=$('#spling').data('spling-size-base'),
        ss=$('#spling').data('spling-size-step'),
        sp=$('<script>').attr('type', 'text/javascript').attr('async', true);
    for (i in ot){t=ot[i].trim();if(t.length) ts.push(t);}
    for (i in cs){c=cs[i].trim();if(c.length && c != '-') ++l;}
    var qs=$.param({callback:'spCb',tags:ts, limit:l,'size-base':sb,'size-step':ss});
    sp.attr('src', SPLING.apiURL+'recommendation/?'+qs).insertBefore($('script')[0]);
  })(jQuery);
</script>

hcliff/readme.md