When you're creating custom code using the awe.js API it's important to understand the lifecycle of your awe app and how you can tie your functionality to specific events.

Your awe app has a rich model of events that are listed in detail below and there are 4 key ways you can choose to handle these events.

The simplest way to handle a specific event is to use the awe.on_state() function and ask your code to wait for this to happen.

await awe.on_state('view_loaded', true);

Because this is using the await keyword then you need to ensure this is inside an async enabled function. If you are using this inside one of your own functions then just add the async keyword to your function definition.

async function my_function() {
  await awe.on_state('all_projections_loaded', true);
  // put your code here
}

This means that you can call my_function() any time you want and it will start then wait for the next all_projections_loaded event and your // put your code here code will only run after that event fires.

It's important to note the two parameters you pass to the awe.on_state(event_name, next) call. The first parameter is the event name you're interested in (see full lists below). The second parameter is a boolean that controls if you want to wait for the next time this event fires (true) or if you just want to know if this event has ever been fired (false). Binding your custom code couldn't get much easier than that!

But perhaps you don't want to place your code inside a custom function and just want to place it somewhere that will get run as soon as the app is loaded (e.g. /settings/custom_code or if you have a white-label app inside /settings/custom_branding). To use the await syntax you still need to place your code inside an async enabled function, but here you can use an auto-calling anonymous function. Here's an example of this with a number of chained events that will run in sequence.

(async function() {
  await awe.on_state('app_js_loaded');
  // put your code that relies on your /settings/custom_code here

  await awe.on_state('view_loaded');
  // put your code to setup your first view here

  await awe.on_state('all_projections_loaded');
  // put your code to manipulate some loaded projections here
})();

If you choose to use the async/await syntax then you can handle errors by wrapping your code in a try {...} catch(e) {...} block. Here's a great post on why the await/async approach is so useful.

If you want to create some await based code that is run each time an event is fired (e.g. each time view_loaded fires) then you can create a function that re-calls itself after each time it has run.

// setup your function
async function run_each_time_a_view_is_loaded() {
  await awe.on_state('view_loaded', true); // wait for the next view_loaded event
  // put your code here that is run after a view is loaded e.g.
  if (application.current_view.name == 'special_view_x') {
    // run some code here that only applies to 'special_view_x'
  }
  run_each_time_a_view_is_loaded(); // have your function call itself once it is done
}
(async function() { // setup an inline anonymous function
  await awe.on_state('view_loaded'); // wait for the first view_loaded event
  run_each_time_a_view_is_loaded(); // call your function for the first time
})(); // automatically call this anonymous function immediately

Because the awe.on_state() function returns a Promise you can also choose to use the standard .then() and .catch() methods too.

awe.on_state('view_loaded', true)
.then(() => {
  // put your code that runs once a view is loaded here
})
.catch((error) => {
  // put your error handling code here
});

If you aren't comfortable with or don't want to use a Promise based approach you can always use the more traditional listener based model. If you want to listen for an event to fire once then you can use this helpful function.

awe.util.add_one_event_listener('view_loaded', expiry_time, callback, expiry_callback);

For example if you just want to wait indefinitely for the next view_loaded event then alert the user with a specific message you can use some code like this.

awe.util.add_one_event_listener(
  'view_loaded', 
  undefined, // wait indefinitely
  function() { alert(MY_CUSTOM_MESSAGE); }
);

Or perhaps you want to wait for 5 seconds and if the user hasn't interacted with an object in your scene then show them a useful prompt.

awe.util.add_one_event_listener(
  'object_clicked',
  5000, // listen for 5 seconds 
  function() { console.log("YAY YOU INTERACTED WITH SOMETHING"); }, 
  function() { alert("DON'T JUST STAND THERE - DO SOMETHING!"); }
)

If you want to setup a persistent listener that listens for one or more events then you can use this helpful function.

awe.util.add_events_listener (event_names, callback);

For example if you want to listen for every time a user interacts with an object in one of your scenes you can use some code like this.

