DEV Community: Romain Lebesle

How to build a Grid system in JavaScript

Romain Lebesle — Fri, 29 Oct 2021 23:47:36 +0000

While making my connect four in JavaScript I thought it would be great to build a reusable and scalable grid system.

That's what I'm sharing with you today.

So first, let's go through the basics, exactly how can we define a grid system?

We could say that a grid is made of cells that are organized into rows.

Grid

So let's start from here and make a Grid class that will hold our rows:

grid.js

class Grid {

  constructor() {
    this._rows = {}
  }

  /**
   * @readonly
   * @type {object}
   */
  get rows() {
    return this._rows
  }

}

Here, my rows variable type is an object but you could also use an array.

Row

Now that we have our grid class ready, let's create a Row class:

row.js

class Row {

  /**
   * @param {number} x
   */
  constructor(x) {
    this._x = x
    this._cells = {}
  }

  /**
   * @readonly
   * @type {object}
   */
  get cells() {
    return this._cells
  }

  /**
   * @readonly
   * @type {number}
   */
  get x() {
    return this._x
  }

}

As you can see Row is in fact an abstraction of x in our grid. Just like the Grid class holds rows our Row class holds cells.

From here the next step would be to add cells to the grid, so let's create a method inside our Grid class that'll do just that.

Adding cells to our grid

grid.js

/**
 * @param {number} x
 * @param {number} y
 * @returns {Cell}
 */
addCell(x, y) {
  const cell = new Cell(x, y)
  if(!this.rows[cell.x]) {
    this.rows[cell.x] = new Row(cell.x)
  }
  cell._row = this.rows[cell.x]
  this.rows[cell.x].cells[cell.y] = cell
}

Now we can do something like:
demo.js

const grid = new Grid()
grid.addCell(0, 0)

Now that we're good with the row part let's dive into the cell part.

Cell

cell.js

class Cell {

  /**
   * @param {number} x
   * @param {number} y
   */
  constructor(x, y) {
    this._x = x
    this._y = y
  }

  /**
   * @readonly
   * @type {number}
   */
  get x() {
    return this._x
  }

  /**
   * @readonly
   * @type {number}
   */
  get y() {
    return this._y
  }

}

demo.js

const grid = new Grid()
grid.addCell(0, 0)

Let's build a 4x4 grid then.

4x4 grid

demo.js

const size = 4
const grid = new Grid()
for(let x = 0; x < size; x++) {
  for(let y = 0; y < size; y++) {
    grid.addCell(x, y)
  }
}

There are lots more that we could do but let's save it for later...

Also, check out the library I made out of this grid system: https://github.com/thoughtsunificator/grid.

userinterface.js - Small front-end library

Romain Lebesle — Mon, 18 Oct 2021 19:55:54 +0000

userinterface.js is a front-end library built around the idea that logic relating to how the visual looks and how the visual works should be distinguished.

Getting started

Installing

Scaffold

See https://github.com/thoughtsunificator/userinterface.js-skeleton.

Standalone

git submodule add https://github.com/thoughtsunificator/userinterface.js.git lib/userinterface.js

Add userinterface.js to the head section of your web page:

<script src="./lib/userinterface.js/src/userinterface.js"></script>

Model

A Model is an object representation of a Node.
It has three required properties depending on the method: name, method and properties or callback,

The name property will be the identifier of your model it will be used whenever you need to run your model but also to associate a binding to your model.
The method property will describe how your model should be ran.
The properties and callback properties will contain the properties of your Elements.

A Model often goes along with a Binding and an Object.

Basic model

Here we create a model named simplemodel using the method appendChild it has a one LI element child. LI has the className simplemodel and textContent Myfirst simple model.
This model uses the textContent, className and tagName propertie however you might use any Element properties the DOM API offers.

src/userinterface/simplemodel.js

UserInterface.model({
  name: "simplemodel",
  method: UserInterface.appendChild,
  properties: {
    tagName: "li", // required
    className: "simplemodel",
    textContent: "My first simple model"
  }
});

UserInterface.runModel("simplemodel", { parentNode: document.querySelector("ul") });

