Rebuilding Sandcastle: Technical Implementation #12566
Comments
|
This will be a very welcomed update. Sandcastle has had the same look and feel for many years and could definitely use a refresh. |
|
Some running TODO's which have come up in discussion like the forum and @jjspace's initial PR.
|
Build structureA big complication with this process is the actual build configuration. This is more complicated because locally we want to point at all the locally built files instead of copying them into the vite build statically. I wanted to share this breakdown I've been referencing a lot during my work on #12574. This is also not helped by the fact that when we deploy to prod we copy everything to the top level domain and basically all routes need to be adjusted somewhat to account for that. This will need to be kept in mind as we discuss how we want to change the import process into Sandcastles. There are basically 3 main ways a specific sandcastle can be loaded. They all need to work. More specifically routes to imported JS or CSS and sample data need to work for all of these routes regardless of the environment outlined above.
Gallery filesAnother big topic we still need to settle on is the structure of an actual, saved, gallery file. Right now they're all html files that work on their own. The code is extracted from them and loaded into the code editors when they're loaded in Sandcastle. Metadata like the title, tags and description is included in the Open questions:
CC @ggetz there's more beyond these to talk about but hopefully this can help kickstart our discussions |
|
@jjspace Re: Gallery files Before we get into the technical aspects of the gallery file (like the JS/CSS/HTML breakdown, import styles, etc), I think it would be helpful to decouple what we'd like out of a gallery example and how to organize them from implementation itself. To start what makes up a gallery example? I think defining this will help guide (3) and is directly involved with (4).
Then going one level deeper, how do we ideally want to store that metadata (4)? I'm putting aside backwards compatibility for a moment to think about how it might make sense if starting from scratch.
title: Adjust 3D Tileset Height
thumbnail: "./3d-tiles-adjust-height.jpg"
description: Adjust the relative height of a tileset to better align it with terrain.
labels:
- 3D Tiles
- Tutorial
category: Working with 3D Tiles
context: Each instance of a 3D tileset has a modelMatrix property that, when set, modifies the entire tileset's position, rotation, and scale. This transformations are applied in worldspace before the tileset's root tile transform.Or, if we want more formatting, that yaml can be ported to a markdown file's front matter: ---
title: Adjust 3D Tileset Height
thumbnail: "./3d-tiles-adjust-height.jpg"
description: Adjust the relative height of a tileset to better align it with terrain.
labels:
- 3D Tiles
- Tutorial
category: Working with 3D Tiles
---
Each instance of a 3D tileset has a `modelMatrix` property that, when set, modifies the entire tileset's position, rotation, and scale. This transformations are applied in worldspace before the tileset's [root tile transform](https://github.com/CesiumGS/3d-tiles/tree/main/specification#transforms).For (5), I'm having trouble picturing a use case, but it sounds like you have some in mind. Could you share what you were thinking about? Let me know your thoughts on all that, and then we can talk through the details of how we'd like to store the code and what this may mean for backwards compatability. |
|
@ggetz sorry my response got a little lost but here's my thoughts
Correct, that is the current list, even if not all of those are displayed promenantly (description). I think it could be helpful to include a general category but I'm not sure how different it would be than tags. It would definitely help to categorize in whatever UI we pick but I could also see it being an issue that certain sandcastles should belong to multiple categories and then we're right back to tags.
I agree it may get cumbersome to all be in the same html file. I also think the more we do in there the harder it may make our lives to try and parse/process it when we want to load examples. That said, a separate file may end up being even easier to miss and forget to update but I think that's going to be true for any solution we come up with.
I agree, even if we stuck to a single file I would want to pre-process it more so we can load only the metadata on page load instead of the full example.
I do really like the idea of using YAML, it's common and easy to use and can be pretty extensible. Definitely easier to write and read than JSON. The main question will be where does it live. This is all pointing to having one or more "sidecar files" for a given sandcastle. One big question I think we need to answer is still: Should people be able to load gallery examples directly? If the answer is "yes" then I think we should keep what we can inside the html file itself. If the answer is "no" then we can do more with the "save format". Maybe even separating into dedicated JS and HTML files. or creating subdirectories for each sandcastle and use the file structure itself to encapsulate the metadata sidecar files and the thumbnail and the code etc.
The primary usecase I like is just having access to the active |
I agree this is valid from an implementation standpoint. From a usability perspective, just displaying the tags as "categories" is a bit overwhelming due to the number of them, and I think we would like to be more intentional about which ones we present and in which order.
Good point. Just for clarity here, you're talking about the ability to take the HTML file and load it outside of the context of Sandcastle as more of a standalone example, correct? Or are you looking more to address "saving" a sandcastle to a file and being able to bring it back in? Overall, I'm personally favoring a gallery example being a directory of files for the flexibility and simplicity from the point of view of the user. Theoretically, this wouldn't prevent the example from working as a standalone example. And we could save as a zip file if the user wants to download, while an example could be brought back in by unzipping in browser (for example).
Potentially, we could include things like version info, author, last updated, or search embeddings if they prove useful. I really am leaning towards the |
|
Talking offline, with @jjspace– To facilitate different directory structures, we'll consider path aliasing for things like |
Uh oh!
There was an error while loading. Please reload this page.
This issue will track the technical implementation of a new version of Sandcastle for CesiumJS. Design and features will primarily be worked out and discussed elsewhere. If you want to provide feedback on features you'd like to see please add them to our post on the community forum
High level plan
We plan to create a new workspace/package within our mono-repo to keep the new Sandcastle project separated but co-located with CesiumJS.
itwin-ui: We expect to use the newest version of iTwin/Bentley UI library for both components and styling as much as possible. We may contribute improvements or components back to it as necessary.As we build out the new version we plan to have a beta/dev deployment for people to test against. More info on this as build systems and CI get set up
CC @ggetz
The text was updated successfully, but these errors were encountered: