NAME

Chandra::Protocol - Custom URL protocol handlers for Chandra applications

SYNOPSIS

use Chandra::App;

my $app = Chandra::App->new(title => 'My App');

# Register a custom protocol
$app->protocol->register('myapp', sub {
    my ($path, $params) = @_;
    if ($path eq 'settings') {
        return { page => 'settings', user => $params->{user} };
    }
    return { page => $path };
});

$app->set_content(q{
    <a href="myapp://settings?user=admin">Settings</a>
    <a href="myapp://about">About</a>
});
$app->run;

# In JavaScript:
#   window.__chandraProtocol.navigate('myapp://dashboard?tab=home')
#     .then(result => console.log(result));

DESCRIPTION

Chandra::Protocol enables custom URL scheme handling in Chandra applications. When a user clicks a link with a registered scheme (e.g. myapp://path?key=val), the click is intercepted and the registered Perl handler is called with the path and parsed query parameters.

Handlers can also be invoked programmatically from JavaScript via window.__chandraProtocol.navigate(url).

The injected JavaScript also transparently intercepts <link>, <script>, <img>, and fetch() calls whose URLs match a registered scheme. For <link> and <script> elements the content is fetched via the Perl handler and injected inline; for <img> elements the data is base64-encoded into a data URI. A MutationObserver watches for dynamically added elements as well.

To avoid "Failed to load resource: unsupported URL" warnings in the developer console, use data-href / data-src attributes instead of plain href / src:

<link rel="stylesheet" data-href="myapp://css/style.css">
<script data-src="myapp://js/app.js"></script>
<img data-src="myapp://images/logo.png">

Both forms (data-* and native attributes) are supported.

This is implemented entirely in Perl + JavaScript — no C-level protocol registration is required.

METHODS

new(%args)

Create a new Protocol instance. Usually accessed via $app->protocol.

register($scheme, $coderef)

Register a handler for a custom URL scheme. The handler receives ($path, $params_hashref).

schemes()

List all registered scheme names.

is_registered($scheme)

Check whether a scheme is registered.

inject()

Inject the protocol handler JavaScript. Called automatically by Chandra::App->run() when protocols are registered.

js_code()

Return the JavaScript source for manual injection.

SEE ALSO

Chandra::App