add support for storing custom metadata to cart/order items and options
[bse.git] / site / cgi-bin / modules / BSE / CustomData.pm
1 package BSE::CustomData;
2 use strict;
3 use JSON ();
4
5 our $VERSION = "1.000";
6
7 my $json;
8
9 sub get_custom_all {
10   my ($self) = @_;
11
12   my $data = $self->custom_data;
13   my $result;
14   if (defined $data && length $data) {
15     eval { $result = JSON::decode_json($data); 1};
16   }
17   return $result || {};
18 }
19
20 sub set_custom_all {
21   my ($self, $hash) = @_;
22
23   ref $hash eq "HASH"
24     or die "set_custom_all() called with non-hash";
25   my $data;
26   eval { $data = JSON::encode_json($hash) };
27   $data ||= "{}";
28   $self->set_custom_data($data);
29 }
30
31 sub set_custom {
32   my ($self, $name, $value) = @_;
33
34   my $data = $self->get_custom_all;
35   $data->{$name} = $value;
36   $self->set_custom_all($data);
37 }
38
39 sub get_custom {
40   my ($self, $name) = @_;
41
42   my $data = $self->get_custom_all;
43   return $data->{$name};
44 }
45
46 1;
47
48 =head1 NAME
49
50 BSE::CustomData - mix in for treating a field of a table as JSON.
51
52 =head1 SYNOPSIS
53
54   package YourTable;
55   use parent 'Squirrel::Row', 'BSE::Custom';
56
57   sub columns { ... custom_data }
58
59   my $item = YourTable->getByPkey(...);
60   $item->set_custom($name => $value);
61   my $value = $item->get_custom($name);
62
63 =head1 DESCRIPTION
64
65 A simpler, cheaper alternative to the table metadata system, intended
66 for uses where that would be far too heavy.
67
68 Expects your class to define the following methods:
69
70 =over
71
72 =item *
73
74 set_custom_data($value) - sets the custom data field in the row object.
75
76 =item *
77
78 custom_data - retrieves the custom data field in the row object.
79
80 =back
81
82 The data should be stored/retrieved as a BLOB, though JSON column
83 types may also work.
84
85 Provides the following methods:
86
87 =over
88
89 =item *
90
91 set_custom($name, $value) - set the given field in the custom data to
92 C<$value>.  C<$name> must be a simple string.  C<$value> must be a
93 JSON compatible structure, including strings, numbers, arrays, hashes,
94 and may not include blessed objects.
95
96 =item *
97
98 set_custom_all($hash) - set the entire custom data to a given hash,
99 used by set_custom().
100
101 =item *
102
103 get_custom($name) - retrieve a value set previously by set_custom.
104
105 =item *
106
107 get_custom_all() - get the custom data hash.  Used by get_custom() and
108 set_custom().
109
110 =back
111
112 =cut