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 are two ways of doing this.
You can either:
- Use the pause command.
- Use the "await" option. You could use this option on ajax-type commands.
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 except the "pause" command.
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, Dave?
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. Although the pause command may be a more readable alternative for non-ajax commands.
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.
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.
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).