map-ui-sdk
map-ui-sdk is an alpha-stage UI toolkit, built with React and TypeScript, aimed at enhancing mapping interfaces with interactive UI panels integrated with our MapsGL service. Currently it offers a control for managing map layer visibility and styling as well as a timeline control for easily manipulating and animating the time range data for the map.
Supported Mapping Libraries
Map UI SDK currently supports the third-party mapping libraries supported by MapsGL
Getting Started
yarn add @xweather/map-ui-sdk@alpha
Example Project
map-ui-sdk includes an example project that demonstrates how to use the SDK with a mapping library. The example project is located in the example
directory, separate from the SDK implementation code. Follow the steps below to get the example project up and running:
Prerequisites
- An Xweather account— We offer a free developer account for you to give our weather API a test drive.
- A Mapbox account
Steps to Run
-
Get Xweather MapsGL ID and Secret
Log into your Xweather account, and from your account's Apps page, create a new application for the MapsGL Demo app. Make note of application's Xweather MapsGL ID and Secret; you'll need them in step 5.
-
Get Xweather Mapbox public access token
The example project relies on Mapbox, so you'll need to log into or create a Mapbox account and follow the instructions to create a Mapbox public access token.
-
Navigate to the Example Directory
After downloading or cloning map-ui-sdk from npm, navigate to the example
directory within the SDK:
> cd ./example
- Install Dependencies
Once you're in the
example
directory, install the project's dependencies by running:
> yarn install
- Update environment variables
Rename .env.template at the root of the example repo to .env and add the necessary Xweather and Mapbox access key:
VITE_MAPBOX_KEY=''
VITE_MAPSGL_ID=''
VITE_MAPSGL_SECRET=''
-
Import styles
You will need to import this stylesheet at the root of your project:
import '@xweather/map-ui-sdk/dist/style.css'
-
Run the project in development mode:
> yarn dev
Exploring the Example Project
This project demonstrates an example configuration of the <LayersPanel/>
which offers the ability to customize which layers are displayed and how they are styled through the layersConfig
prop.
layerConfig
example:
import {SAMPLE,COLOR_SCALE, DATA, ButtonListConfig} from '@xweather/map-ui-sdk';
const layersConfig: ButtonListConfig = [{
title: 'Conditions',
buttons: [
{
id: 'temperatures',
title: 'Temperatures',
value: 'temperatures',
selected: false,
controls: {
settings: [
{
name: SAMPLE.opacity,
overrides: {
value: 90
}
},
COLOR_SCALE,
SAMPLE.colorscale.interval,
DATA.quality
]
}
},
{
id: 'wind',
title: 'Winds',
selected: false,
multiselect: false,
segments: [{
id: 'wind-barbs',
title: 'Barbs',
value: 'wind-barbs',
controls: {
settings: [
GRID.spacing,
SYMBOL.size
]
}
},
{
id: 'wind-particles',
title: 'Particles',
value: 'wind-particles',
controls: {
settings: [
COLOR_SCALE,
SAMPLE.smoothing,
PARTICLE.speed,
PARTICLE.size,
PARTICLE.density,
DATA.quality
]
}
}, {
id: 'wind-speeds',
title: 'Fill',
value: 'wind-speeds'
}]
}
]
}];
map-ui-sdk implements the Provider pattern to facilitate data sharing and state management across UI components allowing for increased component reusability. In order to use MapsGL-specific layers, simply wrap the <LayersPanel/>
in <MapsGLLayerStateProvider />
(provide its initial state; the same layersConfig
passed to the <LayersPanel/>
), and MapController
. By also utilizing the Drawer
and Tabs
components, you can quickly build an interface for mapping layer interactions.
Below is a simplified version to show the basic component structure, review App.jsx
in the example project for the full implementation:
<MapController>
<MapsGLLayerStateProvider initialState={layersConfig}>
<DrawerProvider>
<TabsProvider defaultValue="layers">
<Drawer>
<Tabs.Content value="layers">
<LayersPanel layersConfig={layersConfig} />
</Tabs.Content>
<Tabs.Content value="settings">
<SettingsPanel />
</Tabs.Content>
<Tabs.List>
<Tabs.Button value="layers" />
<Tabs.Button value="settings" />
</Tabs.List>
</Drawer>
</TabsProvider>
</DrawerProvider>
</MapsGLLayerStateProvider>
</MapController>
Additionally, the example project demonstrates the <MapsGLTimelinePanel />
which wraps the TimelinePanel
and encapsulates the MapsGL integration, allowing for easy animation control of mapping layers. Included in the TimelinePanel
is a settings button that enables on-the-fly configuration of the time range as well as the speed of animation. Any layers that are currently selected in the layers panel and have animation capability will respond to the TimelinePanel
controls.
Usage
Since map-ui-sdk is written in TypeScript you can refer to the .d.ts
declaration files in the dist
folder for comprehensive type definitions. These mirror the SDK's structure offering insights into component interfaces and configurations. In particular the <LayersPanel />
and <TimelinePanel />
types can be found inside the dist/views
and the various providers are located inside dist/providers
.
MapsGL Resources
Use the following resources to learn more about MapsGL and the wide range of customization options, or to view a variety of demos and examples:
Support
For all MapsGL-specific support, submit a new ticket with any questions, bug reports or feature suggestions you have.