Output:

<ul>
  <li class="simplemodel">My first simple model</li>
</ul>

Children

In the previous example we created a simple model, but what if we wanted to do more and add some children to it ?
The children property is here for that, it is an Array where you can specify child elements.

src/userinterface/children.js

UserInterface.model({
  name: "children",
  method: UserInterface.appendChild,
  properties: {
    tagName: "div",
    className: "model",
    children: [
      {
        tagName: "div",
        className: "child",
        textContent: "My first child"
        // and so on..
      }
    ]
  }
});

UserInterface.runModel("children", { parentNode: document.body });

Output:

<body>
  <div class="model">
    <div class="child">My first child</div>
  </div>
</body>

Callback

Models are required to have either the properties property or callback property, but exactly what does the callback property do ?
It is used when you want to echo some data in your model.

For example here, we have a model called echomodel that has the callback property. This property works the same as the properties property does except that an extra step is added before your model is ran.
The callback will return a properties object accordingly to the data you passed through runModel.

src/userinterface/echomodel.js

UserInterface.model(
  name: "echomodel",
  method: UserInterface.appendChild,
  callback: data => ({
    tagName: "p",
    className: "echomodel",
    textContent: "My "+data.text+" model"
  })
);

UserInterface.runModel("echomodel", { parentNode: document.body, data: {"text": "echo" } });

Output:

<p class="echomodel">My echo model</p>

Processed properties

children Add children to an element

Binding

A Binding is a callback function that, when bound to a model, is automatically called whenever the model has ran.
Bindings will make your models more alive, an example of that would be adding an event listener to your model, that is the place where you will be doing it.

You can also do much more such as using event listeners to connect all of your models together!

A Binding is way to give life to your models enabling them to do things whenever their respective method is executed.
That means if you want to add a listener to an Element that's where you will be doing it.

In this example we will change the textContent of our model root element.

src/userinterface/button.js

UserInterface.model({
  name: "button",
  method: UserInterface.appendChild,
  properties: {
    tagName: "button"
  }
});

UserInterface.bind("button", function(element) {
  element.textContent = "bound";
});

UserInterface.runModel("button", { parentNode: document.body });

Output:

<button>bound</button>

Methods

appendChild Append your model to the target
insertBefore Insert your model before the target
removeElement Remove the target
replaceElement Replace the target with your model
updateElement Update the target according to your model
wrapElement Wrap the target inside your model
removeListeners Remove the listeners of the target

Objects

Objects are the backbone of your models they will store and manipulate data for your Binding.
That's where you want to hide the complicated stuff.

Listeners

Listeners enable intercommunication for your models.

Main object

You usually wants to have a main object that you will pass to most of your models so that they communicate with each other through a central.

Note that you are not forced to have one and you could have multiple observables and still be able to handle inter-model communication.

Most of the time we call it application.

Listening to events

In this example we are creating and running a model called myModel that will listen for the event greeting on through the application context.

A Context represent a reserved area (a channel) that events will be bound to, they're often represented as an instance of an object but could pretty much be anything.

src/userinterface/my-model.js

UserInterface.model({
  name: "myModel",
  method: UserInterface.appendChild,
  properties: {
    tagName: "div"
  }
});
UserInterface.bind("myModel", function(element, application) {

  UserInterface.listen(application, "greeting", async (message) => {
    console.log(message)
  })

});

const application = {}

UserInterface.runModel("myModel", { parentNode: document.body, bindingArgs: [application] });

For the moment we are only listening to the greeting event, we haven't announced anything to it yet.

Announcing events

In the previous example we setup a greeting listener on application.

Now, let's try to announce to the event.

src/userinterface/another-model.js

UserInterface.model({
  name: "anotherModel",
  method: UserInterface.appendChild,
  properties: {
    tagName: "div"
  }
});
UserInterface.bind("anotherModel", function(element, application) {

  UserInterface.announce(application, "greeting", "Hello!");

});

const application = {}

UserInterface.runModel("myModel", { parentNode: document.body, bindingArgs: [application] });
UserInterface.runModel("anotherModel", { parentNode: document.body, bindingArgs: [application] });

