Layer Browser refactoring and publishing online

[grahambates-sp]

I have found the Layer Browser very useful when playing around with layers and as opportunity to discover some of the customisations deck offers.

However, as it is not online and requires checking out the codebase, not everyone will know about this tool. From speaking on the Slack channel I understand that the current implementation is not quite polished enough to be public facing.

I've taken a look at the code, I can follow most of it easily enough, so can try to clean it up.

This ticket is to begin the conversation about the likelihood of it being published online, and the main parts of the code that should be considered for refactoring so I know what to prioritise/focus on.

[ibgreen]

At least the React code should be clean and easy to read - last time I checked it looked like there had been a "hackathon" in there :)

Since you are new to the code base, simply working through it should highlight things are that are confusing.

Ask yourself this question: If a user sees something they like in the layer browser on the website, and wants to see how it is done in code, are they likely to quickly find how it was done when looking into the code, or just end up more confused.

[grahambates-sp]

Yeah. Is there a desire to continue keeping multiple layers in the same file, or would it be alright to move each into their own file with a suitable folder structure?

[ibgreen]

Moving each layer into its own file seems like a way to make this simpler for users.

Also I seem to recall that some of the ways the props are specified for the test layers are "hacky". Better to do a bit more work and make it easier to copy each layer out of the example.

[Pessimistress]

The embedded demos in each documentation page replicate some of its UI. Can you elaborate what functionality of the layer browser that you like is not in the docs website?

We intentionally add various data formats and edge cases in the layer-browser for debugging. As a result, the datasets are not necessarily clean or make sense. In contrary, the embedded demos in docs strive to be easy to read and showcase why the layer is useful. If possible, I'd rather maintain one version of layer demos across the board.

If it causes too much confusion, layer-browser should be moved into the test/apps directory, instead of staying in examples.

[grahambates-sp]

The layer browser has taught me a lot and encourages one to think about potential applications that combine multiple layers. Some examples of what it achieves without me having to type a line of code:

• It lets me play with opacity
• It helps users quickly set lineWidthMin/MaxPixels
• It hits home the performance of deckgl
• It conveys what concepts like billboard are that quite buried in the docs
• it's a great 'creative' tool to inspire for what is possible.

In short, it does a great job addressing the point I made in Slack the other day about how Deck is much more than 'mapbox layers'.

if it exposes some 'beta' features like separation ( I only leant about that today from using Layer Browser) then I understand a reluctance to push it more public. But I saw a black list set of properties - that could be used to hide certain things that aren't ready for primetime yet?

[ibgreen]

Trying to stay neutral here :)

I do think the layer browser could be a pretty cool example, but as I indicated from the beginning in slack that is assuming that it is redesigned to be a showcase rather than a test app.

Some things that could help:

• we could move the pathological test cases for e.g. path layer into a fork in test/apps.
• We could architect that "fork" to include the main app.js from examples and just inject some extra examples as props, rather than duplicating all the code.
• this would be some extra work for you @grahambates-sp

[grahambates-sp]

I've only done about 5 layers so far (simply moving each layer into its own file really and a bit of tidying up, nothing more. Should I continue with that? It does make it easier to follow rather than multiple layers in their own file.

Another option is to make a shiny completely new example that isn't quite a layer browser as it doesn't have the ambition of covering every prop, but could be a cool 'kitchen sink' all the same.

For example some nice combo of terrain, geojson, arc layer, bitmap, mesh models, point cloud, trip layers, lighting, post processing with sliders that allow playing with the props that make sense (but not necc. all).

[Pessimistress]

Ok, I can get on board with a clean, public-facing version + some ugly edge cases in test/apps.

[grahambates-sp]

I've been having experimenting with using storybook (https://storybook.js.org/) - it is a library for example the kind of thing we are trying to do.

See here my initial progress:

https://deckstories.imfast.io

And you can see how you build the stories here:

https://github.com/mogmog/DeckStories

It's pretty cool, and allows very copy and pastable examples.

Before I go any further I wanted to checkin and see if this is ok and if you see any issues with hosting this kind of thing.

[Pessimistress]

I am not opposed to Storybook, however, my impression is that it is designed for showing off components individually. It seems to be going in the opposite direction from your goal of showcasing how deck.gl composes layers and effects.

[grahambates-sp]

