Common Questions, Pitfalls, and Performance Issues

Common Questions a Developer May Ask

When should I create a new Surface versus adding more HTML content to a single Surface?

In short, when you need something to behave or animate differently, it should be a new Surface. If the HTML will behave the same, then it can all be contained in a single Surface. Think of a standard deck of cards. Each card ought to be its own Surface because it can be moved individually, but the numbers and pictures on each card are never going to animate independently and therefore may exist together as the content of the Surface.

Why is my Surface behind this second Surface?

There are a few reasons this could happen.

Why is my Surface not getting this click?

This is usually an indication that there is some invisible Surface on top of the one you are trying to click. If you inspect the element you are trying to click, it may give you insight into the exact DOM element you are targeting. This can happen when a Surface has an opacity of 0 but still exists in the DOM.

How do I find the absolute position of a Surface on the screen?

By design this is not possible. It is something the developer should not care about. For the time being, this means that interactions such as drag and drop are harder to implement, but this is intended and we are working on an elegant solution for these use-cases.

When should I be using a new Context?

New contexts should be used when various sections of your application require different perspectives to be set. A great example is having an overlay or HUD. It would make sense to have a Context for a 3D scene and a second context for a flat HUD sitting on top of the 3D scene. This technique is also useful for modals.

Be careful with the amount of Contexts that are created. Each Context created triggers another full render cycle for the Engine to calculate. Overuse of Contexts can lead to performance loss. Do Not's

Pinging the DOM is very different from many Javascript frameworks, since it endorses zero touches to the DOM. Querying the DOM can lead to both performance issues as well as unexpected behavior.

In terms of performance, performing large queries against the DOM is fairly expensive (in measurement of CPU cycles). Also, seemingly simple requests, such as asking for the width of a DOM element, will sometimes cause the entire page to reflow in order to calculate the correct value for the element's width. These reflows are made more apparent in a highly animated environment.

There is also unexpected behavior because of how uses DOM elements. Some components, such as Scrollview, can cause the DOM element associated with a Surface to be deallocated. This resource pooling optimization allows to minimize the amount of DOM element creations which is an expensive operation. However, this leads to issues when trying to access DOM elements that no longer are present in the DOM.

Using setInterval

Using the default Javascript setInterval will cause issues in because of the amount of code the Engine runs. In some cases, it is possible for the default setInterval to miss a cycle. If you need setInterval functionality, there is a Timer utility as a part of that is integrated with the Engine so that no cycles are missed.

Using Native DOM Events

Using native DOM events is fine for intra-surface eventing but is messy for inter-surface eventing. When trying to communicate across Surfaces, it is best to use' eventing system. By keeping all events in a single system, it is much easier to manage, as an application grows. Also, because of the resource pooling mentioned in "Pinging the DOM", it is possible that your Surface may have its DOM element deallocated and therefore would result in a loss of all of the registered DOM event handlers that were registered on it.

Non-performant CSS

CSS is from the age of web pages, not web applications. As a result, the long paint and reflow times associated with certain CSS classes has gone somewhat unnoticed due to the static nature of the web. As developers strive to further animate their web applications, understanding the performance implications of their CSS is important. Below are some of the CSS pitfalls a developer may run into in a highly dynamic environment.

Check out Paul Lewis' and Paul Irish's High Performance Animations for a great rundown of CSS' impact on performance.

Browser Specific Issues

Each browser comes with its own set of quirks. Understanding the limitations of the browsers and when encounters these limitations is very important for developing cross-browser applications. Below are some of the known browser issues that you may come across while developing with

All Browsers
Chrome & Firefox
iOS7 iPad