If everything went well you should be able see a Hello! log message in the console.

Removing event listeners

Sometimes you might want your model to be dynamically added and removed, meaning that it will be added upon an action and removed upon another action.

Usually what you want to do is to create _listener variable and push all the listeners to this array and then remove them as needed using forEach for example.

In this example, we create a listener message and remove it whenever the event done is emitted.

UserInterface.bind("myDynamicModel", function(element, application) {

  const _listeners = []

  _listeners.push(UserInterface.listen(application, "message", async data => {
    console.log(data)
  }))

  _listeners(UserInterface.listen(application, "done", async () => {
    _listeners.forEach(listener => UserInterface.removeListener(listener))
  }))

})

API

You can read the API by visiting https://thoughtsunificator.github.io/userinterface.js.

Common errors

Cannot set property 'binding' of undefined

UserInterface.js could not find the model specified when calling UserInterface.bind.

Cannot destructure property 'method' of 'model' as it is undefined.

UserInterface.js could not find the model specified when calling UserInterface.runModel.

Feel free to open an issue if you need assistance.

Collection

userinterface.js also provides a collection that contains a few basic models to get you started. See https://github.com/thoughtsunificator/userinterface.js-collection.

Extensions

See https://github.com/topics/userinterface-js-extension.

Demos

See https://github.com/topics/userinterface-js-demo.

domodel - ES6 Modules based front-end library

Romain Lebesle — Mon, 18 Oct 2021 19:50:12 +0000

domodel is front-end library that organizes the user interface into models (look) and bindings (behavior) it follows the principle of separation of concerns, it also introduce elements of the observable pattern for the communication between the different parts of the user interface.

Getting started

Installing

Setup a new project

npx create-domodel-app [name]

Setup as a dependency to an existing project

npm install domodel

Model

A model is a JSON representation of a DOM Element.

Let's take this model for example:

export default {
  tagName: "button"
}

That would the equivalent of:

const button = document.createElement("button")

A model with children:

export default {
  tagName: "div",
  children: [
    {
      tagName: "h2",
      identifier: "headline",
      textContent: "Unveil a new world"
    }
  ]
}

Notice the textContent property. You can set any Element properties in this fashion.

The identifier property is a model property.

The term model will later be used to refer to both the model and its Binding to make it simpler.

Properties

Most properties listed in your model are defined at the Element level.

However custom properties are not set on the Element as they have unusual behaviors they are treated differently:

tagName - String - Passed to createElement
children - Array - To add children to an Element
identifier - String - To save and retrieve a Node
model - Model - Specify the model that should be ran
binding - Binding - Specify the Binding to use when running the model (model property must be set)
properties - Object - Specify the arguments to pass along the Binding (binding property must be set)

Binding

Now that we're able to create models, we will learn how to turn them into a real Element ?

Properties

These properties are available from within the the instance of a Binding:

properties Properties passed along when instancing a binding.
root Root Element of your model.
identifier Hosts individual Element previously tagged in the definition of the model (see Model properties).

Adding models to the DOM and managing them

We might know how to define models however they wont simply be added by defining them alone.

For that we have to use the Core.run method provided by DOModel object and tell it how to add them.

The first step in your project would be create or edit the main.js in src/, it is the entry point module that is defined in your index.html.

src/main.js

import { Core } from "domodel" // first we're importing DOModel

// It is preferred to use camel case and suffix model names with "Model" and binding names with "Binding" such as: RectangleModel and RectangleBinding.
import Model from "./model/model.js" // the model we defined earlier, it is our super model
import ModelBinding from ".model/model.binding.js" // the binding we will be defining .bindinglater

window.addEventListener("load", function() { // we only add the
  Core.run(Model, {
    method: Core.METHOD.APPEND_CHILD, // This is the default method and will append the children to the given parentNode.
    binding: new ModelBinding({ myProp: "hello :)" }), // we're creating an instance of our binding (which extends the Binding class provided by DOModel) and passing it to the run method.
    parentNode: document.body // the node we want to target in this case it is the node where we want to append the child node using appendChild.
  })
})

