Improve MapboxImageryProvider documentation

[Maarondesigns]

After the recent change removing default mapbox imagery, I struggled for a few hours to implement it on my own. The documentation for MapboxImageryProvider only gives one tiny example which only works for satellite imagery with no labels. I was not ever successful getting any other mapbox imagery to display using that class, however, I eventually got it to work using UrlTemplateImageryProvider and just passing in the entire url string:

new Cesium.UrlTemplateImageryProvider({
                    url: `https://api.mapbox.com/styles/v1/mapbox/satellite-streets-v11/tiles/256/{z}/{x}/{y}?access_token=${mbToken}`
                });

To add to the baselayer picker this is my complete code:

        let mapBoxSatStreets = new Cesium.ProviderViewModel({
            name: "Mapbox Streets with Labels",
            iconUrl: "./img/...",
            tooltip: "Mapbox Satellite with Labels",
            category: "Mapbox",
            creationFunction: function() {
                return new Cesium.UrlTemplateImageryProvider({
                    url: `https://api.mapbox.com/styles/v1/mapbox/satellite-streets-v11/tiles/256/{z}/{x}/{y}?access_token=${mbToken}`
                });
            }
        });
        let blp = viewer.baseLayerPicker.viewModel;
        blp.imageryProviderViewModels.unshift(mapBoxSatStreets);

For classic streets just replace satellite-streets-v11 with streets-v11.
It took some serious digging to find the correct names for a tilesets in Mapbox's documentation.

Hope this helps anyone in a similar situation.

[OmarShehata]

@Maarondesigns which doc were you looking at? This one has an example that works with streets-v11 or satellites-streets-v11 etc:

https://cesium.com/docs/cesiumjs-ref-doc/MapboxStyleImageryProvider.html?classFilter=MapboxStyle

This would be the easiest way to add it to your app:

var streetsLayer = new Cesium.MapboxStyleImageryProvider({
    styleId: 'satellite-streets-v11',
    accessToken: 'yourToken'
});

var imageryLayer = viewer.imageryLayers.addImageryProvider(
  streetsLayer
);

MapboxImageryProvider uses the old API (see doc on Map id being deprecated https://docs.mapbox.com/help/glossary/map-id/) so that's why it doesn't work with the new styleId's you were passing in. Perhaps the doc just needs to have a note on the MapboxImageryProvider warning you this is using the old API.

There was some discussion about removing MapboxImageryProvider in this PR, but it seems that the old API is still functional and in use: #7698 (comment).

[OmarShehata]

Perhaps it would be best to remove the old provider, since there's nothing you can do with the deprecated API that you can't do with the new one.

[wisdomware]

@Maarondesigns which doc were you looking at? This one has an example that works with streets-v11 or satellites-streets-v11 etc:

https://cesium.com/docs/cesiumjs-ref-doc/MapboxStyleImageryProvider.html?classFilter=MapboxStyle

This would be the easiest way to add it to your app:

var streetsLayer = new Cesium.MapboxStyleImageryProvider({
    styleId: 'satellite-streets-v11',
    accessToken: 'yourToken'
});

var imageryLayer = viewer.imageryLayers.addImageryProvider(
  streetsLayer
);

MapboxImageryProvider uses the old API (see doc on Map id being deprecated https://docs.mapbox.com/help/glossary/map-id/) so that's why it doesn't work with the new styleId's you were passing in. Perhaps the doc just needs to have a note on the MapboxImageryProvider warning you this is using the old API.

There was some discussion about removing MapboxImageryProvider in this PR, but it seems that the old API is still functional and in use: #7698 (comment).

@OmarShehata, your code worked perfectly for me. Thank you very much!