Sequential actions ("await")

In the core, all action commands run in sequence, except for commands that use ajax or have some sort of delay. But in Active CSS you can specify that you want to wait until one of these types of action command is finished before running the next action command.

There is a way to do this. Use the "await" option. You can use this option on either ajax-type commands, or any delayed action command.

Both these options make commands sequential in the event they are written in. Each event has its own sequential flow. The whole page won't freeze up, unlike JavaScript sleep(). This isolation to a specific event gives you the benefit of synchronous coding in a naturally asynchronous environment.

This part of the documentation covers the "await" option, and the "await" option is available on every regular CSS command and every action command in Active CSS.

What is the syntax?

To work, "await" must be placed at the end of the action command. Like "color: blue after 1s await;".

What is sequential/asynchronous, Scotty?

A sequential action command is one that waits until it is completed before moving on and running the next action command in the config.

An asynchronous action command starts running but does not get a result immediately as it needs to waits for a result. It lets the rest of the page carry on until it completes, then at some point the asynchronous action command gets a result and then does its thing.

Actions that do not return a result immediately, such as delayed action (using the "after" option on action commands) or ajax commands, are asynchronous, but can be made sequential within a specific event declaration by adding the "await" option to the action command.

This await option works on all ACSS action commands that are delayed in some way.

What if the action command is cancelled before it finishes?

If the delayed action command is cancelled, or there was an ajax error, the rest of the action commands will not run for that specific queue of actions. Action commands will only continue to run afterwards if it was successful and not cancelled or erroring.

Which order do the commands run when used in target selectors that affect more than one element?

That's a good question. It depends. See the event flow page for the answer to that.

More details

Actions that have no delay, or for example do not use ajax, are sequential in nature and so the await option will be ignored if used on those action commands.

Each separate event declaration in the config has its own dedicated sequential "queue". If you use the await option, the next action command in that event declaration will run after the action command has completed successfuly.

The sequential aspect is isolated to that specific event declaration for that specific event, so other user-driven events on the page will continue to respond as usual, even if there may be other sequential actions waiting to be run in other events. This means that the page continues to be responsive to user interaction even though there could be multiple simultaneous sequential actions in play. This is possible with the event flow that had to be manually built for the Active CSS core to work sensibly. You can't do this sort of thing easily in native JavaScript.

Internally in the core, all delayed actions are asynchronous, including "sequential" ones that appear to be waiting before they can continue. This is necessary so that the page doesn't complete freeze up while it waits for a sequential action command to complete. But from the programming viewpoint of the developer, "await" action commands can be considered fully sequential within a specific event declaration.

 

The await option can be useful, for example for chaining CSS changes or UI changes, or for making ajax code a bit shorter.

 

 

Using the "await" option with ajax

Using the "await" option in a single event with multiple targets

Using the "await" option with a single target in multiple events

 

 

Note: Dynamic styling and switching back and forth between browsers can sometimes cause a bizarre thing to happen if there are multiple delays going on in separate declarations. Like sometimes when coming back into the browser, one specific event with a pause will be delayed slightly compared to the other CSS effects on different elements. I suspect this is more to do with event transitions on a browser level than something needing to be fixed in the core. Or something like the event in progress at the point of window blur causes a small, difficult to avoid, delay before completion within the rendering engine - something like that. Essentially, the timing goes off. If anyone knows differently though and thinks it can actually be resolved in the core, please get in contact via github issues, as it would be good to get it resolved. In theory a workaround would be to manually stop and restart specific grouped animations on exit and re-entry into the window using events on the window object (although this hasn't been tried out).