Autolayout.js

Apple's Auto Layout and Visual Format Language for javascript (using cassowary constraints)

Generate Convert Improve

Install / Use

/learn @IjzerenHein/Autolayout.js

About this skill

Quality Score

0/100

README

THIS REPOSITORY IS NO LONGER MAINTAINED

Looking for an alternative that is maintained? Please have a look at lume/autolayout.

If you are interested in maintaining this repository (and taking ownership of it), please reach out to me here.

AutoLayout.js implements Apple's Auto Layout and Visual Format Language in Javascript. Auto layout is a system which lets you perform lay out using mathematical relationships (constraints). It uses the awesome Cassowary.js library to do the actual constraint resolving and implements Apple's constraint system and Visual Format Language (vfl) on top of that. It supports the Extended VFL syntax, including view-stacks and z-indexing.

var constraints = AutoLayout.VisualFormat.parse([
  'H:|[view1(==view2)]-10-[view2]|',
  'V:|[view1,view2]|'
], {extended: true});
var view = new AutoLayout.View({constraints: constraints});
view.setSize(400, 500);
console.log(view.subViews.view1); // {left: 0, top: 0, width: 195, height: 500}
console.log(view.subViews.view2); // {left: 205, top: 0, width: 195, height: 500}

Layouts can be previewed and debugged using the Visual Format Editor:

(click image to open the editor)

Index

THIS REPOSITORY IS NO LONGER MAINTAINED

Getting started

AutoLayout.js is an abstract library for integrating Auto Layout and VFL into other javascript technologies. It provides a simple API and programming model that you can use to build your own auto layout and VFL solution. A simple example of this is, is using position: absolute; to lay out DOM elements. A more elaborate example of this is the Visual Format Editor, which is built using famo.us and famous-flex. AutoLayout.js is written in ES6 and contains transpiled distribution files.

Installation

Install using npm or bower:

npm install autolayout

bower install autolayout

Include the library in your project:

<head>
  <script type="text/javascript" src="<path-to-autolayout.js>/dist/autolayout.js"></script>
</head>

var AutoLayout = window.AutoLayout;

Or when using a bundler like webpack or browserify, use:

var AutoLayout = require('autolayout.js');

(when using the 'src/' directory, do make sure plugins for transpiling es6 files are installed!)

Using the API

To parse VFL into constraints, use:

try {
  // The VFL can be either a string or an array of strings.
  // strings may also contain '\n' which indicates that a new line of VFL will begin.
  var constraints = AutoLayout.VisualFormat.parse([
    '|-[child(==child2)]-[child2]-|',
    'V:|[child(==child2)]|',
  ]);
} catch (err) {
    console.log('parse error: ' + err.toString());
}

A View is the main entity onto which constraints are added. It uses the cassowary SimplexSolver to add relations and variables. You can set the size of the view and other properties such as spacing. When constraints are added it automatically creates so called "sub-views" for every unique name that is encountered in the constraints. The evaluated size and position of these sub-views can be accessed through the .subViews property.

// Create a view with a set of constraints
var view = new AutoLayout.View({
    constraints: constraints, // initial constraints (optional)
    width: 100,               // initial width (optional)
    height: 200,              // initial height (optional)
    spacing: 10               // spacing size to use (optional, default: 8)
});

// get the size and position of the sub-views
for (var key in view.subViews) {
    console.log(key + ': ' + view.subViews[key]);
    // e.g. {
    //   name: 'child1',
    //   left: 20,
    //   top: 10,
    //   width: 70,
    //   height: 80
    // }
}

By changing the size, the layout is re-evaluated and the subView's are updated:

view.setSize(300, 600);

// get the new size & position of the sub-views
for (var key in view.subViews) {
    console.log(key + ': ' + view.subViews[key]);
}

Instead of using VFL, you can also add constraints directly. The properties are identical to those of NSLayoutConstraint. To constrain view1 to its parent view, use null for view2.

view.addConstraint({
    view1: 'child3',
    attr1: 'width',    // see AutoLayout.Attribute
    relation: 'equ',   // see AutoLayout.Relation
    view2: 'child4',
    attr2: 'width',    // see AutoLayout.Attribute
    constant: 10,
    multiplier: 1
});

API Documentation

The API reference documentation can be found here.

Examples

Extended Visual Format Language (EVFL)

Apple's Visual Format Language prefers good notation over completeness of expressibility. Because of this some useful constraints cannot be expressed by "Standard" VFL. AutoLayout.js defines an extended syntax (superset of VFL) which you opt-in to use. To enable the extended syntax, set option extended to true when parsing the visual format:

var evfl = '|-[view1(==50%)]';
var constraints = AutoLayout.VisualFormat.parse(evfl, {extended: true});

Language features

Proportional size (|-[view1(==50%)])
Operators (|-[view1(==view2/2-10)]-[view2]-|)
Attributes (V:|[view2(view1.width)])
Z-ordering (Z:|-[view1][view2])
Equal size spacers/centering(|~[center(100)]~|)
View stacks (V:|[column:[header(50)][content][footer(50)]]|)
View ranges (spread operator) (H:[view1..8(10)]|)
Multiple views (Z:|[background][text1,text2,text3]|)
Multiple orientations (HV:|[background]|)
Disconnections (right/bottom alignment) (|[view1(200)]->[view2(100)]|)
Negative values (overlapping views) (|[view1]-(-10)-[view2]|)
Explicit constraint syntax (C:view1.centerX(view2.centerX))
Comments ([view1(view1.height/3)] // enfore aspect ratio 1/3)

Proportional size

To make the size proportional to the size of the parent, you can use the following % syntax:

|-[view1(==50%)]    // view1 is 50% the width of the parent (regardless of any spacing)
[view1(>=50%)]      // view1 should always be more than 50% the width of the parent

Operators

Operators can be used to create linear equations of the form: view1.attr1 <relation> view2.attr2 * multiplier + constant.

Syntax:

(view[.{attribute}]['*'|'/'{value}]['+'|'-'{value}])

To, for instance, make the width or height proportional to another view, use:

|-[view1(==view2/2)]-[view2]-|  // view1 is half the width of view2
|-[view1(==view2*4-100)]-[view2]-|  // view1 is four times the width minus 100 of view2

Attributes

In some cases it is useful to for instance make the width equal to the height. To do this you can use the .{attribute} syntax, like this:

|-[view1]-|
V:|-[view1(view1.width)]

You can also combine with operators to for instance enforce a certain aspect ratio:

V:|-[view1(view1.width/3)]

Supported attri

Related Skills

node-connect

336.5k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

82.9k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

336.5k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

commit-push-pr

82.9k

Commit, push, and open a PR