Getting Started

Fireman is a javascript library used for building UI/UX filtering web pages.

It makes it easy to build a fully featured web page with many filters of any type. In addition, Fireman will handle their state, the browser url, restore filter’s state according to the URL, make HTTP requests and many features described bellow.

It can bind to user input controls like input fields, range sliders, datetime pickers and other elements. Automatically updates the browser url, make HTTP requests to a predefined endpoint, update page content, apply rules, reset filters to default state and many other functionalities as described in detail below.

Installation

Fireman is a pure js library and has no other dependencies. Originally it was written in typescript and compiled into js using the ts compiler.

The js library can be found here.

The extensions (adaptors etc..) used also in DEMO can be found here and here

Usage

In order to use Fireman instantiate the main object like this:

let fireman = new Fireman();

You can also provide configuration in fireman’s constructor.

Now, you are able to add filters, channels, configure, and build your UI/UX filtering mechanism.

Creating Filters

You can create filters using the update method of fireman or using attributes in HTML elements (DOM).

Below is an example of a Filter creation in both ways.

fireman.update({
  id: 1,
  name: "sku",
  type: 'text',
  state: [
    { target: "#SKUInputId" },
  ],
})

// all lines are equivalent 
<input filter name="sku" filter-id="1">
<input filter filter-name="sku" id="1">
<div filter filter-name="sku" id="1"><input ><div>

You can reference later this Filter using either its id or name.

let skuFilter = fireman.getFilterByNameOrId(1)
or
let skuFilter = _$('1');
or
let skuFilter = _$('sku');

_$() is Fireman’s selector for containers and filters.

Basic Rules

The update method of Fireman object is used both for the creation of containers and filters. You can provide a single object or an array of objects that can be filters or containers.

Below we present a valid creation example of three filters and one container.

fireman.update([{
  name: "price"
},
{
  name: 'disk',
  filters: [
      {
          name: "HDD",
          type: 'boolean',
      },
      {
          name: "SSD",
          type: 'boolean',
      }
  ]
}])

In the previous example, the 1st object is recognized as a Filter and the 2nd as a container because it have a filters array property.

Filter properties

Below we present all the properties that can be set during Filter creation both with JSON and DOM as shown below.

{
  id: 1
}

<input filter filter-id="1" type="checkbox" >
// or
<input filter id="1" type="checkbox" >

{
  name: "asus"
}

<input filter filter-name="asus" type="checkbox" >
// or
<input filter name="asus" type="checkbox" >

{
  name: "price",
  channels : ["_REQ", "_URL", "custom"]
}

<input filter name="price" channels="_URL, _REQ, custom" type="number" />

{
  name: "price",
  type: 'number'
}

// or for Array of numbers Filter

{
  name: "price",
  type: {
    encoderType: "number",
    isArray: true,
    size: 2
  }
}

<input filter name="price" channels="_URL, _REQ, custom" type="number" />
or
<input filter name="price" channels="_URL, _REQ, custom" filter-type="number" />
                        

//example 1
{
  name: "price",
  url: {
    infix: "_to_"
  }
}

//example 2
{
  name: "price",
  url: {
    type: "split",
    postfix: ["From", "To"],
  }
}

<!--example1-->
<div filter url='{"infix" : "_to_"}' name="price" >
  <input type="number">
  <input type="number">
</div>
<!--example2-->
<div filter url='{"type" : "split", "postfix" : ["From", "To"]}' name="price" >
  <input type="number">
  <input type="number">
</div>

//example 1
{
  name: "price",
  req: {
    infix: "_to_"
  }
}

//example 2
{
  name: "price",
  req: {
    type: "split",
    postfix: ["From", "To"],
  }
}

<!--example1-->
<div filter req='{"infix" : "_to_"}' name="price" >
  <input type="number">
  <input type="number">
</div>
<!--example2-->
<div filter req='{"type" : "split", "postfix" : ["From", "To"]}' name="price" >
  <input type="number">
  <input type="number">
</div>

//example1
{
  name: "page",
  type: "number",
  default: 0
}

//example2
{
  name: "price",
  type: {
    encoderType: "number",
    isArray: true,
    size: 2
  },
  default: [0,0]
}

<!--example1-->
<input filter name="page" default="0" type="number" />

<!--example2-->
<div filter name="price" default="[0, 0]">
  <input type="number" >
  <input type="number" >
</div>

//example1: Text Filter with one UI Element ("#SKU") bound to it.
{
  name: "sku",
  type: 'text',
  state: [
    { target: "#SKU" }
  ]
}

