node package manager

@squarespace/layout-base

Squarespace Template Layout Base Module

A base module class for building Squarespace layouts.

  • Performs basic module configuration and bootstrapping
  • Options passed to layout() are merged with config automatically
  • Provides hooks into the layout render pipeline
  • Provides interface for before/after resize handlers

NOTICE: This code is licensed to you pursuant to Squarespace’s Developer Terms of Use. See license section below.

Usage

Install

npm install --save @squarespace/layout-base

Implementation

import LayoutBase from '@squarespace/layout-base';
 
class NewLayout extends LayoutBase {
  constructor(rootNode, config) {
    super(rootNode, config);
 
    // layout construction 
  }
 
  layout(config) {
    // module handles config update before layout cycle 
    this.beforeLayout(config);
 
    // options can always be explicity set without passing to beforeLayout 
    // this.config = config; 
 
    // layout work 
 
    this.afterLayout();
  }
 
  destroy(config) {
    this.beforeDestroy();
 
    // destroy layout 
 
    this.afterDestroy();
  }
}

Using ES6

If you prefer to handle transpiling and polyfilling on your own, you can import ES6 from Layout Base:

import LayoutBase from '@squarespace/layout-base/src';

Alternately, Layout Base specifies a module property in package.json that points to the uncompiled src/index.js, so you may be able to simply import @squarespace/layout-base if you're using one of the following bundlers:

Reference

API

rootNode

node passed as first argument

document

reference to rootNode.ownerDocument

window

reference to rootNode.ownerDocument.defaultView

config

configuration object

childNodes

array of nodes matching config.childSelector

hasRunInitialLayout

set to true after first layout cycle

Config

Defaults

  resizeHandler: true
  resizeDebounceTime: 250
  resizeMaxWait: 2500

Resize Handlers

LayoutBase includes 2 built-in resize hooks by default:

config.beforeResize()

called immediately on first resize event in a sequence

config.afterResize()

debounced event is called config.resizeDebounceTimems after the final resize event in a sequence; force fires after config.resizeMaxWaitms

You can choose to manually handle resizing in your module by setting resizeHandler: false in your config

Hooks

Layout

config.beforeLayout(config)

called before each layout cycle

config.beforeInitialLayout()

called before the first layout cycle only

config.afterLayout()

called after each layout cycle

config.afterInitialLayout()

called after the first layout cycle only

Lifecycle

config.beforeDestroy()

called before tearing down the layout

config.afterDestroy()

called after tearing down the layout

Altering Hooks

class NewLayout extends LayoutBase {
...
  beforeLayout() {
    // do some module-specific layout stuff 
 
    // optionally, to still fire config beforeLayout callback 
    super.beforeLayout();
  }
...
}

Tests

npm run test: run tests npm run cover: generate JSON coverage report npm run report: generate HTML coverage report

License

Portions Copyright © 2016 Squarespace, Inc. This code is licensed to you pursuant to Squarespace’s Developer Terms of Use, available at http://developers.squarespace.com/developer-terms-of-use (the “Developer Terms”). You may only use this code on websites hosted by Squarespace, and in compliance with the Developer Terms. TO THE FULLEST EXTENT PERMITTED BY LAW, SQUARESPACE PROVIDES ITS CODE TO YOU ON AN “AS IS” BASIS WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED.