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://sojolicio.us/{user}?q={uri}

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

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

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

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   => 'sojolicio.us',
      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://sojolicio.us/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://sojolicio.us/.well-known/webfinger?resource={uri}&rel={rel?}' => {
      'uri' => 'acct:akron@sojolicio.us',
      '?'   => 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://sojolicio.us/suggest?q={searchTerms}&start={startIndex?}

  return $self->endpoint(opensearch => {
    searchTerms => 'simpson',
    '?' => undef
  });
  # https://sojolicio.us/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-2015, 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