add some documentation
authorTony Cook <tony@develop-help.com>
Fri, 8 May 2020 06:47:43 +0000 (16:47 +1000)
committerTony Cook <tony@develop-help.com>
Fri, 14 Aug 2020 10:56:56 +0000 (20:56 +1000)
MANIFEST
plugins/optionpricing/lib/BSECustom/ProductOptionPricing.pm
site/cgi-bin/modules/BSE/PubSub.pm
site/cgi-bin/modules/BSE/TB/Product.pm
site/docs/bsepubsub.pod [new file with mode: 0644]
site/docs/config.pod

index 0f8fe11..93cf6e1 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -427,6 +427,7 @@ site/docs/BSE::Variables.html
 site/docs/bse_import.pod
 site/docs/bsedbschema.odt
 site/docs/bsedbschema.pdf
+site/docs/bsepubsub.pod
 site/docs/bugs.html
 site/docs/bugs.pod
 site/docs/config.html
index 36da3d2..ebbdf19 100644 (file)
@@ -1,7 +1,7 @@
 package BSECustom::ProductOptionPricing;
 use strict;
 
-our $VERSION = "1.000";
+our $VERSION = "1.001";
 
 sub init {
   my ($class) = @_;
@@ -148,3 +148,29 @@ sub order_item_option {
 }
 
 1;
+
+=head1 NAME
+
+BSECustom::ProductOptionPricing - support storing price offsets for
+different product option values.
+
+=head1 SYNOPSIS
+
+  [customizers]
+  preload-prodopt-prices=BSECustom::ProductOptionPricing,init
+
+=head1 DESCRIPTION
+
+This accepts a price offset for each database-product option added or
+edited and saves it in the C<value_price> custom field for the product
+option value.
+
+The offset is stored in cents and negative offsets are permitted.
+
+The cart items and total price also include the price offsets and that
+is transferred to the order when it is created.
+
+The custom C<value_price> is stored in the options saved with the
+order line items.
+
+=cut
index 194d409..93bd47e 100644 (file)
@@ -2,7 +2,7 @@ package BSE::PubSub;
 use strict;
 use BSE::CfgInfo qw(load_class);
 
-our $VERSION = "1.000";
+our $VERSION = "1.001";
 
 my %subscribers;
 
@@ -24,7 +24,6 @@ sub _load_handlers {
   my @entries = $cfg->entries($name);
   while (@entries) {
     my ($key, $val) = splice @entries, 0, 2;
-    $key =~ s/\d+$//;
     $key =~ s/-.*//;
     push @{$cache->{$key}}, [ split /,/, $val ];
   }
@@ -167,14 +166,14 @@ BSE::Notify - BSE's publish/subcribe system.
 
   BSE::PubSub->handle(custom_type => \&code);
   BSE::PubSub->handle(custom_type => [ $class_object, $method ]);
-  BSE::PubSub->handle("*" => $class_object);
+  BSE::PubSub->handle("*" => $class_or_object);
 
   # in a config file somewhere
   [subscribers]
-  messagename=classname,methodname,reserved
+  messagename-suffix=classname,methodname,reserved
 
   [customizers]
-  custom_type=classname,methodname,reserved
+  custom_type-suffix=classname,methodname,reserved
 
 =head1 DESCRIPTION
 
@@ -217,4 +216,74 @@ Typically handlers for messages will be configured in the
 configuration file, but other parts of the system may request to
 handle specific messages (or customizations), but this will be rare.
 
+=head1 CONFIGURATION
+
+Message and customization handlers are configureed in their respective
+configuration sections C<[subscribers]> and C<[customizers]>.
+
+The key for each entry is a the message name, optionally followed by
+C<-> and extra text to make the key unique, to allow multiple handlers
+for each message/customization.
+
+The value for each entry is comma separated:
+
+=over
+
+=item *
+
+class name - the class to load.
+
+=item *
+
+method - the method to call on that class
+
+=item *
+
+reserved - reserved for future use.
+
+=back
+
+The special message name C<preload> can be used to preload a class
+which may register other handlers through the registration API.
+
+Errors loading handler classes or calling handlers are logged but
+otherwise ignored.
+
 =cut
+
+=head1 REGISTRATION API
+
+Handler classes loaded with C<preload> can register handlers for
+messages.  The handler specified can be:
+
+=over
+
+=item *
+
+a code reference
+
+=item *
+
+an array reference containing a class name and the method to call on
+that class.
+
+=item *
+
+for wildcard customization handlers only, a class name or (non-code
+ref) object only.
+
+=back
+
+=over
+
+
+=item subscribe(message => $handler);
+
+Register a publication message handler.
+
+=item handle(message => $handler)
+
+Register a customization handler.
+
+
+=back
index 12be747..240e073 100644 (file)
@@ -5,7 +5,7 @@ use BSE::TB::Articles;
 use vars qw/@ISA/;
 @ISA = qw/BSE::TB::Article/;
 
-our $VERSION = "1.007";
+our $VERSION = "1.008";
 
 # subscription_usage values
 use constant SUBUSAGE_START_ONLY => 1;
@@ -111,6 +111,7 @@ sub _get_prod_options {
        desc => $opt->name,
        value => $values[$index],
        valueobj => $opt_valueobjs{$values[$index]},
+       valueobjs => \%opt_valueobjs,
        type => $opt->type,
        labels => \%opt_values,
        default => $opt->default_value,
diff --git a/site/docs/bsepubsub.pod b/site/docs/bsepubsub.pod
new file mode 100644 (file)
index 0000000..7f3e011
--- /dev/null
@@ -0,0 +1,273 @@
+=head1 NAME
+
+bsepubsub.pod - new customization
+
+=head1 DESCRIPTION
+
+This new mechanism supplements the BSE::Custom class replacement
+mechanism with a more extensible mechanism, allowing for independent
+classes to be used for different events and even to allow multiple
+handlers for a given event.
+
+Currently this is very limited, but expect any new customization or
+experiments to use this mechanism instead of BSE::Custom.
+
+Also, unlike BSE::Custom, this always uses named parameters, avoiding
+much of the messiness of that interface.
+
+=head1 SUBCRIBED MESSAGES
+
+None yet.
+
+=head1 CUSTOMIZATION MESSAGES
+
+=head2 Product editing
+
+=over
+
+=item C<product_edit_variables>
+
+Called when displaying the product page.
+
+Parameters:
+
+=over
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited
+
+=item *
+
+C<errors> - hash of errors to be displayed.
+
+=back
+
+=item C<product_option_add_validate>
+
+Called to validate when adding a new product option.
+
+Parameters:
+
+=over
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited
+
+=item *
+
+C<errors> - hash of errors to be updated.
+
+=item *
+
+C<fields> - standard fields already validated.
+
+=back
+
+=item C<product_option_add>
+
+Called for post processing after a new product option is added by form.
+
+Parameters:
+
+=over
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited
+
+=item *
+
+C<option> - new option object
+
+=item *
+
+C<values> - hashref mapping C<value*> keys to the values added.
+
+=back
+
+=item C<product_edit_option_edit>
+
+Called when presenting the product option edit and product option delete forms.
+
+Parameters:
+
+=over
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited.
+
+=item *
+
+C<option> - option object being edited.
+
+=back
+
+=item C<product_option_edit_validate>
+
+Called for custom validation of editing a product option.
+
+Parameters:
+
+=over
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited.
+
+=item *
+
+C<option> - option object being edited.
+
+=item *
+
+C<errors> - errors hash to be updated.
+
+=back
+
+=item C<product_option_edit_save>
+
+Called for custom processing on saving a product option.
+
+Parameters:
+
+=over
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<product> - product being edited.
+
+=item *
+
+C<option> - option object being edited.
+
+=item *
+
+C<newvalues> - hash of C<newvalue*> keys to the added value objects,
+this can be used to find names like C<newcustomN> for a given
+C<newvalueN> to update a custom field for the value.
+
+=back
+
+=back
+
+=head2 Cart processing
+
+=over
+
+=item C<cart_price>
+
+Called to customize the price for a given line item in the cart.
+
+Parameters:
+
+=over
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=item *
+
+C<cart> - cart object.
+
+=item *
+
+C<cartitem> - cart line item object.
+
+=item *
+
+C<price> - scalar reference to price value to be updated (in cents).
+
+=item *
+
+C<req> - current L<BSE::Request> object
+
+=back
+
+=back
+
+=head2 Order processing
+
+=over
+
+=item C<order_item_option>
+
+Called for each cart item option when converting the cart to an order.
+
+=over
+
+=item *
+
+C<cartitem> - the cart line item being converted.
+
+=item *
+
+C<cartoption> - the value object being converted.
+
+=item *
+
+C<cart> - the BSE::Cart being converted.
+
+=item *
+
+C<orderitem> - the order item object
+
+=item *
+
+C<orderitemoption> - the order item option object.
+
+=back
+
+=item C<order_build_item>
+
+Called for each line item when converting the cart items to order line
+items.  Called before the order or order items are saved to the
+database.
+
+Parameters:
+
+=over
+
+=item *
+
+C<cartitem> - the cart line item.
+
+=item *
+
+C<cart> - the cart
+
+=item *
+
+C<orderitem> - a hashref to update.
+
+=back
+
+Currently unused.
+
+=back
+
+=cut
+
index be2a868..591a50c 100644 (file)
@@ -3014,6 +3014,11 @@ Default: an empty string.
 
 =back
 
+=head2 [customizers] and [subscribers]
+X<configuration, [customizers]>X<configuration, [subscribers]>
+
+See L<BSE::PubSub>.
+
 =head1 AUTHOR
 
 Tony Cook <tony@develop-help.com>