Adding POD to the commerce system, as well as objectifying everything.

2005-01-10 16:06:11 +00:00 · 2005-01-10 16:06:11 +00:00 · 61d74619c5
commit 61d74619c5
parent 702905c9db
4 changed files with 827 additions and 1 deletions
--- a/lib/WebGUI/Commerce/Payment.pm
+++ b/lib/WebGUI/Commerce/Payment.pm
@ -6,7 +6,76 @@ use WebGUI::International;
 use Tie::IxHash;
 use WebGUI::HTMLForm;

+=head1 NAME
+
+Package WebGUI::Commerce::Payment
+
+=head1 DESCRIPTION
+
+An abstract class for all payment plugins to extend.
+
+=head1 SYNOPSIS
+
+ use WebGUI::CommercePayment;
+ our @ISA = qw(WebGUI::Commerce::Payment);
+
+Invoking goes as follows:
+
+ $plugin = WebGUI::Commerce::Payment->new('MyPlugin');
+
+=head1 METHODS
+
+These methods are available from this class:
+
+=cut
+
+
 #-------------------------------------------------------------------
+
+=head2 cancelRecurringPayment ( data )
+
+This method takes care of canceling a recurring transaction. You must override this
+method if your plugin can handle recurring payments.
+
+=head3 data
+
+A hashref containing:
+
+	id		=> the gateway ID of the transaction,
+	transaction	=> the instanciated WebGUI::Commerce::Transaction object
+
+=cut	
+
+sub cancelRecurringPayment {
+	return "";
+}
+
+#-------------------------------------------------------------------
+
+=head2 checkoutForm
+
+This must return a printRowsOnly'ed WebGUI::HTMLForm containing the fields for the checkout
+dat you want to collect. Do not include submit buttons. You probably want to override this 
+method.
+
+=cut
+
+sub checkoutForm {
+	return "";
+}
+
+#-------------------------------------------------------------------
+
+=head2 configurationForm
+
+This generates the configuration form that's displayed in the admin console. You must 
+extend this method to include parameters specific to this payment module. To do so return
+the SUPER::configurationForm method with a printRowsOnly'ed WebGUI::HTMLForm as the argument.
+
+Also be sure to prepend all formfield names with the prepend method. See propend for more info.
+
+=cut
+
 sub configurationForm {
 	my ($self, $form, $f);
 	$self = shift;
@ -23,18 +92,86 @@ sub configurationForm {

 	return $f->printRowsOnly;
 }
-	
+
 #-------------------------------------------------------------------
+
+=head2 confirmRecurringTransaction
+
+This method is called if your gateway signals you (ie. posts data to some URL) to confirm a 
+recurring payment term has been processed. If this is the case, you probably want to store 
+the result in some table so it can be processed by the Schedualer plugin through the 
+getRecurringPaymentStatus method. 
+
+You only need to override this method if your gateway uses a webbased contacting scheme.
+
+=cut
+
+sub confirmRecurringTransaction {
+	return undef;
+}
+
+#-------------------------------------------------------------------
+
+=head2 confirmTransaction
+
+This method is called when your gateway contacts a specific URL to notify you of the result of a
+transaction. You should override this method only if your gateway uses this kind of notification 
+(ie. like PayPal APN). Returns a boolean indicating whether the transaction was successful or not.
+
+=cut
+
+sub confirmTransaction {
+	return 0;
+}
+
+#-------------------------------------------------------------------
+
+=head2 connectionError
+
+Returns an error message if there was a connection error. You must override this method.
+
+=cut
+
+sub connectionError {
+	return "The connetionError method must be overridden.";
+}
+
+#-------------------------------------------------------------------
+
+=head2 enabled
+
+Returns a boolean indicating whether the plugin is enabled or not.
+
+=cut
+
 sub enabled {
 	return $_[0]->{_enabled};
 }

 #-------------------------------------------------------------------
+
+=head2 get ( property )
+
+Returns property of the plugin.
+
+=head3 property
+
+The name of the property you want.
+
+=cut
+
 sub get {
 	return $_[0]->{_properties}{$_[1]};
 }

 #-------------------------------------------------------------------
+
+=head2 getEnabledPlugins
+
+Returns a reference to an array of all enabled instanciated payment plugins.
+
+=cut
+
 sub getEnabledPlugins {
 	my (@enabledPlugins, $plugin, @plugins);
 	@enabledPlugins = WebGUI::SQL->buildArray("select namespace from commerceSettings where type='Payment' and fieldName='enabled' and fieldValue='1'");
@ -48,6 +185,17 @@ sub getEnabledPlugins {
 }
 	
 #-------------------------------------------------------------------
+
+=head2 init ( namespace )
+
+Constructor for the plugin. You should extend this method.
+
+=head3 namespace
+
+The namespace of the plugin.
+
+=cut
+
 sub init {
 	my ($class, $namespace, $properties);
 	$class = shift;
@ -59,6 +207,68 @@ sub init {
 }

 #-------------------------------------------------------------------
+
+=head2 gatewayId
+
+Returns the gatewayId of the transaction. You must override this method.
+
+=cut
+
+sub gatewayId {
+	return WebGUI::ErrorHandler::fatalError("You must override the gatewayId method in your Payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 getRecurringPaymentStatus ( recurringId, term )
+
+This should return a hashref containing the payment status of the specified term. If
+the term has not been processed yet this method should return undef. Override only if 
+your plugin is capable of recurring transactions.
+
+The hashref should contain:
+
+	resultCode	=> the result of the payment
+
+=head3 recurringId
+
+The ID the gateway has assigned to the recurring transaction.
+
+=head3 term
+
+The term number you want the status of.
+
+=cut
+
+sub getRecurringPaymentStatus {
+	return undef;
+}
+
+#-------------------------------------------------------------------
+
+=head2 errorCode
+
+Returns the error code of the last submission.
+
+=cut
+
+sub errorCode {
+	return WebGUI::ErrorHandler::fatalError("You must override thie errorCode method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 load ( namespace )
+
+A convienient method to load a plugin. It handles all error checking and stuff for you.
+This is a SUPER class method only and shoud NOT be overridden.
+
+=head3 namespace
+
+The namespace of the plugin.
+
+=cut
+
 sub load {
 	my ($class, $namespace, $load, $cmd, $plugin);
    	$class = shift;
@ -74,11 +284,121 @@ sub load {
 }

 #-------------------------------------------------------------------
+
+=head2 name
+
+Returns the (display) name of the plugin. You must override this method.
+
+=cut
+
+sub name {
+	return WebGUI::ErrorHandler::fatalError("You must override the name method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 namespace
+
+Returns the namespace of the plugin.
+
+=cut
+
 sub namespace {
 	return $_[0]->{_namespace};
 }

 #-------------------------------------------------------------------
+
+=head2 normalTransaction ( transactionData )
+
+This method submits a normal (non-recurring) transaction to the payment gateway. You probably
+should override this method.
+
+=head3 transactionData
+
+A hashref containing:
+
+	amount		=> the total amount of the transaction
+	description	=> the transaction description
+	invoiceNumber	=> the invoice number of the transaction
+	id		=> the webgui transaction ID
+
+=cut
+
+sub normalTransaction {
+	return undef;
+}
+
+#-------------------------------------------------------------------
+
+=head2 recurringTransaction ( transactionData )
+
+This method submits a recurring transaction to the payment gateway. You must override
+this method if your plugin supports recurring payments.
+
+=head3 transactionData
+
+A hashref containing:
+
+	amount		=> the total amount of the transaction,
+	term		=> the number of terms of the subscription should last.
+			   If none is given your plugin should use an infinite number of terms,
+	payPeriod	=> the billing interval,
+	description	=> the transaction description,
+	invoiceNumber	=> the invoice number of the transaction,
+	id		=> the webgui transaction ID,
+
+=cut
+
+sub recurringTransaction {
+	return undef;
+}
+
+#-------------------------------------------------------------------
+
+=head2 resultCode
+
+Returns the result code of the transaction. You must override this method.
+
+=cut
+
+sub resultCode {
+	return WebGUI::ErrorHandler::fatalError("You must override the resultCode method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 resultMessage
+
+Returns the result message of the transaction. You must override this method.
+
+=cut
+
+sub resultMessage {
+	return WebGUI::ErrorHandler::fatalError("You must override the resultMessage method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 prepend ( fieldName )
+
+A utility method that prepends fieldName with a string that's used to save configuration data to
+the database. Use it on all fields in the configurationForm method.
+
+For instance:
+
+	$f = WebGUI::HTMLForm->new;
+	$f->text(
+		-name	=> $self->prepend('MyField');
+		-label	=> 'MyField'
+	);
+
+=head3 fieldName
+
+The string to prepend.
+
+=cut
+
 sub prepend {
 	my ($self, $name);
 	$self = shift;
@ -88,6 +408,17 @@ sub prepend {
 }

 #-------------------------------------------------------------------
+
+=head2 recurringPeriodValues ( period )
+
+A utility method that returns the internationalized name for period.
+
+=head3 period
+
+The period you want the name for.
+
+=cut
+
 sub recurringPeriodValues {
 	my ($i18n, %periods);
 	$i18n = WebGUI::International->new('Commerce');
@ -105,5 +436,72 @@ sub recurringPeriodValues {
 	return \%periods;
 }

+#-------------------------------------------------------------------
+
+=head2 supports
+
+Returns a hashref containg the types of payment the plugin supports. The hashref may contain:
+
+	single		=> 1 if the plugin supports normal transactions,
+	recurring	=> 1 if the plugin supports recurring transactions
+
+You must override this method.
+
+=cut
+
+sub supports {
+	return WebGUI::ErrorHandler::fatalError("You must override the supports method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 transactionCompleted {
+
+A boolean indicating whether the payment has been finished or not. You must override this method.
+
+=cut
+
+sub transactionCompleted {
+	return WebGUI::ErrorHandler::fatalError("You must override the transactionCompleted method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 transactionError
+
+Returns an error message if a transaction error has occurred. You must override this method.
+
+=cut
+
+sub transactionError {
+	return WebGUI::ErrorHandler::fatalError("You must override the transactionError method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 transactionPending
+
+A boolean indicating whether the payment is pending or not. You must override this method.
+
+=cut
+
+sub transactionPending {
+	return WebGUI::ErrorHandler::fatalError("You must override the transactionPending method in the payment plugin.");
+}
+
+#-------------------------------------------------------------------
+
+=head2 validateFormData
+
+This method checks the data entered in the checkoutForm. If an error has occurred this method must 
+return an arrayref containing the errormessages tied to the errors. If everything's ok it will return
+undef. You must override this method.
+
+=cut
+
+sub validateFormData {
+	return WebGUI::ErrorHandler::fatalError("You must override the validateFormData method in the payment plugin.");
+}
+
 1;