Declarative custom elements for Cesium

Overview

Use custom element web components to allow cesium to be used declaratively in HTML.

Currently Cesium is an imperative library that requires writing Javascript code with step by step instructions to set up the view. Many newer UI frameworks (like React, Vue, Svlete) are declarative. They allow the developer to declare what they want to display.

Example of current imperative Javascript code

const viewer = new Cesium.Viewer("cesiumContainer", {
  animation: true,
  homeButton: true,
  navigationHelpButton: false,
  shadows: true,
  shouldAnimate: true,
});

viewer.scene.primitives.add(new Cesium.Cesium3DTileset({
  url:  "../SampleData/Cesium3DTiles/Tilesets/Tileset/tileset.json"
}));

viewer.entities.add({
    position: position,
    orientation: orientation,
    model: {
      uri: "../SampleData/models/CesiumAir/Cesium_Air.glb",
      minimumPixelSize: 128,
      maximumScale: 20000,
    },
  });

Example of what a declarative custom element interface could look like

<cesium-view shadows animate>
  <cesium-animation-controls></cesium-animation-controls>
  <cesium-navigation-controls hide-help></cesium-navigation-controls>
  <cesium-tileset src= "../SampleData/Cesium3DTiles/Tilesets/Tileset/tileset.json"></cesium-tileset>. 
  <cesium-model
    src="../SampleData/models/CesiumAir/Cesium_Air.glb"
    minium-pixel-size="128"
    maximum-scale="20000"
  ></cesium-model>
</cesium-view>

Other custom element functionality

Using custom elements would also allow functionality like:

• automatically resizing the canvas to the containing element using ResizeObserver. This way it just works if the layout changes.
• Exposing events as native DOM events eg. document.querySelector('cesium-view').addEventListener('selected-entity-changed', ...). Makes it easier to learn for developers already familiar with other HTML DOM events.

First steps

I think the first steps would be to create a proof of concept cesium-viewer element that mirrors the exposes Viewer interface today. It would not support any sub-elements like the example above (there would still need to be some imperative configuration).

This could be used as a building block to start adding more elements like cesium-tileset.

Long term vision

Longer term I would like to see the viewer element be more modular and extensible for widgets. It provides a generic set of hosting capability for widgets (such as accessing the scene, maybe some basic positioning for widgets). Instead of the current system where the viewer knows about all possible widgets and they all get configured via the viewer object. That puts cesium created widgets on the same level as user created widgets. The cesium created widgets can serve as examples for how to create your own custom widgets.

[angrycat9000]

Probably worth taking a look at Resium if you haven’t seen it already.

Thanks for pointing that out. Yes this would be similar to Resium, however it would use custom elements instead of React. The advantage of custom elements is that they are not tied to any particular framework. So they could be used in React, Angular, Vue, or with plain HTML+JS.

[rudifa]

Hi @angrycat9000

Thank you for the comments and clarifications.

it might also make sense to just write it as a vanilla custom element with no framework

I think that LitElement places an useful layer of abstractions over the HTMLElement, hiding the drudgery and boilerplate code needed to use the HTMLElement API directly, see for example the codelab From Web Component to Lit Element.