Concert.js

A Basic Explanation of Applicators

The purpose of an applicator function is to take the value applicable to the present frame and apply it to the object being manipulated by the animation.

Because Concert.js can be used to animate just about anything, it is necessary to be able to apply all kinds of values to all kinds of objects. The values might be CSS styles, or innerHTML text content, for instance, or some kind of complex, user-defined object that needs to be mapped in a custom way to whatever is being manipulated in the animation sequence.

The Built-in Applicator Functions

There are three built-in applicator functions:

• Concert.Applicators.Property: The Property applicator simply takes whatever value is passed to it and applies it to the target object feature, treating the feature as a property of the object. That is, if the object being animated is an object captionDiv, the target feature is "innerHTML", and the value being applied is "caption text", it will simply result in the equivalent of the following value assignment:
  captionDiv.innerHTML = "caption text";
  The Property applicator is the default, used if none is specified and the default isn't changed.
• Concert.Calculators.Style: The Style applicator takes the value passed to it and applies it to the target object feature, treating the feature as a CSS style property. That is, if the object being animated is is an object colorDiv, the target feature is "background-color", and the value being applied is "rgb(255, 0, 0)", it will result in the equivalent of the following value assignment:
  colorDiv.style.backgroundColor = "rgb(255, 0, 0)";
  Note that style properties are normalized automatically, so you can specify target features which are styles using either their CSS-style name (e.g. background-color) or the equivlant JavaScript property-style name (e.g. backgroundColor).
• Concert.Calculators.SVG_ElementAttribute: The SVG_ElementAttribute applicator takes the value passed to it and applies it to the target object feature, treating the feature as an attribute of the object. That is, if the object being animated is an object svgRect, the target feature is width, and the value being applied is 90, it will result in the equivalent of the following value assignment:
  svgRect.setAttribute("width", 90);

Below is an example where you can see all three in use:

const WideningDiv = document.getElementById("WideningDiv"),
  WideningSvgRect = document.getElementById("WideningSvgRect"),
  CaptionBox = document.getElementById("Caption");

let animations =
  [
    {
      target: WideningDiv,
      feature: "width",
      unit: "px",
      applicator: Concert.Applicators.Style,
      calculator: Concert.Calculators.Linear,
      keyframes: { times: [0, 1500], values: [100, 480] }
    },

    {
      target: WideningSvgRect,
      feature: "width",
      unit: "px",
      applicator: Concert.Applicators.SVG_ElementAttribute,
      calculator: Concert.Calculators.Linear,
      keyframes: { times: [0, 1500], values: [100, 480] }
    },

    {
      target: CaptionBox,
      feature: "innerHTML",
      unit: null,
      applicator: Concert.Applicators.Property,
      calculator: Concert.Calculators.Discrete,
      keyframes:
      {
        times: [0, 750, 1500],
        values: ["Start Value", "Midpoint Value", "End Value"]
      }
    }
  ];

let sequence = new Concert.Sequence();
sequence.addTransformations(animations);

document.getElementById("GoButton").onclick =
  function () { sequence.begin(); };

The first two transformation definitions above are nearly identical. The first is just like many we have seen in earlier steps of this tutorial. But SVG objects don't get altered in quite the same way as regular HTML elements, so to accomplish the same width-altering animation with the SVG rect, we use a different applicator: Concert.Applicators.SVG_ElementAttribute. Everything else about this transformation works exactly the same.

The third transformation is on the caption box. To change the text inside the div element, we're just changing the innerHTML property. This is not a style, but a direct property of the div object, so the applicator used in most of the examples up to now does not apply. Instead, we use the Concert.Applicators.Property applicator. (You will probably also note that we used the Concert.Calculators.Discrete calculator here, because our usual calculator, Concert.Calculators.Linear, tries to interpolate between start and end values, which makes no sense in the case of wholesale text replacement.)

Custom Applicator Functions

You are not limited to the built-in applicator functions. As with easing functions, and calculator functions, user-provided applicator functions are easy to integrate with Concert.js. If you wish to apply complex numbers, object values, arrays of values, or make use of any other type of value or target object and feature other than those handled by the defaults, you can supply your own function that will be called on each frame when it is time to apply a new value to the animated target.

An applicator function is any function with the following signature:
function applicatorFunction(target, feature, value, unit)
The target passed in is the object being modified by the animation sequence.
The feature passed in is the property being manipulated on that object.
The value passed in is the new thing the applicator function should apply to the target object.
The unit passed in is the unit which should be attached to the value. (For example, for CSS styles, this is often "px", or "%", or some other unit applicable to element styles. But in many cases, a unit isn't applicable at all, and this value may be null.)
No return value is expected.

Your custom function should be able to handle the values passed it by the sequence you define and apply them to the target objects.
It can do whatever you like; just do be aware that this function may get called many times per second, and so its speed does matter.

Want more details?

Reference documentation links for items covered in this step of the tutorial:

• Concert.Applicators namespace
• Concert.Sequence.addTransformations() method documentation also contains information on using applicators, including defining custom applicator functions.