This is an introduction to Sandcastle, a live-coding app for viewing Cesium examples and testing code quickly. The Cesium team uses Sandcastle constantly, and after this, we hope you will too!

Sandcastle provides a Cesium Viewer widget and a code editor. To modify examples, just edit the code and click ‘Run’ at the top of the window.

Browse the gallery of code examples to see the breath of Cesium capabilities. The examples are listed in the scrollable filmstrip at the bottom of the page. These examples can be filtered by labels, or with keywords using the search bar at the top. We’d start with Beginner examples.

Searching through the example code gallery.

Reference Documentation

Sandcastle provides easy-access for Cesium documentation. Simply double-click on a Cesium class, function or property in the code to open the relevant documentation page in a new tab on the right side of Sandcastle.

Sandcastle also provides code suggest and auto-complete for Cesium identifiers and native JavaScript. Just hit Ctrl-Space to open a drop-down menu of all the viable completions at the cursor’s current position in the code.

Code completion and quick documentation access.

Saving and Sharing

Sandcastle makes it easy to share code examples.

Sharing

To share a code example as is in Sandcastle, click the Share button at the top, which will save the current code as a GitHub Gist and generate a url to a Sandcastle example with the code loaded.

This is the best way to share code on the Cesium forum when asking for help, since this provides a live example of your work. The Cesium team also especially appreciates this when submitting bugs on GitHub.

Loading Github Gists

Load saved Github Gists by clicking the Import Gist button and entering a generated gist url or ID.

Save, share and load examples quickly.

Saving code

To save a Sandcastle example as an html for use in a local Cesium repository (and hopefully for contribution later!), just click the Save As button at the top, which will download the current code as an html file. Save the file as Apps/Sandcastle/gallery/*.html for use in a local build.

Simple GUI

Sandcastle also provides some basic GUI widgets, helpful for interactive testing and debugging. Sandcastle widgets include buttons, dropdown menus and toggle buttons. See code examples here.

When a GUI element is triggered, Sandcastle will also highlight the executed code in green so it is easy to fine the related code.

Simple GUI examples.

Building locally

Sandcastle is hosted on our website, but is also included in the Cesium repository, and can be built to use a local version of Cesium. See our build guide for more details. Using a local build is useful for testing code with different branches of Cesium.

Contributing

Do you have a minimalist example that demonstrates a helpful Cesium feature? We’re always in need of more Sandcastle gallery additions! Feel free to open a pull request! See the Contributor’s Guide for how to get started.

Your Sandcastle example will require a few things:

  • Code: Just create a code example in Sandcastle, hit the save button and put the generated html file as Apps/Sandcastle/gallery/*.html in your Cesium repository.
  • Meta information: Before saving a code example, click the “Info” button at the top to write a description and labels for your example.
  • Thumbnail: Click the “View as Thumbnail” button up to for a miniature view of the current viewer application. Screenshot, then add to Apps/Sandcastle/gallery/*.jpg. Make sure the name matches the html file.

That’s it! We hope you find Sandcastle as useful as we do!