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         return sprintf('<%s class="%s">%s</%s>',
  51             $self->wrapper_tag,
  52             $self->wrapper_css_class,
  53             $file->slurp,
  54             $self->wrapper_tag
  55         );
  56     }
  57
  58     croak "Cannot find help text '$help_key' in $file";
  59 }
  60
  61 __PACKAGE__->meta->make_immutable;
  62 1;
  63
  64 =head1 NAME
  65
  66 CatalystX::HelpText::Model - Model to provide snippets of help text
  67
  68 =head1 SYNOPSIS
  69
  70     package MyApp::Model::Help;
  71     use Moose;
  72     use namespace::autoclean;
  73
  74     extends 'CatalystX::HelpText::Model';
  75
  76     1;
  77
  78 =head1 DESCRIPTION
  79
  80 A very simple file system based help text finder.
  81
  82 Expects each piece of help text to be in an individual file, and provides a
  83 C<get_help_text_for> method as used by L<CatalaystX::HelpText::ViewRole> which
  84 just slurps in this file verbatim.
  85
  86 Users are expected (and encouraged) to replace the simple logic in this
  87 model with a more complicated method of help text resolution if needed.
  88
  89 =head1 METHODS
  90
  91 =head1 get_help_text_for ($help_key)
  92
  93 Returns a snippet of help text.
  94
  95 Will throw an exception if the requested help key is not found.
  96
  97 =head1 CONFIGURATION ATTRIBUTES
  98
  99 XXX - FIXME - document these
 100
 101 =head2 help_files_path
 102
 103 =head2 help_files_ext
 104
 105 =head2 wrapper_css_class
 106
 107 =head2 wrapper_tag
 108
 109 =head1 BUGS
 110
 111 =head2 File system only.
 112
 113 Currently we only support getting help texts from the file system (as individual files).
 114
 115 A model to get help from a database table, or YAML file or similar could (and should)
 116 be provided as part of this distribution. Patches are welcome!
 117
 118 =head1 SEE ALSO
 119
 120 =over
 121
 122 =item L<CatalystX::HelpText>
 123
 124 =back
 125
 126 =head1 AUTHOR
 127
 128 Toomas Doran, C<< t0m at state51.co.uk >>
 129
 130 Cinxgler Mariaca Minda, C<< cinxgler at ci-info.com >>
 131
 132 =head1 COPYRIGHT
 133
 134 Copyright Oscar Music and Media 2011.
 135
 136 =head1 LICENSE
 137
 138 This sofware is free software, and is licensed under the same terms as perl itself.
 139
 140 =cut
 141