awe.util.add_events_listener(
  'object_clicked', // this can be a string or an array of strings
  function(event) { console.log("YOU CLICKED ", event.detail.object }
);

And if you want to remove this/these listeners then you can use this helpful function.

awe.util.remove_events_listener (event_names, callback);

You can also access the number of times a specific state event has been fired and see the last event object that was generated through the awe.states object.

• awe.states[event_name].count // the number of times this event has been fired
• awe.states[event_name].event // the last event object that was generated

So what are the valid set of state events that your awe app can fire? Here's the list that you can also access via the awe.valid_states object.

• awe_initialising - your awe app has started setting itself up (once per app load)
• awe_installing - your awe app has started loading the resources it needs (once per app load)
• awe_ready - the base awe object and it's libraries are ready (once per app load)
• application_base_ready - the base level application object is ready so you can now extend it if required (once per app load)
• application_ready - the application object is now completely setup (once per app load)
• ready - the whole awe app has now loaded (once per app load)
• awe_js_loaded - the awe javascript content has loaded (once per app load)
• awe_css_loaded - the awe css content has loaded (once per app load)
• app_js_loaded - your /settings/custom_code javascript has loaded (once per app load)
• app_css_loaded - your /settings/custom_code css has loaded (once per app load)
• scene_ready - the awe.scene() is now setup (once per app load)
• scene_load_started - the content of your scene has started loading (once per view load)
• scene_loaded - the structure of your scene has loaded (once per view load - excludes projections)
• view_loaded - the combined 3D scene and HTML content have loaded (once per view load)
• all_projections_loaded - all the 3D objects in your scene have loaded (once per view load)
• view_unloaded - the scene you were viewing has unloaded (once when you change views)
• gum_ready - the camerastream has been successfully setup (every time the camera is setup)
• cv_ready - the awe computer vision libraries have been successfully setup (the first time an image view is loaded)
• tracking_ready - the awe computer vision tracking system is now running (each time an image view is loaded)
• map_library_ready - the geolocation/map libraries have been successfully setup (the first time a location view is loaded)
• initial_location_established - the user has given permission to access their geolocation and the first location has been acquired (the first time a location view is loaded)
• app_error - an error has occurred loading this awe app (once per app load if required)
• unsupported_browser - this browser does not have all the capabilities required to run this awe app (once per app load if required)
• cookies_disabled - this browser has cookies disabled (once per app load if required)

• tracking_state_changed - tracking has started or stopped (every time the tracking state changes in an image view - event.detail contains a true of false to show the new state)
• tracking_lost_modal_shown - a target image has not been found for a pre-defined time (generally 5 seconds - this time can be altered and this modal can be disabled)
• object_clicked - the user has interacted with an object in the scene (every time the user interacts with an object - when objects overlap only the closest object is clicked - invisible objects can not be clicked)
• scene_clicked - the user has interacted with the scene where there is no object (every time the user interacts with the scene background)
• infopanel_opened - an information panel has been presented to the user (every time an infopanel is opened)
• infopanel_closed - an information panel has closed (every time an infopanel is closed)
• scene_structure_changed - the 3D structure of the scene has been recalculated (when certain config params change)
• touch_gesture - the user has touched or clicked within the window (when the user starts a gesture)
• touch_gesture_ended - the user has stopped touching or clicking within the window (when the user ends a gesture)
• pov_position_changed - the virtual camera within the scene has moved (whenever something moves the camera)
• pov_zoom_changed - the virtual camera has moved along the dolly (whenever something zooms the camera up or down the track on the dolly)
• gyro_allowed - the user has allowed access to the gyro (when gyro permission is granted)
• gyro_denied - user has NOT allowed access to the gyro (when gyro permission is denied)
• compassneedscalibration - the compass values are unreliable (when the system reports this problem)
• scene_visible - when AR or VR mode views are shown (each time your awe app changes to this mode)
• scene_hidden - when the Page mode or similar is shown (each time your awe app changes to a mode that hides the scene)
• view_count_changed - when your awe app changes to stereo or mono mode (each time the number of virtual cameras viewing a scene changes)
• gum_error - when access to the camerastream fails or is denied (each time the camera fails to be setup)

Here's the general event flows for the common scenarios when you load or navigate between different view types.

• awe_initialising
• awe_installing
• application_base_ready
• awe_js_loaded
• awe_css_loaded
• awe_ready
• scene_ready
• app_css_loaded
• app_js_loaded
• scene_load_started
• scene_loaded
• view_loaded
• application_ready
• ready
• all_projections_loaded
• gum_ready
• cv_ready
• tracking_ready

• awe_initialising
• awe_installing
• application_base_ready
• awe_css_loaded
• awe_js_loaded
• awe_ready
• scene_ready
• app_js_loaded
• app_css_loaded
• scene_load_started
• scene_loaded
• view_loaded
• application_ready
• ready
• all_projections_loaded

• awe_initialising
• awe_installing
• application_base_ready
• awe_css_loaded
• awe_js_loaded
• awe_ready
• scene_ready
• app_css_loaded
• app_js_loaded
• scene_load_started
• scene_loaded
• view_loaded
• application_ready
• ready
• map_library_ready
• initial_location_established
• all_projections_loaded

NOTE: Order of events below scene_load_started is not guaranteed

• awe_initialising
• less_ready
• awe_installing
• application_base_ready
• awe_css_loaded
• awe_js_loaded
• awe_ready
• scene_ready
• app_js_loaded
• app_css_loaded
• view_loaded
• application_ready
• ready

• awe_initialising
• less_ready
• awe_installing
• application_base_ready
• awe_css_loaded
• awe_js_loaded
• awe_ready
• scene_ready
• app_js_loaded
• app_css_loaded
• view_loaded
• application_ready
• ready

• view_unloaded
• tracking_state_changed
• scene_load_started
• scene_loaded
• view_loaded
• all_projections_loaded

• view_unloaded
• scene_load_started
• scene_loaded
• view_loaded
• all_projections_loaded

• view_unloaded
• scene_load_started
• scene_loaded
• view_loaded
• all_projections_loaded
• gum_ready
• cv_ready (but only if this is the first time an image view is loaded)
• tracking_ready

• view_unloaded
• tracking_state_changed
• scene_load_started
• scene_loaded
• view_loaded
• all_projections_loaded

• view_unloaded
• scene_load_started
• scene_loaded
• view_loaded
• all_projections_loaded

• view_unloaded
• scene_load_started
• scene_loaded
• view_loaded
• map_library_ready
• initial_location_established
• all_projections_loaded