SL/DB/Helper/DisplayableNamePreferences.pm

   1 package SL::DB::Helper::DisplayableNamePreferences;
   2
   3 use strict;
   4
   5 use parent qw(Exporter);
   6 our @EXPORT = qw(displayable_name displayable_name_prefs displayable_name_specs specify_displayable_name_prefs);
   7
   8 use Carp;
   9 use List::MoreUtils qw(none);
  10
  11 use SL::Helper::UserPreferences::DisplayableName;
  12
  13
  14 my %prefs_specs;
  15 my %prefs;
  16
  17 sub import {
  18   my ($class, %params) = @_;
  19   my $importing = caller();
  20
  21   $params{title} && $params{options}  or croak 'need params title and options';
  22
  23   $prefs_specs{$importing} = \%params;
  24   $prefs{$importing}       = SL::Helper::UserPreferences::DisplayableName->new(
  25     module => $importing
  26   );
  27
  28   # Don't 'goto' to Exporters import, it would try to parse @params
  29   __PACKAGE__->export_to_level(1, $class, @EXPORT);
  30 }
  31
  32 sub displayable_name {
  33   my ($self) = @_;
  34
  35   my $specs = $self->displayable_name_specs;
  36   my $prefs = $self->displayable_name_prefs;
  37
  38   my @names = $prefs->get =~ m{<\%(.+?)\%>}g;
  39   my $display_string = $prefs->get;
  40   foreach my $name (@names) {
  41     next if none {$name eq $_->{name}} @{$specs->{options}};
  42     my $val         = $self->can($name) ? $self->$name // '' : '';
  43     $display_string =~ s{<\%$name\%>}{$val}g;
  44   }
  45
  46   return $display_string;
  47 }
  48
  49 sub displayable_name_prefs {
  50   my $class_or_self = shift;
  51   my $class         = ref($class_or_self) || $class_or_self;
  52
  53   return $prefs{$class};
  54 }
  55
  56 sub displayable_name_specs {
  57   my $class_or_self = shift;
  58   my $class         = ref($class_or_self) || $class_or_self;
  59
  60   return $prefs_specs{$class};
  61 }
  62
  63 1;
  64 __END__
  65
  66 =pod
  67
  68 =encoding utf8
  69
  70 =head1 NAME
  71
  72 SL::DB::Helper::DisplayableNamePreferences - Mixin for managing displayable
  73 names configured via user preferences
  74
  75 =head1 SYNOPSIS
  76
  77   # DB object
  78   package SL::DB::SomeObject;
  79   use SL::DB::Helper::DisplayableNamePreferences(
  80     title   => t8('Some Object'),
  81     options => [ {name => 'some_attribute_1', title => t8('Some Attribute One') },
  82                  {name => 'some_attribute_2,  title => t8('Some Attribute Two') },
  83
  84   );
  85
  86   # Controller using displayable_name
  87   package SL::Controller::SomeController;
  88   $obj       = SL::DB::SomeObject->get_first;
  89   my $output = $obj->displayable_name;
  90
  91   # Controller configuring a displayable name
  92   # can get specs to display title and options
  93   # and the user prefs to read and set them
  94   my specs => SL::DB::SomeObject->displayable_name_specs;
  95   my prefs => SL::DB::SomeObject->displayable_name_prefs;
  96
  97
  98 This mixin provides a method C<displayable_name> for the calling module
  99 which returns the a string depending on the settings of the
 100 C<UserPreferences> (see also L<SL::Helper::UserPrefernces::DisplayableName>.
 101 The value in the user preferences is scanned for a pattern like E<lt>%name%E<gt>, which
 102 will be replaced by the value of C<$object-E<gt>name>.
 103
 104 =head1 CONFIGURATION
 105
 106 The mixin must be configured on import giving a hash with the following keys
 107 in the C<use> statement. This is stored in the specs an can be used
 108 in a controller setting the preferences to display them.
 109
 110 =over 4
 111
 112 =item C<title>
 113
 114 The (translated) title of the object.
 115
 116 =item C<options>
 117
 118 The C<options> are an array ref of hash refs with the keys C<name> and C<title>.
 119 The C<name> is the method called to get the needed information from the object
 120 for which the displayable name is configured. The C<title> can be used to
 121 display a (translated) text in a controller setting the preferences.
 122
 123 =back
 124
 125 =head1 CLASS FUNCTIONS
 126
 127 =over 4
 128
 129 =item C<displayable_name_specs>
 130
 131 Returns the specification given on importing this helper. This can be used
 132 in a controller setting the preferences to display the information to the
 133 user.
 134
 135 =item C<displayable_name_prefs>
 136
 137 This returns an instance of the L<SL::Helper::UserPrefernces::DisplayableName>
 138 (see there) for the calling class. This can be used to read and set the
 139 preferences.
 140
 141 =back
 142
 143 =head1 INSTANCE FUNCTIONS
 144
 145 =over 4
 146
 147 =item C<displayable_name>
 148
 149 Displays the name of the object depending on the settings in the
 150 user preferences.
 151
 152 =back
 153
 154 =head1 BUGS
 155
 156 Nothing here yet.
 157
 158 =head1 AUTHOR
 159
 160 Bernd Bleßmann E<lt>bernd@kivitendo-premium.deE<gt>
 161
 162 =cut