Permalink
Browse files

put README.pod back

  • Loading branch information...
1 parent 524e5f5 commit b336794b4da3bbde9efd3cf814618ccf350f586c sshaw committed Aug 22, 2012
Showing with 115 additions and 1 deletion.
  1. +3 −0 Changes
  2. +2 −1 Makefile.PL
  3. +110 −0 README.pod
View
@@ -1,3 +1,6 @@
+2012-XX-XX v0.05
+* Bug fix: Build failed if perldoc was not in the PATH (thanks Andreas J. König)
+
2012-09-14 v0.04
* Bug fix: remove whitespace from DOM IDs
* Require Mojolicious >= 2.20
View
@@ -11,12 +11,13 @@ WriteMakefile(NAME => 'Mojolicious::Plugin::DomIdHelper',
# Create README.pod for a repo's GitHub page. Unlike CPAN, GitHub won't
# display the module's POD, it looks for a README.*
+use Config;
sub MY::postamble
{
my $self = shift;
return if -r 'README' or ! -r $self->{VERSION_FROM};
return<<END_MAKE;
README.pod: $self->{VERSION_FROM}
- \@perldoc -uT $self->{VERSION_FROM} > README.pod
+ \@$Config{bin}/perldoc -uT $self->{VERSION_FROM} > README.pod
END_MAKE
}
View
@@ -0,0 +1,110 @@
+=head1 NAME
+
+Mojolicious::Plugin::DomIdHelper - Mojolicious plugin to generate DOM IDs and CSS class names from your ORM objects
+
+=head1 SYNOPSIS
+
+ # Mojolicious
+ $self->plugin('dom_id_helper');
+
+ # Or, your defaults
+ $self->plugin('dom_id_helper', delimiter => '-')
+
+ # Mojolicious::Lite
+ plugin 'dom_id_helper';
+
+ # Set defaults
+ plugin 'dom_id_helper', delimiter => '-'
+
+ # Your view
+ <div id="<%= dom_id($object) %>" class="<%= dom_class($object) %>">
+ ...
+ </div>
+
+ <div id="<%= dom_id($object, method => 'name') ) %>">
+ ...
+ </div>
+
+=head1 DESCRIPTION
+
+DOM IDs are generated by joining an object's package name and its primary key with the character
+specified by the L</delimiter> option. By default the primary key is retrieved via a method
+named C<id>. This can be modified, see L</OPTIONS>.
+
+By default, given an instance of C<DB::Package::User> with an ID of C<1>:
+
+ dom_id($user)
+ dom_class($user)
+
+will generate:
+
+ user_1
+ user
+
+For C<dom_id>, if the primary key is undefined only the package name is returned.
+If C<$user> is not a reference C<undef> is returned.
+
+Multi-column primary keys are not separated by the L</delimiter> option, they are concatenated.
+
+For references that aren't blessed C<dom_id> and C<dom_class> return the reference type.
+If Lingua::EN::Inflect is installed array references that contain a blessed reference will return
+the pluralized form of the blessed reference.
+
+For example, if Lingua::EN::Inflect is installed:
+
+ dom_id([$user])
+ dom_class([$user])
+ dom_id([])
+ dom_id({ user => $user })
+ dom_id({})
+
+will generate:
+
+ users
+ users
+ array
+ hash
+ hash
+
+If Lingua::EN::Inflect is not installed C<dom_id([$user])> will return C<array>.
+
+=head1 ORMs
+
+The aim is to be ORM agnostic. Just set the L</method> option to the name of the method used to
+retrieve your object's primary key.
+
+Multi-column primary keys returned as array references will cause problems (for now).
+
+=head1 OPTIONS
+
+=head2 C<delimiter>
+
+ plugin 'dom_id_helper', delimiter => '-'
+
+The character used to delimit the object's package name from its primary key. Defaults to C<'_'>.
+
+=head2 C<method>
+
+ plugin 'dom_id_helper', method => 'name'
+ plugin 'dom_id_helper', method => [qw{first_name last_name}]
+
+The method used to retrieve the object's primary key. Defaults to C<'id'>.
+
+=head2 C<keep_namespace>
+
+ plugin 'dom_id_helper', keep_namespace => 1
+
+Keep the full package name when generating the DOM ID. Defaults to C<0> (false).
+
+=head1 AUTHOR
+
+Skye Shaw <sshaw AT lucas.cis.temple.edu>
+
+=head1 SEE ALSO
+
+L<Mojolicious> and L<Mojolicious::Plugin::TagHelpers>
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
+

0 comments on commit b336794

Please sign in to comment.