Update README and fix script path in Makefile.PL

[catagits/CatalystX-HelpText.git] / lib / CatalystX / HelpText / Model.pm

package CatalystX::HelpText::Model;
use Moose;
use MooseX::Types::Moose qw/Str Undef/;
use MooseX::Types::Path::Class qw/ Dir /;
use Moose::Autobox;
use Carp qw/ croak confess/;
use namespace::autoclean;

extends 'Catalyst::Model';

has help_files_path => (
    is => 'ro',
    isa => Dir,
    coerce => 1,
    required => 1,
    handles => {
        _get_file => 'file',
    }
);

has help_files_ext => (
    is => 'ro',
    isa => Str|Undef,
    default => 'html',
);

has wrapper_css_class => (
    is => 'ro',
    isa => Str,
    default => 'help_text',
);

has wrapper_tag => (
    is => 'ro',
    isa => Str,
    default => 'span',
);


sub get_help_text_for {
    my ($self, $help_key) = @_;
    confess('No $help_key provided') unless $help_key;

    my $fn = $help_key;
    $fn .= "." . $self->help_files_ext if defined($self->help_files_ext);

    my $file = $self->_get_file($fn);

    if ( -e $file ) {
        return sprintf('<%s class="%s">%s</%s>',
            $self->wrapper_tag,
            $self->wrapper_css_class,
            $file->slurp,
            $self->wrapper_tag
        );
    }

    croak "Cannot find help text '$help_key' in $file";
}

__PACKAGE__->meta->make_immutable;
1;

=head1 NAME

CatalystX::HelpText::Model - Model to provide snippets of help text

=head1 SYNOPSIS

    package MyApp::Model::Help;
    use Moose;
    use namespace::autoclean;

    extends 'CatalystX::HelpText::Model';

    1;

=head1 DESCRIPTION

A very simple file system based help text finder.

Expects each piece of help text to be in an individual file, and provides a
C<get_help_text_for> method as used by L<CatalaystX::HelpText::ViewRole> which
just slurps in this file verbatim.

Users are expected (and encouraged) to replace the simple logic in this
model with a more complicated method of help text resolution if needed.

=head1 METHODS

=head1 get_help_text_for ($help_key)

Returns a snippet of help text.

Will throw an exception if the requested help key is not found.

=head1 CONFIGURATION ATTRIBUTES

XXX - FIXME - document these

=head2 help_files_path

=head2 help_files_ext

=head2 wrapper_css_class

=head2 wrapper_tag

=head1 BUGS

=head2 File system only.

Currently we only support getting help texts from the file system (as individual files).

A model to get help from a database table, or YAML file or similar could (and should)
be provided as part of this distribution. Patches are welcome!

=head1 SEE ALSO

=over

=item L<CatalystX::HelpText>

=back

=head1 AUTHOR

Toomas Doran, C<< t0m at state51.co.uk >>

Cinxgler Mariaca Minda, C<< cinxgler at ci-info.com >>

=head1 COPYRIGHT

Copyright Oscar Music and Media 2011.

=head1 LICENSE

This sofware is free software, and is licensed under the same terms as perl itself.

=cut