lib/CatalystX/HelpText/Model.pm

   1 package CatalystX::HelpText::Model;
   2 use Moose;
   3 use MooseX::Types::Moose qw/Str Undef/;
   4 use MooseX::Types::Path::Class qw/ Dir /;
   5 use Moose::Autobox;
   6 use Carp qw/ croak confess/;
   7 use namespace::autoclean;
   8
   9 extends 'Catalyst::Model';
  10
  11 has help_files_path => (
  12     is => 'ro',
  13     isa => Dir,
  14     coerce => 1,
  15     required => 1,
  16     handles => {
  17         _get_file => 'file',
  18     }
  19 );
  20
  21 has help_files_ext => (
  22     is => 'ro',
  23     isa => Str|Undef,
  24     default => 'html',
  25 );
  26
  27 has wrapper_css_class => (
  28     is => 'ro',
  29     isa => Str,
  30     default => 'help_text',
  31 );
  32
  33 has wrapper_tag => (
  34     is => 'ro',
  35     isa => Str,
  36     default => 'span',
  37 );
  38
  39
  40 sub get_help_text_for {
  41     my ($self, $help_key) = @_;
  42     confess('No $help_key provided') unless $help_key;
  43
  44     my $fn = $help_key;
  45     $fn .= "." . $self->help_files_ext if defined($self->help_files_ext);
  46
  47     my $file = $self->_get_file($fn);
  48
  49     if ( -e $file ) {
  50         my $content = $file->slurp;
  51         return sprintf('<%s class="%s">%s</%s>',
  52             $self->wrapper_tag,
  53             $self->wrapper_css_class,
  54             $content,
  55             $self->wrapper_tag
  56         );
  57     }
  58
  59     croak "Cannot find help text '$help_key' in $file";
  60 }
  61
  62 __PACKAGE__->meta->make_immutable;
  63 1;
  64
  65 =head1 NAME
  66
  67 CatalystX::HelpText::Model - Model to provide snippets of help text
  68
  69 =head1 SYNOPSIS
  70
  71     package MyApp::Model::Help;
  72     use Moose;
  73     use namespace::autoclean;
  74
  75     extends 'CatalystX::HelpText::Model';
  76
  77     1;
  78
  79 =head1 DESCRIPTION
  80
  81 A very simple file system based help text finder.
  82
  83 Expects each piece of help text to be in an individual file, and provides a
  84 C<get_help_text_for> method as used by L<CatalaystX::HelpText::ViewRole> which
  85 just slurps in this file verbatim.
  86
  87 Users are expected (and encouraged) to replace the simple logic in this
  88 model with a more complicated method of help text resolution if needed.
  89
  90 =head1 METHODS
  91
  92 =head1 get_help_text_for ($help_key)
  93
  94 Returns a snippet of help text.
  95
  96 Will throw an exception if the requested help key is not found.
  97
  98 =head1 CONFIGURATION ATTRIBUTES
  99
 100 XXX - FIXME - document these
 101
 102 =head2 help_files_path
 103
 104 =head2 help_files_ext
 105
 106 =head2 wrapper_css_class
 107
 108 =head2 wrapper_tag
 109
 110 =head1 BUGS
 111
 112 =head2 File system only.
 113
 114 Currently we only support getting help texts from the file system (as individual files).
 115
 116 A model to get help from a database table, or YAML file or similar could (and should)
 117 be provided as part of this distribution. Patches are welcome!
 118
 119 =head1 SEE ALSO
 120
 121 =over
 122
 123 =item L<CatalystX::HelpText>
 124
 125 =back
 126
 127 =head1 AUTHOR
 128
 129 Toomas Doran, C<< t0m at state51.co.uk >>
 130
 131 Cinxgler Mariaca Minda, C<< cinxgler at ci-info.com >>
 132
 133 =head1 COPYRIGHT
 134
 135 Copyright Oscar Music and Media 2011.
 136
 137 =head1 LICENSE
 138
 139 This sofware is free software, and is licensed under the same terms as perl itself.
 140
 141 =cut
 142