//example2: Array (of size 2) Filter with one target of two DOM elements
{
  name: "price",
  state: [
    { targets: ["#priceFromInput", "#priceToInput"] }
  ]
}

//example3: Text Filter with two targets. Those elements will be synchronized.
{
  name: "sku",
  state: [
    { target: "#skuInput1" },
    { target: "#skuInput2" },
  ]
}

<!--example1:Text Filter with one UI Element bound to it.-->
<input filter name="sku" type="text">

<!--example2:Array (of size 2) Filter with one target of two DOM elements-->
<div filter name="price">
  <input type="number">
  <input type="number">
</div>

<!--example3:Text Filter with two targets. One is in the declaration, 
the other has 'filter-state' and 'filter-id' attributes in order to reference the Filter. 
These input elements will be synchronized.-->
<input filter name="sku" filter-id="sku" type="text">
<input type="text" filter-id="sku" filter-state >

{
  name: "sku",
  type: 'text',
  reset: [
    { target: "#skuReset" }
  ]
}

<div filter filter-id="sku" name="sku">
  <input type="text">
  <button reset>x</button>
</div>
...
<button filter-reset filter-id="sku" >x</button>

{
  name: "page",
  type: "number",
  role: {
      type: "_PAGE"
  }
}

<input filter name="page" filter-role="_PAGE" />

{
  name: "gpu",
  content: [
    { target: "#gpuLabel1", text: "$fs GPU" },
  ]
}

<!--If the content is nested inside the 'filter' attribute, then the 'content' attribute is used.
Otherwise the 'content-id' and 'filter-id' attributes are used to reference the Filter.
In the 2nd case the text of the content is set in Filter declaration with the content-${contentid} attribute.
--><div filter name="gpu" content-selected="$fs GPU">
  <select>
    <option value="none">none</option>
    <option value="price-low-to-high">price (low to high)</option>
    ...
  </select>

  <span content="$fs GPU"></span>
</div>
...
<button content-id="selected" filter-id="gpu" type="button"></button>

{
  name: "description",
  filtering: {
    type: "contains"
  }
}

<div filter name="reviews" filtering="greaterthan">
  <input type="number" />
</div>

{
  name: "reviews",
  type: 'number',
  sensitivity: {
      type: 'number',
      diff: 2
  }
}

<input filter name="reviews" type="number" sensitivity='{"type" : "number", "diff" : 2}'>

Updating Filters

You can update any Filter’s name or content text using the update function of Fireman object. If a Filter with the same id is already present in Fireman then it will be updated.

As an example we create a container and two filters as shown below.

fireman.update([
  {
    id: "1",
    name: "reviews",
    content: [
      { id: 1, target: "#reviewsLabel", text: "$fs reviews" },
      { id: 2, target: "#reviewsLabel2", text: "reviews" },
    ],
    type: 'number'
  },
  {
    id: "1",
    name: 'c',
    filters: [
      {
        id: "2",
        name: "price",
        content: [
          { id: 1, target: "#priceLabel", text: "from $fs[0] to $fs[1]" },
        ],
        type: {
          encoderType: "number",
          isArray: true,
          size: 2
        }
      }
    ]
  }
]);

Then we can update them as follows:

fireman.update({
  id: "1",
  name: "reviews_gr"
});

fireman.update([
  {
    id: "1",
    name: "reviews_gr2"
  },
  {
    id: "2",
    name: "price_gr"
  },
  {
    id: "1",
    name: "priceContainer",
    filters: []
  }
]);

Configuration

You can configure Fireman by providing a JSON object in its constructor. A full configuration example is shown below.

