File Coverage: lib/Yukki/Web/Plugin/Role/Formatter.pm

# File Coverage

File: | lib/Yukki/Web/Plugin/Role/Formatter.pm
Coverage: | 92.6%

line | stmt | bran | cond | sub | pod | time | code
--- | --- | --- | --- | --- | --- | --- | ---
1 |  |  |  |  |  |  | package Yukki::Web::Plugin::Role::Formatter;
2 |
3 | 1 1 |  |  | 1 |  | 446 2 | use v5.24;
4 | 1 1 1 |  |  | 1 |  | 3 2 7 | use utf8;
5 | 1 1 1 |  |  | 1 |  | 14 1 6 | use Moo::Role;
6 |
7 |  |  |  |  |  |  | # ABSTRACT: interface for HTML formatters
8 |
9 - 76 |  |
    =head1 SYNOPSIS

      package MyPlugins::SimpleText;
      use 5.12.1;
      use Moo;

      use Types::Standard qw( HashRef Str );

      extends 'Yukki::Web::Plugin';

      has html_formatters => (
          is          => 'ro',
          isa         => HashRef[Str],
          default     => sub { +{
              'text/simple' => 'format_simple',
            } },
      );

      with 'Yukki::Web::Plugin::Role::Formatter;

      sub format_simple {
          my ($self, $file) = @_;

          my $html = $file->fetch;
          $html =~ s/$/<br>/g;

          return [ { title => 'Simple' }, $html ];
      }

    =head1 DESCRIPTION

    This role defines the interface for file formatters. The first formatter matching the MIME type for a file will be used to format a page's contents as HTML.

    =head1 REQUIRED METHODS

    =head2 html_formatters

    This must return a reference to a hash mapping MIME-types to method names.

    The methods will be called with a hashref parameter containing the following:

    =over

    =item context

    The current L<Yukki::Web::Context> object.

    =item repository

    The name of the repository this file is in.

    =item page

    The full path to the name of the file being formatted.

    =item media_type

    This is the media type that Yukki has detected for the file.

    =item content

    The body of the page as a string.

    =back

    The method should return an HTML document.

    =cut
77 |
78 |  |  |  |  |  |  | requires qw( html_formatters );
79 |
80 - 88 |  |
    =head1 METHOD

    =head2 has_format

      my $yes_or_no = $formatter->has_format($media_type);

    Returns true if this formatter plugin has a formatter for the named media type.

    =cut
89 |
90 |  |  |  |  |  |  | sub has_format {
91 | 2 |  |  | 2 | 1 | 3 | my ($self, $media_type) = @_;
92 | 2 | 50 |  |  |  | 15 | return unless defined $media_type;
93 | 2 |  |  |  |  | 12 | return defined $self->html_formatters->{$media_type};
94 |  |  |  |  |  |  | }
95 |
96 - 109 |  |
    =head2 format

      my $html = $self->format({
          context    => $ctx,
          repository => $repository,
          page       => $full_path,
          media_type => $media_type,
          content    => $content,
      });

    Renders the text as HTML. If this plugin cannot format this media type, it
    returns C<undef>.

    =cut
110 |
111 |  |  |  |  |  |  | sub format {
112 | 1 |  |  | 1 | 1 | 2 | my ($self, $params) = @_;
113 |
114 | 1 |  |  |  |  | 4 | my $media_type = $params->{file}->media_type;
115 | 1 | 50 |  |  |  | 97 | return unless $self->has_format($media_type);
116 |
117 | 1 |  |  |  |  | 2 | my $format = $self->html_formatters->{$media_type};
118 | 1 |  |  |  |  | 3 | return $self->$format($params);
119 |  |  |  |  |  |  | }
120 |
121 |  |  |  |  |  |  | 1;