docs(widgets) Custom Widget Developer Guide #9304
Conversation
chrisgervang
changed the title
| {layers.filter(layer => ( | ||
| this.deck?.props.layerFilter({layer, viewport}) | ||
| )).map((layer) => { | ||
| <li key={layer.id}>{layer.id}</li> |
There was a problem hiding this comment.
Would it be much more code to show how control the layers in some way? For example, have a checkbox next to each layer to toggle visibility in that view?
There was a problem hiding this comment.
I can try it.. but controlling anything the user sets starts to get into a territory where user state and internal state can get out of sync. At least, there's nothing preventing user-space from just overriding any changes a widget makes to a layer. And there's some risk of introducing a race condition.
I think what this would look like with our current API is something like:
this.deck?.setProps({ layers: layers.map(layer => layer.clone({ visible: isVisible }) })
This could cause events to fire in the app that in-turn call setProps. Is there a way to draw the layers without alerting the user? Perhaps:
this.deck?._drawLayers('layer-list-widget', { layers: ... })
| ```ts | ||
| import type {WidgetPlacement} from '@deck.gl/core' | ||
|
|
||
| interface AwesomeWidgetProps { |
There was a problem hiding this comment.
Nit: Recommend with the arguably more modern approach to use the type keyword here. I personally prefer reserving interface for types that are to be derived from with methods that need to be implemented.
| interface AwesomeWidgetProps { | |
| export type AwesomeWidgetProps = { |
There was a problem hiding this comment.
I'd want to do this in a separate PR and update everything in one sweep.
| /** | ||
| * Widget positioning within the view. Default: 'top-left'. | ||
| */ | ||
| placement?: WidgetPlacement; |
There was a problem hiding this comment.
consider exporting a set of base WidgetProps so that widget writers don't need to retype all of that?
| placement?: WidgetPlacement; | |
| export type WidgetProps = { | |
| id?: string; | |
| placement?: WidgetPlacement; | |
| viewId?: string | null; | |
| }; | |
| ... | |
| export type AwesomeWidgetProps = WidgetProps & { | |
| customText: string; | |
| } |
There was a problem hiding this comment.
I like the idea to encourage consistency, though it's still 100% up to the widget authors to decide how they implement this since we're only defining an interface.
| } | ||
| ``` | ||
|
|
||
| ## Best Practices |
There was a problem hiding this comment.
This section looks a little "lost" here at the very end of the page. Maybe lead with something like this before all the examples?. Or maybe the section will grow and it will look more natural.
|
|
||
| ## Handling View Interaction Events | ||
|
|
||
| A widget can update in response to a user interacting with the deck.gl view the widget is attached to. |
There was a problem hiding this comment.
This is easily the most important section and needs its own page IMHO. (I do understand that we have work to do here.)
There was a problem hiding this comment.
Say more? What kind of example would you like to see?
There was a problem hiding this comment.
I've been struggling to port the graph layers controller React component to a widget, I was looking for docs on how to implement zooms and pans
|
|
||
| Below is a comprehensive example demonstrating a layer list widget implemented using Preact for dynamic UI rendering: | ||
|
|
||
| ```tsx |
There was a problem hiding this comment.
We should really use MDX capabilities and make these widgets live on the pages...
Co-authored-by: Ib Green <[email protected]>
Co-authored-by: Ib Green <[email protected]>
Co-authored-by: felixpalmer <[email protected]>
| } | ||
| ``` | ||
|
|
||
| ##### Applying the deck.gl widget design system |
There was a problem hiding this comment.
Should applying the design system be it's own page?
| // Handle when props change here. | ||
| this.placement = props.placement ?? this.placement; | ||
| this.viewId = props.viewId ?? this.viewId; | ||
| this.props = {...props}; |
There was a problem hiding this comment.
This could wipe out existing props?
| this.props = {...props}; | |
| this.props = {...this.props, ...props}; |
For #7946
Background
Adding developer guide to include more advanced examples about how to write both react and non-react widgets. This way our getting-started examples can be very simple, and we can have something to point more advanced users to when they're writing their own widgets.
Change List