{ 
  dataSource: {
    mode : 'client', // 'client', 'http', 'toggle'
    http: {
      baseUrl: "http://url/products", // AJAX request base URL 
    },
    client: {
      data: [
        {
            name: "lenovo model 1",
            description: "desc",
            ram: "8GB", 
            gpu: "nvidia",
            model: "lenovo", 
            sku: "12345", 
            price: 1320,
            weight: 900,
            quantity: 2,
            manufactured: '2021-09-05',
            availability: 'immediately' 
        }
        ...
        ..
        ]
    }
}

Under dataSource you can set where the data will come from. In http, Fireman will use the baseUrl to get data from the server whenever a Filter state is changed. In addition, under client you can set the data that are stored and retrieved from memory (without HTTP request). In that case, the data will be filtered by Fireman, depending on the current state of filters.

Lastly, the mode is used to instruct which strategy Fireman will use (‘client’, ‘http’, ‘toggle’).

The Fireman Interface

The Fireman object have the following capabilities.

Containers

Containers are objects that include Filters. There is no Filter without a container. If no Container is spesified during Filter creation then Fireman will assign one.

Their purpose is to organize similar Filters together. In addition, they also play a role when filtering data and serializing Filters to URL.

We can create an empty container as shown below:

fireman.update({
  id: 1,
  name: "model",
  filters : [] 
});

<div container id="1" name="model" >
</div>

or

<div container container-id="1" container-name="model" >
</div>

Additionaly, in the following example, we create a Container with two boolean Filters.

fireman.update({
  name: "model",
  filters : [{
    name: "asus",
    type: 'boolean'
  },
  {
      name: "lenovo",
      type: 'boolean'
  }] 
});

<div container name="model">
  <input filter name="asus" type="checkbox">
  <input filter name="lenovo" type="checkbox">
</div>

Filters

A Filter is a representation of User input/Parameter. It can have a UI element binded to it and can hold a single or multiple values as its state.

Usually it is binded to one or more UI elements. These elements can be of any type, from a simple checkbox to range pickers and google maps.

For example, a Filter can bind to a price range slider and hold as a state an Array of two numbers (from, to).

Below are Filter Types in more detail.

Types

Most of the simple types are already build-in, however custom implementations can also be provided.

The build-in types are the following:

Boolean

A boolean Filter can hold two states, true or false. A checkbox, for example, can be represented with a Filter of type boolean.

fireman.update({
  id: 1,
  name: "asus",
  type: 'boolean', // this can also be omitted.
  state : [ 
    target : '#check1' // the selector for the checkbox element
  ] 
});

<input filter filter-id="1" name="asus" type="checkbox" >

Text

A text filter holds a single string value as state. A text input can be represented by this kind of Filter.

fireman.update({
  id: 1, // optional
  name: "asus",
  type: 'text', // this can also be omitted
  state : [ target : '#textInput1'] // the selector for the input element
});

<input filter filter-id="1" name="asus" type="text" >

Number

Very similar with the text filter. Its only difference is that its internal representation of state is float.

fireman.update({
  id: 1, // optional
  name: "asus",
  type: 'number', // This can also be omitted
  state : [ 
    target : '#numberInput1'// the selector for the input element
  ] 
});

<input filter filter-id="1" name="asus" type="number" >

Datetime

The state of the Filter is type of javascript Date. An example is show below

fireman.update({
  name: "manufactured",
  type: "datetime",
  state : [ 
    target : '#datetimeInput1'// the selector for the input element
  ] 
})

<input filter name="manufactured" type="date">

Radio

A Radio Filter is a boolean Filter with a group assigned to it. Only one Filter in the same group can have a state value of true.

fireman.update({
  name: 'disk',
  filters: [
      {
          name: "HDD",
          channels: ["_URL"],
          type: 'boolean',
          group: 'diskType',
          state: [
              { target: "#diskHDDRadio" }
          ]
      },
      {
          name: "SSD",
          channels: ["_URL"],
          type: 'boolean',
          group: 'diskType',
          state: [
              { target: "#diskSSDRadio" }
          ]
      }
    ]
})

<div container name="disk">
    <label >HDD</label>
    <input filter filter-name="HDD" type="radio" name="diskType">
    <br>
    <label >SSD</label>
    <input filter filter-name="SSD" type="radio" name="diskType">
</div>

Array

A Filter can also hold multiple values. For example we may want to bind two input fields that hold the price range into an Array Filter of number values.

fireman.update({
  name: "price",
  type: {
    encoderType: "number",
    isArray: true,
    size: 2
  },
  state: [
    { targets: ["#priceFromInput", "#priceToInput"] },
  ],
})

<div filter name="price">
    <input type="number">
    <input type="number">
</div>

Sensitivity

Sensitivity is the minimum difference between a Filter’s current and future state that is required in order to be updated.

For example, a slider should be dragged 5 units or more in order to be considered an update and trigger HTTP request and page refresh. Similarly, with google maps the user needs to drag the map ‘further enough’ in order to trigger an update. This techniche minimizes reduntant request to the server.

Below we present an Array filter (named price) which has a sensitivity with diff of 10.

{
  name: "price",
  default: [301, 311],
  sensitivity: {
      type: 'number',
      diff: 10
  },
  type: {
      encoderType: "number",
      isArray: true,
      size: 2
  }
}

<div filter name="price" sensitivity='{"type" : "number", "diff" : 10}' default="[301, 311]">
  <input type="number" class="form-check-input">
  <input type="number" class="form-check-input">
</div>

Adaptors

An adaptor binds a Filter with a UI element.

For all the common UI elements (input, select, button) there are already build-in adaptors that are used.

However, a new adaptor can be provided in order to bind a Filter with a more complex element (e.g. with an element that is controlled by a js/jquery library ). In that case, the Adaptor will allow the Filter and the UI element to communicate with each other.

Below we present an Adaptor for the noUISlider jquery plugin. The NoUISliderAdaptor class extends from StateAdaptor.

class NoUISliderAdaptor extends StateAdaptor {

  size() {
      return 2;
  }

  identifier() {
      return 'nouislider';
  }

  encoderType() {
      return 'number';
  }

  init() {
      let noUISliderIntAdaptorSlider = this.target;
      noUiSlider.create(noUISliderIntAdaptorSlider, this.params);
  }

  sync(values, defaultValue) {
      if (values[0] !== 'undefined')
          this.target.noUiSlider.set([values[0], null]);
      if (values[1] !== 'undefined')
          this.target.noUiSlider.set([null, values[1]]);
  }

  bind() {
      const self = this;
      this.target.noUiSlider.on('set', function (values, handle) {

          var value = values[handle];

          self.listener.changeIndexedStateRequested(self, value, handle);

      });
  }
}

You can register a new adaptor to Fireman like this:

fireman.register(NoUISliderAdaptor);

As with the previous example, an adaptor needs to override the following methods:

Roles

A Role gives to a Filter a different behaviour regarding certain operations.

For example, a Filter with _SORTING role, sorts the data in case of client data retrieval.

Below are three build-in roles that Fireman supports, and can be assigned to any Filter.

Below we present various Filters with Roles assigned to them.

fireman.update([{
    name: "page",
    type: "number",
    role: {
        type: "_PAGE",
    },
    default: 0,
    channels: ["_REQ", "_URL"],
},
{
    name: "pageSize",
    type: "number",
    role: {
        type: "_PAGE_SIZE",
    },
    default: 3,
    channels: ["_REQ"],
}, {
    name: "sortbyPrice",
    type: "text",
    channels: ["_REQ", "_URL"],
    default: "none",
    role: {
        type: "_SORTING",
        rules: [
            {
                value: "price-low-to-high",
                key: "price",
                order: "asc",
            },
            {
                value: "price-high-to-low",
                key: "price",
                order: "desc",
            }
        ]
    }
}]);

Serializers

A Serializer is used to convert a Filter to a string that is used in browser’s URL and/or in HTTP request.

There are already build-in serializers (filter-state, split, container-filter) as shown below:

{
  name: "price",
  url: {
    type: "filter-state",
    infix: "-"
  },
  req: {
    type: "filter-state",
    infix: "-"
  },
}

<div filter name="price" 
  url='{"type" : "filter-state", "infix" : "-"}'
  req='{"type" : "filter-state", "infix" : "-"}'>
  <input type="number">
  <input type="number">
</div>

{
  name: "price",
  url: {
    type: "split",
    postfix: ["From", "To"],
  },
  req: {
    type: "split",
    postfix: ["From", "To"],
  },  
}

<div filter name="price" 
  url='{"type" : "split", "postfix" : ["From", "To"]}'
  <input type="number" 
  <input type="number" 
</div>

{
  name: 'model',
  filters: [
    {
      name: "asus",
      url: {
        type: "container-filter"
      },
      req: {
        type: "container-filter"
      }
    },
    {
      name: "lenovo",
      url: {
        type: "container-filter"
      },
      req: {
        type: "container-filter"
      }
    }
  ]
}

<div container name="model"
  <input filter name="asus" type="checkbox"
    url='{"type" : "container-filter" }' req='{"type" : "container-filter" }'
  <br>
  <input filter name="lenovo" type="checkbox"
    url='{"type" : "container-filter" }' req='{"type" : "container-filter" }'
</div>

Reset

We can reset a Filter to its default state either by calling reset() on Filter object or using DOM.

fireman.update({
  name: "sku",
  type: 'text',
  state: [
    { target: "#SKU" },
  ],
});

let skuFilter = fireman.getFilterByIdOrName('sku');
skuFilter.reset();

{
  name: "sku",
  type: 'text',
  reset: [
    { 
      target: "#skuReset" // button with selector #skuReset
    }
  ]
}

<div filter name="sku"
  <input type="text" >
  <!--in case the reset-element is nested inside the filter we add the 'reset' attribute-->
  <button reset>X</button>
</div>
..
..
<!--In case the element is outside the filter element,
  we provide a filter-id as filter's name or id and a reset attribute -->
<button filter-id="sku" reset>X</button>

Channels

A Channel is used to notify listeners every time a state of a Filter is changed.

There are already 2 build-in channels. One is used for browser URL manipulation and the other for the HTTP AJAX request.

We can configure a Filter to update the Browser’s URL by adding to its channels the ‘_URL’ channel. Similarly, a Filter can trigger a new HTTP request every time its state is changed, by adding to its channels the ‘_REQ’ channel.

Other custom channels can also be used.

During Filter creation we can set which channels the Filter will notify. Below is an example

fireman.update([
  {
    name: "sku",
    type: 'text',
    channels: ["_URL", "c1", "c2"],
    state: [
      { target: "#SKU" },
    ],
  },
  {
    name: "model",
    filters: [
      {
        name: "asus",
        type: 'boolean',
        channels: ["_URL", "_REQ", "c1"],
        state: [
          { target: "#asusCheck" },
        ],
      }
    ]
}]);

<div filter name="sku" channels="_URL,c1,c2">
  <input type="text">
</div>
<div container name="model" >
  <input filter name="asus" type="checkbox" channels="_URL,_REQ,c1">
</div>

In the above example we create two Filters with various channels each.

The channels _URL and _REQ are the build-in channels for Browser URL manipulation and HTTP request respectively.

The channels c1 and c2 are created dynamically.

Next, we can register listeners for the c1 channel like this:

class C1Listener extends ChannelListener {

  protected filterStateChangedHandler(channel: Channel, filter: Filter, onSuccess: any, onError: any) {
      
  }

  protected filterResetHandler(channel: Channel, filter: Filter, onSuccess: any, onError: any) {
     
  }

}

Finally, we register the C1Listener to Fireman object

let c1Listener = new C1Listener();
fireman.subscribe('c1', c1Listener);

Rules

A Rule can be applied to a Filter in order to make an automated change depending on a condition.

For example, we can reset a Filter if any other Filter’s state is changed. This is a common senario when you want to reset the paging every time a Filter is changed.

Below we show how to create a Rule that resets the Paging when the price Filter is changed.

fireman.rule().whenStateChangesOf(x => x.getFilterByNameOrId("price"))
  .thenResetFor(x => x.getFilterByNameOrId('page'))

Another example is to set the state of a Filter to a specific value like this:

fireman.rule().whenStateChangesOf(x => x.getFilterByNameOrId('manufactured'))
    .thenChangeStateFor(x => x.getFilterByNameOrId("weight")).to([100, 2000]);

Content

You can use fireman expressions in order to update text in the HTML page automatically.

There are cases where we want to update the page content when a Filter’s state or other property is also changed. Below we present an example of binding two HTML elements as contents in a text Filter named ‘gpu’.

{
  name: "gpu",
  content: [
    { target: "#gpuLabel1", text: "$fs GPU" },
    { target: "#gpuLabel2", text: "$fn | upper" },
  ]
}

<div filter name="gpu">
  <input type="text">
  <span content="$fs GPU"></span>
  <!-- if content is inside filter attribute then it can be parsed and rendered automatically -->
</div>
...
<label content="$fn | upper" filter-id="gpu"></label>
<!-- if content is outside filter attribute element then it needs to have a reference to the filter -->

The ‘$fs GPU’ will be converted to filter’s state concatenated with the string ‘GPU’ (with an empty space between them). The result will be written in the HTML element with selector #gpuLabel1.

The ‘$fn | upper’ will be converted to filter’s name and using the pipe ‘upper’ will be converted to string ‘Gpu’. The result will be written in the HTML element with selector #gpuLabel2.

Every time the Filter is updated, its contents will also be updated automatically.

Below we present some variables a Fireman expression can have.

In addition, Fireman expressions have syntax which makes easier to output content based on Filter’s states. Fireman uses curly brases { }, ? and ! to model conditions.

Results

Every time a Filter state changes or when the refresh method is called, Fireman makes an HTTP request (or gets the data from memory). Those results are accesible to the client with a ResultsListener. This listener is registered in Fireman instance as shown below.

class ResultsComponent extends ResultsListener {

  onBeforeHandler(url) { }

  onErrorHandler(err) { }

  resultsReceivedHandler(data) { }

  onCompletedHandler() { }

}

fireman.subscribeResultsListener(new ResultsComponent());

The ResultsListener overrides the following methods:

Localization

Using the capability of updating Filters you can change the names of the Filters dynamically.

Also using fireman expressions for displaying filter names in the HTML those names will update automatically.

Support

If this documentation doesn’t answer your questions, please send us an email at softwareparticles [at] gmail.com

If you want something more specific you can check the packages below.

Packages

If any specific support is needed, a new feature development or a full js package of various plugins (adaptors) you can choose the approprtiate packages below that fit your needs.