Get Started

Installation

Formstone is available via NPM or a CDN.

npm i formstone

You can use Formstone directly in the browser with the full library or ES6 Modules, or bundle Formstone into your application using a module bundler like Webpack.

Full Library

Load the full library from a CDN or your local project. The global Formstone object will include all available modules, which can be destructured into local variables.

<link rel="stylesheet" href="path/to/formstone/dist/formstone.css">

<script src="path/to/formstone/dist/formstone.js"></script>

<script>
  let { Background, Utils } = Formstone;

  Utils.ready(() => {
    Background.construct('.js-background', {
      source: '...',
    });
  });
</script>

ES6 Modules

Load specific modules from a CDN or your local project using import statements.

<link rel="stylesheet" href="path/to/formstone/src/css/background.css">

<script type="importmap">
  {
    "imports": {
      "formstone": "path/to/formstone/src/js/index.js"
    }
  }
</script>

<script type="module">
  import { Background, Utils } from 'formstone';

  Utils.ready(() => {
    Background.construct('.js-background', {
      source: '...',
    });
  });
</script>

Module Bundler

Bundle Formstone into your project by importing only the modules needed.

@import 'path/to/formstone/src/less/background.less';

import { Background, Utils } from 'formstone';

Utils.ready(() => {
  Background.construct('.js-background', {
    source: '...',
  });
});

jQuery Adaptors

Formstone includes jQuery adaptors for each module, allowing integration into legacy environments. The adaptors are thin wrappers; options, methods and events are the same as each module's own API.

Setup

Load jQuery first, then the jQuery build. Plugins register on the global jQuery automatically.

<link rel="stylesheet" href="path/to/formstone/dist/formstone.css">

<script src="path/to/jquery.js"></script>
<script src="path/to/formstone/dist/formstone.jquery.js"></script>

When bundling, import the adaptors instead. If jQuery is a global, importing registers the plugins. Bundlers usually import jQuery as a module, so pass it to install(), which registers every adaptor you've imported (individual adaptors are available from formstone/jquery/<module>).

import $ from 'jquery';
import { install } from 'formstone/jquery';

install($);

Usage

The module APIs are mapped to match jQuery design patterns. Call the plugin with an options object to initialize it, or with a method name and its arguments to call an instance method.

$('.js-background').background({
  source: '...'
});

$('.js-background').background('load', '...');

Method calls return the first element's result when the method returns something (for example, the Promise from close()), and the jQuery collection otherwise, so they can be chained. Static methods such as defaults() are available as $.pluginname().

$('.js-modal').modal('close').then(() => {
  console.log('Closed');
});

$.lightbox('defaults', {
  ordinal: false
});

Events are native DOM events, so they can be handled with jQuery; event data is available on e.originalEvent.detail.

$('.js-tabs').on('tabs:activate', (e) => {
  console.log('Activated', e.target);
});

Plugins