NAME

Mojolicious::Plugin::Util::Endpoint - Use Template URIs in Mojolicious

SYNOPSIS

# Mojolicious::Lite
plugin 'Util::Endpoint';

# Mojolicious
$self->plugin('Util::Endpoint');

my $rs = $mojo->routes;

# Set endpoint
my $r = $rs->route('/:user')->endpoint(
  webfinger => {
    query  => [
      q => '{uri}'
    ]
  });

return $self->endpoint('webfinger');
# https://sojolicious.example/{user}?q={uri}

$self->stash(user => 'Akron');

return $self->endpoint('webfinger');
# https://sojolicious.example/Akron?q={uri}

return $self->endpoint(webfinger => {
  uri => 'acct:akron@sojolicious.example'
});
# https://sojolicious.example/Akron?q=acct%3Aakron%40sojolicious.example

DESCRIPTION

Mojolicious::Plugin::Util::Endpoint is a plugin that allows for the simple establishment of endpoint URIs. This is similar to url_for, but includes support for template URIs with parameters following RFC6570 Level 1 (as used in, e.g., Host-Meta or OpenSearch).

METHODS

register

# Mojolicious
$app->plugin('Util::Endpoint');

# Mojolicious::Lite
plugin 'Util::Endpoint';

Called when registering the plugin.

SHORTCUTS

endpoint

my $rs = $mojo->routes
my $r = $rs->route('/suggest')->endpoint(
  opensearch => {
    scheme => 'https',
    host   => 'sojolicious.example',
    port   => 3000,
    query  => [
      q     => '{searchTerms}',
      start => '{startIndex?}'
    ]
  });

Establishes an endpoint defined for a service. It accepts optional parameters scheme, host, a port and query parameters (query), overwriting the current values of url_for. Template parameters need curly brackets, optional template parameters need a question mark before the closing bracket. Optional path placeholders are currenty not supported. Returns the route.

Warning: Support for named routes to use with url_for was dropped in v0.19.

HELPERS

endpoint

# In Controller:
#   Set endpoints:
$self->endpoint(hub => 'http://sojolicious.example/search?q={searchTerm}');
$self->endpoint(hub => Mojo::URL->new('http://pubsubhubbub.appspot.com/'));

#   Get endpoints:
return $self->endpoint('webfinger');
return $self->endpoint(webfinger => { user => 'me' } );

# Interpolate arbitrary template URIs
return $self->endpoint(
  'http://sojolicious.example/.well-known/webfinger?resource={uri}&rel={rel?}' => {
    'uri' => 'acct:akron@sojolicious.example',
    '?'   => undef
  });

# In Template:
<%= endpoint 'webfinger' %>

Get or set endpoints defined for a specific service.

For setting it accepts the name of the endpoint and either a string with the endpoint URI or a Mojo::URL object.

For getting it accepts the name of the endpoint or an arbitrary template URI and additional stash values for the route as a hash reference. These stash values override existing stash values from the controller and fill the template variables.

# In Controller:
return $self->endpoint('opensearch');
# https://sojolicious.example/suggest?q={searchTerms}&start={startIndex?}

return $self->endpoint(opensearch => {
  searchTerms => 'simpson',
  '?' => undef
});
# https://sojolicious.example/suggest?q=simpson

The special parameter ? can be set to undef to ignore all undefined optional template parameters.

If the defined endpoint can't be found, the value for url_for is returned.

get_endpoints

# In Controller:
my $hash = $self->get_endpoints;

while (my ($key, $value) = each %$hash) {
  print $key, ' => ', $value, "\n";
};

Returns a hash of all endpoints, interpolated with the current controller stash.

Note: This helper is EXPERIMENTAL and may be deprecated in further releases.

COMMANDS

endpoints

$ perl app.pl endpoints

Show all endpoints of the app established by this plugin.

DEPENDENCIES

Mojolicious (best with SSL support).

CONTRIBUTORS

Viacheslav Tykhanovskyi

AVAILABILITY

https://github.com/Akron/Mojolicious-Plugin-Util-Endpoint

COPYRIGHT AND LICENSE

Copyright (C) 2011-2021, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.

cpanm Mojolicious::Plugin::Util::Endpoint

perl -MCPAN -e shell
install Mojolicious::Plugin::Util::Endpoint