Now that your main.js is created let's create your first Binding:

src/model/model.binding.js

import { Core } from "domodel" // you could import the library again and run yet another model inside this model

class ModelBinding extends Binding {

  onCreated() {
    const { myProp } = this.properties

    console.log(myProp) // prints hello

    // access your model root element through the root property: this.root

    // access identifier with the identifier property:

    this.identifier.headline.textContent = "The new world was effectively unveiled before my very eyes"

    // you might even run another model inside this model
  }

}

export default ModelBinding

Methods

APPEND_CHILD Append your model to parentNode
INSERT_BEFORE Insert your model before parentNode
REPLACE_NODE Replace parentNode with your model
WRAP_NODE Wrap parentNode inside your model
PREPEND Insert your model before the first child of parentNode

They are available through Core.METHOD.

Observable

An Observable is a way for your models to communicate with each other.

src/object/observable-example.js

import { Observable } from "domodel"

class ExampleObservable extends Observable {

  // you can have a constructor

  // getter setter...

  // or even better, you could have methods.

}

export default ExampleObservable

Listening to events

EventListener

Here we associate the EventListener with our current binding and give it properties.observable as the observable to register the events to.

src/model/model.binding.js

import { Observable, Binding } from "domodel"

import ModelEventListener from "/model/model.event.js"

class ModelBinding extends Binding {

  constructor(properties) {
    super(properties, new ModelEventListener(properties.observable))
  }

}

export default ModelBinding

Any method inside an EventListener is automatically registered as a listener to the given observable.

src/model/model.event.js

import { EventListener } from "domodel"

class ModelEventListener extends EventListener {

  message(data) {
    console.log(data)
  } 

}

export default ModelEventListener

observable.listen

Useful when you want to listen to other parts your UI.

src/model/model.binding.js

import { Observable, Binding } from "domodel"

class ModelBinding extends Binding {

  onCreated() {

    const observable = new Observable()

    observable.listen("message", data => {
      console.log(data)
    })

  }

}

export default ModelBinding

Emitting events

src/model/model.binding.js

import { Observable } from "domodel"

class ModelBinding extends Binding {

  onCreated() {

    const observable = new Observable()

    observable.emit("message", { /* data go here */ })

  }

}

export default ModelBinding

Running your model:

import { Core, Observable } from "domodel"

import Model from "/model/model.js"
import ModelBinding from "/model/model.binding.js"

const observable = new Observable()

Core.run(Model, { parentNode: document.body, binding: new ModelBinding({ observable }) })

Advanced

Nesting models

Method 1 - Import

src/model/application.js

import Model from "./model.js"

export default {
  tagName: "div",
  children: [
    Model
  ]
}

Method 2 - Binding

src/model/application.binding.js

import { Core } from "domodel"

import Model from "./model.js"
import ModelBinding from "./model.binding.js"

class extends Binding {

  onCreated() {
    Core.run(Model, { parentNode: this.root, binding: new ModelBinding() })
  }

}

export default class

Method 3 - "model" property

src/model/application.js

import Model from "./model.js"
import ModelBinding from "./model.binding.js"

export default {
  tagName: "div",
  children: [
    {
      model: Model,
      binding: ModelBinding // optionnal
      properties: {} // optionnal
      identifier: "model" // optionnal
      // Any other property is not handled.
    }
  ]
}

Referencing to nested models

In some cases, you might want to reference to a nested model.

You can use the identifier, it will reference to an instance of the Binding you specified, in this case it would be an instance of ModelBinding.

Accessing the reference:

src/model/model.binding.js

import { Binding } from "domodel" // you could import the library again and run yet another model inside this model

class extends Binding {

  onCreated() {

    console.log(this.identifier.model) // returns an instance of ModelBinding
    // You could access the root element of the nested model through:
    console.log(this.identifier.model.root)
    // and much more...

  }

}

export default class

API

See https://thoughtsunificator.github.io/domodel.

Extensions

See https://github.com/topics/domodel-extension.

Demos

See https://github.com/topics/domodel-demo.