After multiple tests, I believe the ABeamer API has reached a mature state.
In the future, and with the help of user feedback, small portions of the API can still change but it will be done by creating a new version of a function and deprecating the previous version.
Therefore, I released ABeamer 1.0.0, the first production level version of ABeamer.
This version has many improvements, bug fixes, a few cosmetics changes in the documentation, and better support on Windows platform and Microsoft web browsers.

The new features in ABeamer 1.0.0 include:

  • Support for the command-line to pass variables to the library and these to be used by expressions.
  • Support for the command-line to control the frame dimensions.
  • Default variables.
  • Support to server rendering without local configuration files.
  • The easings name can be defined by an expression.

LTS version

This is the first LTS version of ABeamer.
I created the new 1.0-lts branch on github to provide future support of this version in case of critical bugs are found.
Since ABeamer has reached production level, I created a new github dev branch to welcome more developers to this project, leaving the master branch only for stable versions.

Passing variables from the command-line to the client library

Previously, the animated-badges already read variables from the queryString to configure its parameters, but this wasn’t a standard way, it was very limited and didn’t support teleportation.
Passing variables to the client library is mostly used to server render locally, but it can also have an impact for teleported stories.
Now, with ABeamer 1.0.0 the command-line can pass variables via:

abeamer render --var "<name>=<value>" --var "<name>=<value>"

Example take from How to generate an animated badge with ABeamer:

abeamer render --dp \
--url /gallery/latest/animate-badges/index-online.html \
--width 126 --height 20 \
--var "name=downloads" --var "value=156.000" --var "valueBackgroundColor=#1b90c3" \
--var "nameWidth=70"

Each var will be encoded and added to the queryString:

/gallery/latest/animate-badges/index-online.html?var=name%3Ddownloads&var=value%3D156.000

And then, it’s accessible via story.args.vars parameter:

const vars = story.args.vars;
console.log(vars.name);

But ABeamer is all about teleportation, and since JavaScript isn’t stored on teleported story, the best is to use as variables in a expression:

scene1
  .addAnimations([{
    selector: '#text',
    props: [{
      prop: 'text',
      valueText: '=name',
    }],
  }]);

This way, it will allow the cloud render server to dynamically control the story.

Controlling the story dimensions by the command-line

Before this version, the client library read the dimensions from abeamer.ini, and then, in case of local server rendering, server agent executed by the command-line also read the dimensions from the same file, and in case of teleported stories, the server agent read the dimensions from the teleported story, usually, the story.json.
This model has the advantages of:

  • It’s simple.
  • The SCSS file is aware of the dimensions, allowing to better position elements.
  • The client library is aware of the dimensions without the need of a server.
  • The server-agent reduce the risk of attacks of very large dimensions, since the dimensions limits are tested before the rendering starts.

With ABeamer 1.0.0 the server render can override the dimensions defined in the ini/json configuration, allowing to:

  • Render the story in multiple dimensions.
  • Increase or Decrease the dimensions depending on the variables defined in above section.

To transform a story into dynamic dimensions:

  • Change the scene dimensions to 100% in the main.scss.
.abeamer-scene {
  width: 100%;
  height: 100%;
}
  • Change any dimension dependent CSS property.
    The preferred method is to addAnimations to that CSS property with 1f duration.
scene1
  .addAnimations([{
    selector: '#text',
    props: [ {
      prop: 'left',
      value: '=frameWidth-50', // don't use units. ABeamer only works with pixels.
    }]);

This method, unlike JavaScript code, is teleportable.

Security Note: When setting up a cloud render server, don’t allow the user to send queryString information to reduce the risk of an attack.
Pass render variables only via command-line.

Default variables

As stated above passing a variable on the command-line, allows the expressions to access it as variables in a expression, but if the variable is missing it will raise an exception.
To prevent this, ABeamer allows to define default variables via add-vars task.
This task already existed previously but before it always overwrite the existing variable.
Now, it can prevent a variable from being overwritten having the same effect as a default variable.

  scene1
    .addAnimations([{
      selector: '#label',
      tasks: [{
        handler: 'add-vars',
        params: {
          overwrite: false,
          vars: {
            color: '#FF000',
          },
        } as ABeamer.AddVarsTaskParams,
      }],
      props: [{
        prop: 'color',
        valueText: '=color',
      }
  }]);

In example about label will be change its color from the command-line variable color, but if this variable is missing it will set to #FF000.

abeamer render --var "color=green" --url <url>
abeamer render --url <url>

Server rendering without local configuration files

Previously, for the server to render always required for the abeamer.ini, index.html to be present and in case of a teleported story to have the .json file.
With this version, this is no longer necessary, simplifying the process of the server to render stories the local network or render demo stories built with ABeamer in remote links.
This process wasn’t tested for teleported stories and is still under evaluation if there are advantages of cloud server renders to render without local files.

The easings name can be defined by an expression.

Since the expressions were already used by easings to generate a run-time interpolator, it wasn’t possible to use expressions to define the easings name, which can be useful in case of the easing be defined as server render variable.
In this version, an easing expression starting with ==, allows to define the easing name to defined as an expression.

on main.ts:

  scene1
    .addAnimations([{
      selector: '#label',
      props: [{
        prop: 'left',
        easing: '==easing',
        value: 100,
      }
  }]);

on the command-line:

abeamer render --var "easing=easeOutElastic" --url <url>