diff --git a/lib/WebGUI/Operation/Commerce.pm b/lib/WebGUI/Operation/Commerce.pm index e50369f15..657b09bf4 100644 --- a/lib/WebGUI/Operation/Commerce.pm +++ b/lib/WebGUI/Operation/Commerce.pm @@ -19,6 +19,29 @@ use Storable; #------------------------------------------------------------------- + +=head2 _submenu ( $session ) + +Returns a rendered Admin Console view, with a standard list of five submenu items. + +=head3 $session + +The current WebGUI session object. + +=head3 workarea + +A scalar of HTML that defines the current workarea. + +=head3 title + +The i18n key of the title of this workarea. + +=head3 help + +The i18n key of the help link for this workarea. + +=cut + sub _submenu { my $session = shift; my $i18n = WebGUI::International->new($session, "Commerce"); @@ -37,6 +60,13 @@ sub _submenu { } #------------------------------------------------------------------- + +=head2 _clearCheckoutScratch ( $session ) + +A wrapper around _clearShippingScratch and _clearPaymentScratch. + +=cut + sub _clearCheckoutScratch { my $session = shift; _clearShippingScratch($session); @@ -44,12 +74,26 @@ sub _clearCheckoutScratch { } #------------------------------------------------------------------- + +=head2 _clearPaymentScratch ( $session ) + +Clears the C scratch variable. + +=cut + sub _clearPaymentScratch { my $session = shift; $session->scratch->set('paymentGateway', '-delete-'); } #------------------------------------------------------------------- + +=head2 _clearShippingScratch ( $session ) + +Clear the C and C scratch variables. + +=cut + sub _clearShippingScratch { my $session = shift; $session->scratch->set('shippingMethod', '-delete-'); @@ -57,6 +101,15 @@ sub _clearShippingScratch { } #------------------------------------------------------------------- + +=head2 _paymentSelected ( $session ) + +A utility method to tell if the C scratch variable is +set, that it points to a valid payment plugin that can be loaded and +is enabled. + +=cut + sub _paymentSelected { my $session = shift; return 0 unless ($session->scratch->get('paymentGateway')); @@ -66,6 +119,16 @@ sub _paymentSelected { } #------------------------------------------------------------------- + +=head2 _shippingSelected ( $session ) + + +A utility method to tell if the C scratch variable is +set, that it points to a valid shipping plugin that can be loaded and +is enabled and whose C method returns true. + +=cut + sub _shippingSelected { my $session = shift; return 0 unless ($session->scratch->get('shippingMethod')); @@ -80,6 +143,31 @@ sub _shippingSelected { } #------------------------------------------------------------------- + +=head2 www_addToCart ( $session ) + +Adds the requested item to the user's shopping cart and creates a cart if necessary. + +Uses these form variables: + +=over 4 + +=item C + +The id of the item to add. + +=item C + +The type (namespace) of the item that's to be added to the cart. + +=item C + +The number of items to add. Defaults to 1 if quantity is not given. + +=back + +=cut + sub www_addToCart { my $session = shift; WebGUI::Commerce::ShoppingCart->new($session)->add($session->form->process("itemId"), $session->form->process("itemType"), $session->form->process("quantity")); @@ -88,6 +176,15 @@ sub www_addToCart { } #------------------------------------------------------------------- + +=head2 www_cancelTransaction ( $session ) + +Cancel the transaction described by the form varialbe C if the +transaction status is C. Display an internationalized +message to the user using the C template from the site settings. + +=cut + sub www_cancelTransaction { my $session = shift; my ($transaction, %var); @@ -105,6 +202,15 @@ sub www_cancelTransaction { # This operation is here for easier future extensions to the commerce system. #------------------------------------------------------------------- + +=head2 www_checkout ( $session ) + +A wrapper around the selectShippingMethod, selectPaymentGateway and +checkoutConform methods. selectShippingMethod and selectPaymentGateway +are only executed if their respective scratch variables are not set. + +=cut + sub www_checkout { my $session = shift; return WebGUI::Operation::execute($session,'selectShippingMethod') unless (_shippingSelected($session)); @@ -115,6 +221,20 @@ sub www_checkout { } #------------------------------------------------------------------- + +=head2 www_checkoutConfirm ( $session ) + +Show the user the contents of their shopping cart and a button to pay for the contents. Form +controls are provided to delete items from the cart, change quantities on items, and to +change payment and shipping plugins. All information is placed in variables and styled +using the C template. + +If no plugins have been chosen yet, then they are redirected back to www_checkout. + +If the user continues, the next sub called is www_checkoutSubmit. + +=cut + sub www_checkoutConfirm { my $session = shift; my ($plugin, $f, %var, $errors, $i18n, $shoppingCart, $normal, $recurring, $shipping, $total); @@ -195,6 +315,20 @@ sub www_checkoutConfirm { } #------------------------------------------------------------------- + +=head2 www_checkoutSubmit ( $session ) + +This is the real, final checkout routine. Requires that the user be logged in and have +valid Shipping and Payment plugins set. + +Processes all transactions using the appropriate method for each one, and then return +any templated errors via C. + +If everything is okay, clears all scratch variables and returns the user to the +C operation. + +=cut + sub www_checkoutSubmit { my $session = shift; my ($plugin, $shoppingCart, $transaction, $var, $amount, @cartItems, $i18n, @transactions, @@ -209,7 +343,7 @@ sub www_checkoutSubmit { return WebGUI::Operation::execute($session,'displayLogin'); } - # Check if a valid payment gateway has bee selected. If not have the user do so. + # Check if a valid payment gateway has been selected. If not have the user do so. return WebGUI::Operation::execute($session,'checkout') unless (_paymentSelected($session) && _shippingSelected($session)); # Load shipping plugin. @@ -325,6 +459,16 @@ sub www_checkoutSubmit { } #------------------------------------------------------------------- + +=head2 www_completePendingTransaction ( $session ) + +You must be in group Admin (3) to execute the subroutine. Completes +the transaction specified in the form variable C by calling +WebGUI::Commerce::Transaction->completeTransaction. Returns the user +to the C operation. + +=cut + sub www_completePendingTransaction { my $session = shift; return $session->privilege->adminOnly() unless ($session->user->isInGroup(3)); @@ -335,6 +479,14 @@ sub www_completePendingTransaction { } #------------------------------------------------------------------- + +=head2 www_confirmRecurringTransaction ( $session ) + +Using the Payment plugin from the C form variable and attempts to complete a +recurring transaction, but only if the plugin is valid. + +=cut + sub www_confirmRecurringTransaction { my $session = shift; my($plugin, %var); @@ -346,6 +498,14 @@ sub www_confirmRecurringTransaction { } #------------------------------------------------------------------- + +=head2 www_confirmTransaction ( $session ) + +Using the Payment plugin from the C form variable and attempts to complete the +transaction, but only if the plugin's C returns true. + +=cut + sub www_confirmTransaction { my $session = shift; my($plugin, %var); @@ -357,6 +517,14 @@ sub www_confirmTransaction { } #------------------------------------------------------------------- + +=head2 www_deleteCartItem ( $session ) + +Delete an item, C, from the user's cart. Returns the user to +the C operation. + +=cut + sub www_deleteCartItem { my $session = shift; WebGUI::Commerce::ShoppingCart->new($session)->delete($session->form->process("itemId"), $session->form->process("itemType")); @@ -365,6 +533,18 @@ sub www_deleteCartItem { } #------------------------------------------------------------------- + +=head2 www_editCommerceSettings ( $session ) + +Only users in group Admin (3) can execute the subroutine. + +Site wide setting for commerce, including payment plugins, shipping plugins +and templates. + +Calls C on form submission. + +=cut + sub www_editCommerceSettings { my $session = shift; my (%tabs, $tabform, $currentPlugin, $ac, $jscript, $i18n, @@ -407,7 +587,6 @@ sub www_editCommerceSettings { -label => $i18n->get('checkout canceled template'), -hoverHelp => $i18n->get('checkout canceled template description'), -value => $session->setting->get("commerceCheckoutCanceledTemplateId"), - -hoverHelp => $i18n->get('checkout canceled template description'), -namespace => 'Commerce/CheckoutCanceled' ); $tabform->getTab('general')->template( @@ -415,7 +594,6 @@ sub www_editCommerceSettings { -label => $i18n->get('checkout select payment template'), -hoverHelp => $i18n->get('checkout select payment template description'), -value => $session->setting->get("commerceSelectPaymentGatewayTemplateId"), - -hoverHelp => $i18n->get('checkout select payment template description'), -namespace => 'Commerce/SelectPaymentGateway' ); $tabform->getTab('general')->template( @@ -423,7 +601,6 @@ sub www_editCommerceSettings { -label => $i18n->get('checkout select shipping template'), -hoverHelp => $i18n->get('checkout select shipping template description'), -value => $session->setting->get("commerceSelectShippingMethodTemplateId"), - -hoverHelp => $i18n->get('checkout select shipping template description'), -namespace => 'Commerce/SelectShippingMethod' ); $tabform->getTab('general')->template( @@ -431,7 +608,6 @@ sub www_editCommerceSettings { -label => $i18n->get('view shopping cart template'), -hoverHelp => $i18n->get('view shopping cart template description'), -value => $session->setting->get("commerceViewShoppingCartTemplateId"), - -hoverHelp => $i18n->get('view shopping cart template description'), -namespace => 'Commerce/ViewShoppingCart' ); @@ -440,7 +616,6 @@ sub www_editCommerceSettings { -label => $i18n->get('daily report email'), -hoverHelp => $i18n->get('daily report email description'), -value => $session->setting->get("commerceSendDailyReportTo") - -hoverHelp => $i18n->get('daily report email description'), ); # Check which payment plugins will compile, and load them. @@ -523,12 +698,25 @@ sub www_editCommerceSettings { } #------------------------------------------------------------------- + +=head2 www_editCommerceSettingsSave ( $session ) + +Only users in group Admin (3) can execute the subroutine. + +Form post processor for C. Plugin +configuration data is stored in a special table for security and all +other settings in the WebGUI settings table for easy access. + +Returns the user to C. + +=cut + sub www_editCommerceSettingsSave { my $session = shift; return $session->privilege->adminOnly() unless ($session->user->isInGroup(3)); foreach ($session->form->param) { - # Store the plugin confiuration data in a special table for security and the general settings in the + # Store the plugin configuration data in a special table for security and the general settings in the # normal settings table for easy access. if (/~([^~]*)~([^~]*)~([^~]*)/) { WebGUI::Commerce::setCommerceSetting({ @@ -546,6 +734,16 @@ sub www_editCommerceSettingsSave { } #------------------------------------------------------------------- + +=head2 www_listPendingTransactions ( $session ) + +Only users in group Admin (3) can execute the subroutine. + +Show a paginated list of all transactions with status, Pending. Provide +links so the Admin can complete any pending transaction. + +=cut + sub www_listPendingTransactions { my $session = shift; my ($p, $transactions, $output, $properties, $i18n); @@ -579,6 +777,17 @@ sub www_listPendingTransactions { } #------------------------------------------------------------------- + +=head2 www_listTransactions ( $session ) + +Show all transactions in the system and allow them to be managed. + +You must be in group Admin (3) in order to access this screen. + +The screen is not templated. + +=cut + sub www_listTransactions { my $session = shift; my ($output, %criteria, $transaction, @transactions); @@ -681,6 +890,14 @@ sub www_listTransactions { } #------------------------------------------------------------------- + +=head2 www_selectPaymentGateway ( $session ) + +Allow the user to select a payment plugin. Uses the C +template. After form submission, calls www_selectPaymentGatewaySave + +=cut + sub www_selectPaymentGateway { my $session = shift; my ($plugins, $f, $i18n, @pluginLoop, %var); @@ -714,6 +931,17 @@ sub www_selectPaymentGateway { } #------------------------------------------------------------------- + +=head2 www_selectPaymentGatewaySave ( $session ) + +Form processor for www_selectPaymentGateway. If the user selected payment plugin can +be loaded and enabled, sets the scratch variable C so that it can +be used. Otherwise the value of the scratch variable is cleared. + +Returns the user to the operation C when it is done. + +=cut + sub www_selectPaymentGatewaySave { my $session = shift; if (WebGUI::Commerce::Payment->load($session, $session->form->process("paymentGateway"))->enabled) { @@ -726,6 +954,14 @@ sub www_selectPaymentGatewaySave { } #------------------------------------------------------------------- + +=head2 www_selectShippingMethod ( $session ) + +Allow the user to select a payment plugin. Uses the C +template. After form submission, calls www_selectPaymentGatewaySave + +=cut + sub www_selectShippingMethod { my $session = shift; my ($plugins, $f, $i18n, @pluginLoop, %var); @@ -760,6 +996,20 @@ sub www_selectShippingMethod { } #------------------------------------------------------------------- + +=head2 www_selectShippingMethodSave ( $session ) + +Form processor for www_selectShippingMethod. If the shipping method +plugin can be loaded and the C method returns false, then +takes the user back to the C operation (probably +www_selectShippingMethod). + +If the plugin is enabled, then set scratch variables to be used downstream. + +Returns the user to the operation C when it is done. + +=cut + sub www_selectShippingMethodSave { my $session = shift; my $shipping = WebGUI::Commerce::Shipping->load($session, $session->form->process("shippingMethod")); @@ -778,12 +1028,28 @@ sub www_selectShippingMethodSave { } #------------------------------------------------------------------- + +=head2 www_transactionComplete ( $session ) + +This is wrapper for the C operation, probably +WebGUI::Operation::TransactionLog::www_viewPurchaseHistory. + +=cut + sub www_transactionComplete { my $session = shift; return WebGUI::Operation::execute($session,'viewPurchaseHistory'); } #------------------------------------------------------------------- + +=head2 www_updateCart ( $session ) + +Update the shopping cart with new quantities for items. Returns the user +to the C operation, probably www_viewCart. + +=cut + sub www_updateCart { my $session = shift; my $shoppingCart = WebGUI::Commerce::ShoppingCart->new($session); @@ -798,6 +1064,17 @@ my $shoppingCart = WebGUI::Commerce::ShoppingCart->new($session); } #------------------------------------------------------------------- + +=head2 www_viewCart ( $session ) + +Display the user's shopping cart to the user using the C +template, and allow them to delete items or change the quantity of regular items. + +Will call the C operation, the C operation or C +based on user input. + +=cut + sub www_viewCart { my $session = shift; my ($shoppingCart, $normal, $recurring, %var, $total, $i18n);