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