README

Mount compiled Elm apps into WordPress admin pages, shortcodes and other surfaces. Handles the enqueue, the localized flags blob, and the REST nonce. Bundling your Elm is your job — this package takes the compiled .js and wires it into WordPress.

Part of a three-package set:

Install

composer require pinkcrab/elm-mount

Usage

Build an Elm_App once with your script + flags, then call render() (echoes) or parse() (returns a string) from any WordPress callback that produces output — admin page, shortcode, meta box, widget, REST handler, template part. The same $app works for all of them.

use PinkCrab\ElmMount\Elm_App;

$app = Elm_App::create( 'my_settings' )
    ->script( plugin_dir_url( __FILE__ ) . 'build/main.js' )
    ->flags( [
        'pageTitle' => __( 'My Settings', 'td' ),
        'canEdit'   => current_user_can( 'manage_options' ),
    ] );

// Admin page / meta box — echo
add_submenu_page(
    'options-general.php',
    'My Settings',
    'My Settings',
    'manage_options',
    'my-settings',
    fn() => $app->render()
);

// Shortcode — return string
add_shortcode( 'my_app', fn() => $app->parse() );

Both render() and parse() enqueue the script, localize the flags blob on window.my_settings, and produce <div id="my_settings-root"></div> for Elm to attach to. The mount node id defaults to {handle}-root; override with ->mount_node( 'custom-id' ) if needed.

Your compiled Elm bundle reads window.my_settings and mounts into #my_settings-root — @pinkcrab/elm-wp-bootstrap handles that plumbing automatically.

Contract

This section is the authoritative spec shared by all three packages. Any change here is a contract bump and must be mirrored in the other two repos in lockstep.

Flags blob

Emitted via wp_localize_script( $handle, $handle, $blob ). The JavaScript side reads it from window.<handle> and hands it to Elm as flags.

{
  "restRoot":     "https://example.test/wp-json/",
  "restNonce":    "abc123...",
  "restNamespace":"wp/v2",
  "ajaxUrl":      "https://example.test/wp-admin/admin-ajax.php",
  "ajaxNonce":    "def456...",
  "mountNode":    "my_settings-root",
  "locale":       "en_GB",
  "currentUser": {
    "id":          1,
    "displayName": "Glynn Quelch",
    "roles":       ["administrator"],
    "capabilities":["manage_options", "edit_posts"]
  },
  "pluginData": {
    "pageTitle": "My Settings",
    "canEdit":   true
  }
}

Notes:

• restNonce is minted from the wp_rest action and is what wp.apiFetch needs.
• ajaxNonce is minted from a package-specific action (one per handle) for the legacy admin-ajax.php path.
• pluginData is the only free-form section — user-supplied flags via ->flags( [...] ).
• capabilities is a UI hint for Elm to disable buttons etc; never trust it for authorisation (server-side checks are the real gate).

Port names

The JS bootstrap and the Elm package must agree on these names. Changing any is a contract break.

id on wpApiFetch / wpApiFetchResult is a string correlation id the Elm side generates so multiple in-flight requests can be matched to their responses.

Versioning

All three packages share a major version. Within 1.x, minor and patch versions can move independently per package — compatibility is guaranteed across the same major.

License

MIT © PinkCrab