SoftwareDriven.Blockly.Blazor 1.8.0

SoftwareDriven.Blockly.Blazor

A Razor component that embeds a Blockly editor into a Blazor application.

The component hosts the Blockly JavaScript editor through JS interop and hands the workspace back to .NET as Blockly XML. That XML is executed server-side in C# by SoftwareDriven.Blockly.Code — Blockly's own JavaScript code generators are not used.

The required Blockly bundle ships inside the package; npm is only needed to build this package from source, not to consume it.

Installation

dotnet add package SoftwareDriven.Blockly.Blazor

Target framework: net10.0. The package references SoftwareDriven.Blockly.Code.

Add the bundled script to the host page — wwwroot/index.html for Blazor WebAssembly, App.razor / _Host.cshtml for Blazor Server — after the Blazor script:

<script src="_framework/blazor.webassembly.js"></script>
<script src="_content/SoftwareDriven.Blockly.Blazor/js/index.bundle.js"></script>

Quick start

@using SoftwareDriven.Blockly.Blazor.Components

<div id="workspaceArea" style="width: auto; height: 800px;">
    <Workspace @ref="workspace"
               WorkspaceAreaName="workspaceArea"
               Toolbox="@Toolbox"
               BlocksJson="@BlocksJson"
               OnWorkspaceChanged="OnWorkspaceChanged" />
</div>

@code {
    private Workspace? workspace;

    private Toolbox? Toolbox { get; set; }
    private string? BlocksJson { get; set; }

    private async Task Save()
    {
        var xml = await workspace!.Export(false);
        // ... store or execute the XML.
    }

    private void OnWorkspaceChanged() { /* mark as dirty ... */ }
}

The component renders a single div that is positioned and resized over the element named by WorkspaceAreaName. That container must have a size — without an explicit height the editor stays invisible. If WorkspaceAreaName is not set, the parent element is used instead.

Toolbox and BlocksJson normally come from the server, where the same IBlockRepository that later executes the program also describes its blocks:

BlocksJson = await httpClient.GetStringAsync("api/blockly/blocks");
Toolbox = await httpClient.GetFromJsonAsync<Toolbox>("api/blockly/toolbox");

Executing the workspace

Export() returns the Blockly XML, which BlocklyXmlReader turns into an executable program; BlocklyXmlWriter produces XML that Import() accepts again.

using SoftwareDriven.Blockly.Code;
using SoftwareDriven.Blockly.Code.Parser;

var xml = await workspace.Export(toMinimal: false);

var reader = new BlocklyXmlReader();
using var stream = new MemoryStream(Encoding.UTF8.GetBytes(xml));
var control = reader.ReadStream(stream, new BlockControlConfig()
{
    TypeRegistry = typeRegistry,
    BlockRepository = blockRepository,
});

control?.Run(new RunContext() { Caller = "Editor" });

// Load a stored program back into the editor.
await workspace.Import(xml, replace: true);

Parameters

Methods and events

InitializeBlocks, Initialized and GetMembersOfTypeEvent are static events — subscribe before the Workspace renders for the first time and unsubscribe in Dispose().

Supplying toolbox, blocks and types via the initialize event

The InitializeBlocks event is the alternative to the parameters above and is the only way to register additional JavaScript block definitions:

protected override async Task OnInitializedAsync()
{
    Workspace.InitializeBlocks += OnInitializeBlocks;
    Workspace.GetMembersOfTypeEvent += OnGetMembersOfType;
}

void IDisposable.Dispose()
{
    Workspace.InitializeBlocks -= OnInitializeBlocks;
    Workspace.GetMembersOfTypeEvent -= OnGetMembersOfType;
}

private void OnInitializeBlocks(object? sender, InitializeEventArgs args)
{
    args.Toolbox = Toolbox;
    args.BlocksJson = BlocksJson;
    args.VariableTypes = JsonSerializer.Serialize(
        VariableTypes.Select(type => new[] { type.DisplayName, type.TypeName }));

    // The name of a global JS function defining additional blocks.
    args.CustomBlocksFunction = "initCustomBlocks";

    args.LocaleKey = "de";
}

private void OnGetMembersOfType(object? sender, GetMembersOfTypeEventArgs args)
{
    args.Members = TypeRegistry?.GetMembersOfType(args.Type)?
        .Select(member => new TypeMember() { Name = member.MemberName, Type = member.TypeName })
        .ToList() ?? new();
}

Typed variables

When VariableTypes is set, Blockly's typed-variable dialog is used. Set OnCreateTypedVariable to replace it with an own dialog:

private async Task<VariableModel> OnCreateTypedVariable(VariableModel[] usedVariables)
{
    var result = await ShowMyDialogAsync(usedVariables);
    return result ?? new VariableModel(); // An empty model cancels the creation.
}

Localization

The component ships English and German texts; Blockly itself is bundled with en, de, es and fr. Own resources are merged in, and the locale is applied to both Blockly and the component:

Workspace.AddLocalizationResource(Resources.ResourceManager);

await workspace.SetLocale("de");

Category and block names may use Blockly's message references, e.g. %{BKY_CATEGORY_LOGIC}, so that they are translated from those resources.