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).

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