[FEATURE]: Extensibility - create a template for extensions.

[ryanspain]

Is your feature request related to a problem?

No response

Describe the solution you'd like

I'd like to be able to add custom functions/utilities to the JavaScript interop module to perform more advanced interactions with the rendered map. For example, orbiting around a specific point on the map as is demonstrated in the example Animate map camera around a point.

The implementation of this is simple, but could be more advanced, combining many routines/API usages into one utility function.

function rotateCamera(timestamp) {
    clamp the rotation between 0 -360 degrees
    Divide timestamp by 100 to slow rotation to ~10 degrees / sec
    map.rotateTo((timestamp / 100) % 360, {duration: 0});
    Request the next frame of the animation.
    requestAnimationFrame(rotateCamera);
}

The main need for extensibility comes from my understanding that only the MapLibre.razor.js interop library has first-class access to the map instances (and options) on the page. It's likely possible to "new up" some reference to the maps, but first-party extensibility would be better.

Describe alternatives you've considered

I made a new component named MapLibre2 that extends MapLibre. This works to some degree and would need some more thought if this is a the preferred method, but most of the extensibility scenarios require running JavaScript. With that, I think support for extending the JavaScript interop module could be explored.

MapLibre JS Reference

See this example from MapLibre: Animate map camera around a point

Example Usage

// Using custom `Orbit` method
private MapLibre? _map { get; set; }
...
_map.Orbit(duration: 2000);

Worth noting this is an overly simple articulation of the idea. It would be up to the consumer to design the new APIs/method signatures.

Additional context

I think it's fair to say that it's best if this library continues to just wrap MapLibre. Sure, a bunch of extensions/utilities would be helpful, but they would add to the maintenance overhead of the project.

Instead, I propose a discussion around how the project can given consumers the ability to extend the interop library with their own functions while still using the same API (core MapLibre Razor component).

Contribution

• I'm interested in implementing this feature with guidance

[MatejMa2ur]

Hi,
thank you for this point, i currently also reached a point, where I am not sure which way to proceed, because I need to use the Mapbox Draw GLJS.

And I just implemented a version but I do not think it is correct to do it in a way I did it.

So any suggestion from anyone are welcome I would look into the issue, if there is some nice way to make it more extensible.

[MatejMa2ur]

Little Off topic, but still important.

Also related to the managing of the library and ease of communication, I am starting a coding community, I know there are a lot of already ones in the world. https://github.com/Cod3rs-org

But I wanted to start with something local for me and my friends but I am open for all the communication also if people would like to talk more about the issues or suggestions of the library, feel free to join us, I am down to talk about it on the Discord: https://cod3rs.org/

[ryanspain]

Great work on this library so far @MatejMa2ur.

I'll have a think about the extensibility options more over the next few weeks and I'll take a look at tool mapbox-gl-draw you mentioned above.

[MatejMa2ur]

Also how about if we would make some kind of Plugin System like:

public interface IMapLibrePlugin
{
    string Name { get; }
    Task InitializeAsync(IJSRuntime jsRuntime, string containerId, DotNetObjectReference<object> dotNetRef);
    Task<IJSObjectReference> GetJsModuleAsync();
}

// Add to existing MapLibre.razor.cs class
private readonly List<IMapLibrePlugin> _plugins = new();

public void RegisterPlugin(IMapLibrePlugin plugin)
{
    _plugins.Add(plugin);
}

// Modify existing initialization to include plugin initialization
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        await InitializeMap();
        
        // Initialize all registered plugins
        foreach (var plugin in _plugins)
        {
            await plugin.InitializeAsync(JSRuntime, ContainerId, DotNetReference);
        }
    }
}

// Add method to expose map object
public async Task<IJSObjectReference> GetMapObjectAsync()
{
    return await JSModule.InvokeAsync<IJSObjectReference>("getMapInstance", ContainerId);
}

Something similar... I think this could be really cool, because than I could make the DrawGLJS as a plugin so it could be split separatelly.

And than you would have the IJSObjectReference and you could than invoke or run any command you would like to you could than also extend on it. I am not saying, it is perfect solution but I like it.

[ryanspain]

That looks promising. I like it.

Would the plugin have access to the same map instance though? Presumably IMapLibrePlugin.GetJsModuleAsync would allow a consumer to load in their own JavaScript module, but this way it'd only know about the map ID (ContainerId).

Speaking Thinking out load here...

Or I guess that's where MapLibre.GetMapObjectAsync comes in. It will provide a reference to the map element on the page and allow for interop using maplibregl.

But would a new maplibregl.Map instance need to be created within the plugin instances JavaScript module?

[MatejMa2ur]

Based on quick searchin on internet, I found few mentions that yes you should get the reference to the instance:
https://swimburger.net/blog/dotnet/interacting-with-javascript-objects-using-the-new-ijsobjectreference-in-blazor

But I never used it, so I do not know exactly if it will work, so yep same here just:
Speaking Thinking out load here...

[ryanspain]

Ah, I never expected to feel nostalgic after seeing a swimburger.net article after so long. This looks promising.

[ryanspain]

@MatejMa2ur I opened a draft pull request with a simple enough solution based on your idea above. See #95.

It deviates slightly in that it I simply return the map object from the JavaScript module on initialize. Then this map object is provided to other libraries.

Other libraries can assume the Map Libre GL JS JavaScript module has already been loaded into the JavaScript runtime so they only need to worry about loading in their custom/third-party libraries.

[MatejMa2ur]

Just one suggestion came to my mind, what we could do is create a simple project template, which will set the basic stuff for you.

It is not required, but I feel like it could be nice to have.
https://learn.microsoft.com/en-us/dotnet/core/tutorials/cli-templates-create-project-template