Auftrags-Controller: Workflow -> Rechnung (Speichern und Rechnung erfassen)
[kivitendo-erp.git] / SL / DB / Helper / TranslatedAttributes.pm
1 package SL::DB::Helper::TranslatedAttributes;
2
3 use strict;
4
5 use SL::DB::GenericTranslation;
6
7 use parent qw(Exporter);
8 our @EXPORT = qw(translated_attribute save_attribute_translation);
9
10 use Carp;
11
12 sub translated_attribute {
13   my ($self, $attribute, $language_id, $verbatim) = @_;
14
15   $language_id        = _check($self, $attribute, $language_id, $verbatim);
16   my $translation_obj = _find_translation($self, $attribute, $language_id, 0);
17   my $translation     = $translation_obj ? $translation_obj->translation : '';
18
19   return $translation if $verbatim || $translation;
20
21   $translation_obj = _find_translation($self, $attribute, undef, 0);
22   $translation     = $translation_obj ? $translation_obj->translation : '';
23
24   return $translation || $self->$attribute;
25 }
26
27 sub save_attribute_translation {
28   my ($self, $attribute, $language_id, $value) = @_;
29
30   $language_id = _check($self, $attribute, $language_id);
31
32   return _find_translation($self, $attribute, $language_id, 1)->update_attributes(translation => $value);
33 }
34
35 sub _check {
36   my ($self, $attribute, $language_id, $verbatim) = @_;
37
38   croak "Invalid attribute '${attribute}'" unless $self->can($attribute);
39   croak "Object has not been saved yet"    unless $self->id || $verbatim;
40
41   return (ref($language_id) eq 'SL::DB::Language' ? $language_id->id : $language_id) || undef;
42 }
43
44 sub _find_translation {
45   my ($self, $attribute, $language_id, $new_if_not_found) = @_;
46
47   my %params = (language_id      => $language_id,
48                 translation_type => ref($self). '/' . $attribute,
49                 translation_id   => $self->id);
50
51   return SL::DB::Manager::GenericTranslation->find_by(%params) || ($new_if_not_found ? SL::DB::GenericTranslation->new(%params) : undef);
52 }
53
54 1;
55
56 __END__
57
58 =encoding utf8
59
60 =head1 NAME
61
62 SL::DB::Helper::TranslatedAttributes - Mixin for retrieving and saving
63 translations for certain model attributes in the table
64 I<generic_translations>
65
66 =head1 SYNOPSIS
67
68 Declaration:
69
70   package SL::DB::SomeObject;
71   use SL::DB::Helper::Translated;
72
73 Usage:
74
75   my $object   = SL::DB::SomeObject->new(id => $::form->{id})->load;
76   my $language = SL::DB::Manager::Language->find_by(description => 'Deutsch');
77   print "Untranslated name: " . $object->name . " translated: " . $object->translated_attribute('name', $language) . "\n";
78
79   print "Now saving new value\n";
80   my $save_ok = $object->save_attribute_translation('name', $language, 'Lieferung frei Haus');
81
82 =head1 FUNCTIONS
83
84 =over 4
85
86 =item C<translated_attribute $attribute, $language_id, $verbatim>
87
88 Returns the translation stored for the attribute C<$attribute> and the
89 language C<$language_id> (either an ID or an instance of
90 L<SL::DB::Language>).
91
92 If C<$verbatim> is falsish and either no translation exists for
93 C<$language_id> or if C<$language_id> is undefined then the default
94 translation is looked up.
95
96 If C<$verbatim> is falsish and neither translation exists then the
97 value of C<< $self->$attribute >> is returned.
98
99 Requires that C<$self> has a primary ID column named C<id> and that
100 the object has been saved.
101
102 =item C<save_attribute_translation $attribute, $language_id, $value>
103
104 Saves the translation C<$value> for the attribute C<$attribute> and
105 the language C<$language_id> (either an ID or an instance of
106 L<SL::DB::Language>).
107
108 If C<$language_id> is undefined then the default translation will be
109 saved.
110
111 Requires that C<$self> has a primary ID column named C<id> and that
112 the object has been saved.
113
114 Returns the same value as C<save>.
115
116 =back
117
118 =head1 EXPORTS
119
120 This mixin exports the functions L</translated_attribute> and
121 L</save_attribute_translation>.
122
123 =head1 BUGS
124
125 Nothing here yet.
126
127 =head1 AUTHOR
128
129 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
130
131 =cut