Anzahlungs-Rg.: keine weitere Rückbuchung bei erneutem Buchen einer Schluss-Rg
[kivitendo-erp.git] / 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