Yeah I think that's what its primarily designed for. There are 2 things that it has been helpful for that I haven't found anywhere else, and don't really fancy writing my own as it won't be as battle tested.

1. A nice tidy menu system where everything is derived from the 'title' of the story and the exported component function name. You don't have to maintain anything else, it automatically creates the hierarchy .

2. A easy and relatively automatic/hidden to the user when copy and pasting code, 'knobs' mechanism that allows you to add sliders, radio buttons etc without having to write the code for them. You just define those number/boolean etc variables and it does the rest, keeping excess code to a minimum. I'm pretty sure I could build up an example of 5 or 6 layers with all sorts of knobs that would show some nice interactions that hint at what is possible.

If anyone has any suggestions on powerful combinations of layers, suggest them here.

I'm happy to crack on and come up with a kitchen sink demo, even if you don't use it, the lighting and post processing sliders I've started to wire up are useful for my own project.

[ibgreen]

Well, Storybook is super popular so having a story book with really small clean working examples for each layer is probably not a bad idea, it might give a lot of folks an easy way to get started using an environment they already have some familiarity with..

There is quite a bit of overlap with the inline documentation examples but I think we can live with that - having the storybook could mean that we don't have to put in extra effort to make the code for those easy to find and read for newcomers :)

Also agree for the "kitchen sink" demo, focusing on enabling users to play with multiple layers, effects, lighting etc, is all very valuable just as you say.

[jfuehner]

Just my two cents; I'd love to see something similar to what Cesium does with their Sandcastle. An interactive code sandbox would be super useful.

[kylebarron]

Just my two cents; I'd love to see something similar to what Cesium does with their Sandcastle. An interactive code sandbox would be super useful.

Aka https://deck.gl/playground/, but for JS instead of JSON?

[jfuehner]

@kylebarron exactly! JSON gets you 50% of the way there. Also, would love to see some of the hidden nugget examples such as the Harp.gl example. Wouldn't even know its there unless you are trolling the github source...

[ibgreen]

Good suggestions!

Aka https://deck.gl/playground/, but for JS instead of JSON?

Nothing against JS sandcastles etc, but want to make a small plug for the JSON playground:

A limitation with the JSON playground is that the example dropdown on top of the text is not very prominent. Simply redesigning that to a list with some thumbnails etc would probably lead to more people discovering the examples there (and motivate other people like me to add more examples :)

Also, since we now support many API versions (pure JS, script, React, Python, and now gradually C++/Swift/Java) the JSON browser does have the advantage that those examples are essentially guaranteed to work in all environments... and they are easier to maintain over releases as well.

[grahambates-sp]

That is a strong argument for the JSON Playground 'being' the the equivalent of the Layer Browser.

I think my StoryBook thing should be reserved for complex examples involving multiple layers and composite layers, state etc, ill take out the basic layer examples, they were more for testing anyway.

Re UI - Agreed about the drop down, a combination of the padding and the fact a layer is auto selected means its not super obvious it can a be changed. The thumbnails also sounds like a good shout.

Also some helper text could be added, I didn't realise the JSON was editable!

Only thing thats held me back when I have scanned the JSON playground - I've seen some interesting syntax in there - what does this mean? "getPosition": "@@=-",

[ibgreen]

• I've seen some interesting syntax in there - what does this mean? "getPosition": "@@=-",

The syntax is documented, I would assume it is somewhat obvious that strings starting with @@= are parsed as expressions and converted into functions (in this case accessors for data driven styling).

The - expression basically returns the entire "row" (efficient when the table rows are very simple e.g. just an array with position) this short cut does not seem to be documented. It could be better to avoid using it.

[ibgreen]

I think my StoryBook thing should be reserved for complex examples involving multiple layers and composite layers, state etc, ill take out the basic layer examples, they were more for testing anyway.

Sounds reasonable. If an example can be done declaratively in JSON, it would be my preference to do it so.

It may be hard to see now, but even though deck.gl was designed with a declarative properties based API from the start, it took a major push to make deck.gl "declarative enough" that it allowed JSON examples to be written with out supporting javascript code. Without requiring separate JavaScript loading and data transform code, interaction callbacks etc.

And even so, there will always be examples where additional code is necessary. Right now about 50% of the website examples can be ported to JSON, the rest still depend on some JavaScript code.

Generally I'd like to see us gradually improve the declarative capabilities of the API so that a bigger percentage of those examples can be written in JSON.