FormulaJS

Generate formulas on the fly

Doc

• Installation

Simply import formula.min.js & formula.min.css into your HTML by downloading it or using a CDN.

<link rel="stylesheet" href="https://unpkg.com/@zenoo/[email protected]/formula.min.css">
<script src="https://unpkg.com/@zenoo/[email protected]/formula.min.js"></script>

• Demo

A demo is available on this JSFiddle

• Usage

Initialize your Formula by specifying a wrapper and some additional options:

const formula = new Formula("#wrapper");
// OR
const formula = new Formula(wrapperElement);
// OR
const formula = new Formula(wrapperElement, options);

You can change the cursor position by clicking on an existing tag or pressing the left/right arrow keys.

• Options

The available options and their default values are:

{
  separators: [' ', 'Enter'], // Characters that will process the inputted String into a new tag
  closers: '+-*/()%^',        // A chain of characters that will always trigger a new separate tag
  lang: {                     // Dictionary holder (The attribute 'field' is the only one needed right now)
    field: 'Custom Field'
  },
  customFields: undefined,    // Custom Fields to display, see below
  onFieldExpand: function(field){ ... } // Callback REQUIRED if you use the 'children: true' Field property. Expects a Field-like object to be returned
  onUpdate: function(value){ ... } // Callback triggered whenever the Formula gets updated. It's first parameter is the String representation of the Formula
}

• Custom Fields

If you want to allow the user to pick from some predefined properties, you can use the customFields attribute:

// Basic usage
const customFields = {
  firstField: {
    name: "Pretty name",
  },
  whatever: {
    name: "Prettier name",
  },
};

// Tree-like usage (you can deep-nest)
const customFields = {
  firstField: {
    name: "Pretty name",
    children: {
      nestedField: {
        name: "Hey ya",
      },
    },
  },
  whatever: {
    name: "Prettier name",
  },
};

// Dynamic tree-like usage
const customFields = {
  firstField: {
    name: "Pretty name",
    children: true, // When using a Boolean as the children value, you have to use the 'onFieldExpand' callback, see below
    customData: {
      // This optional object will be returned as the second argument of the 'onFieldExpand' callback
      whateverIWant: ":D",
    },
  },
  whatever: {
    name: "Prettier name",
  },
};

• Dynamic fields

Using children: true as a Field property forces you to specify the onFieldExpand callback. It will be called every time a new subtree is opened by the user.

• The first parameter of this callback returns the field Node the user opened:

<li class="formula-js-field" data-field="test" data-name="Hey">Hey<span class="children"></span></li>

The data-field and data-name attribute will allow you to build the subtree accordingly.

• The second parameter of this callback returns whatever you passed inside the customData attribute of your Field

The onFieldExpand callback expects a Promise that resolves with a Field-like object to be returned, which will be used to build the subtree.

// Example
onFieldExpand: (field) => {
  const path = field.getAttribute("data-field"),
    children = grabChildren(path);

  return Promise.resolve(
    children.map((child) => ({
      name: prettyName(child),
      children: hasChildren(child),
    }))
  );
};

• Methods

The full documentation is available on https://zenoo.github.io/FormulaJS/.

• .get()
• .set(formulaString)
• .add(formulaString)
• .addField(fieldPath)
• .clear()
• .destroy()

Authors

• Zenoo - Initial work - Zenoo.fr