From 3b8a28fd16ac12581718cd63291507e21ff0672b Mon Sep 17 00:00:00 2001 From: JT Smith Date: Wed, 20 Feb 2008 06:33:46 +0000 Subject: [PATCH] fixing pay and shipper docs, and cleaned up special characters in the others --- designdocs/cart.pod | 42 +-- designdocs/commerce.pod | 779 +++------------------------------------- designdocs/pay.pod | 257 +++++++++++++ designdocs/shipper.pod | 242 +++++++++++++ designdocs/sku.pod | 16 +- 5 files changed, 582 insertions(+), 754 deletions(-) create mode 100644 designdocs/pay.pod create mode 100644 designdocs/shipper.pod diff --git a/designdocs/cart.pod b/designdocs/cart.pod index 97f630a98..03dfb488e 100644 --- a/designdocs/cart.pod +++ b/designdocs/cart.pod @@ -8,7 +8,7 @@ written to display the cart data. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>cartEE<128>E<157>. +"cart". Field Schema Description cartId guid The unique id for this cart. @@ -25,10 +25,10 @@ class. Adds an item to the cart. Returns the number of items now in the cart. -param: asset EE<128>E<147> the asset object to be added already +param: asset - the asset object to be added already configured as needed -param: quantity EE<128>E<147> the number of this item that the +param: quantity - the number of this item that the user wants =head3 create @@ -37,7 +37,7 @@ Creates a new cart object if there's not one already attached to the current session object. Otherwise just instanciates the existing one. Returns a reference to the object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session =head3 delete @@ -51,7 +51,7 @@ Removes all items from this cart. Returns a duplicated hash reference of this object's data. -param: any field EE<128>E<147> returns the value of a field +param: any field - returns the value of a field rather than the hash reference =head3 getId @@ -67,10 +67,10 @@ the cart. Calls WebGUI::Shop::CartItem-EgetAllInCart Instanciates a cart based upon a cartId. -param: sessionId EE<128>E<147> a reference to the current +param: sessionId - a reference to the current session -param: cartId EE<128>E<147> the unique id for this cart +param: cartId - the unique id for this cart =head3 set @@ -90,7 +90,7 @@ This object represents an individual item in the cart. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>cartItemsEE<128>E<157>. +"cartItems". Field Schema Description cartId guid The unique id for this cart. @@ -108,29 +108,29 @@ class. Creates a new cart item object. Returns a reference to the object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: cartId EE<128>E<147> the unique id of the cart +param: cartId - the unique id of the cart -param: asset EE<128>E<147> A reference to the asset you wish to +param: asset - A reference to the asset you wish to create. -param: quantity EE<128>E<147> the quantity of sku to purchase +param: quantity - the quantity of sku to purchase =head3 get Returns a duplicated hash reference of this object's data. -param: any field EE<128>E<147> returns the value of a field +param: any field - returns the value of a field rather than the hash reference =head3 getAllInCart Returns an array reference of WebGUI::Shop::Cart::Item objects. -param: session EE<128>E<147> the session object +param: session - the session object -param: cartId EE<128>E<147> the unique id of the cart you'd like +param: cartId - the unique id of the cart you'd like to retrieve the objects of =head3 getSku @@ -141,27 +141,27 @@ Returns an instanciated WebGUI::Asset::Sku object for this cart item. Instanciates a cart item based upon a cartId and assetId. -param: session EE<128>E<147> the session object +param: session - the session object -param: cartId EE<128>E<147> the unique id for this cart +param: cartId - the unique id for this cart -param: assetId EE<128>E<147> the unique id of an skue contained +param: assetId - the unique id of an skue contained in the cart =head3 remove Removes an item from the cart. -param: assetId EE<128>E<147> the unique id of the asset to be +param: assetId - the unique id of the asset to be removed =head3 update Updates an item in the cart. -param: assetId EE<128>E<147> the unique id of the sku to be +param: assetId - the unique id of the sku to be updated -param: hashRef EE<128>E<147> a hash reference of the things that +param: hashRef - a hash reference of the things that might be updated, including quanity, shippingAddressId, and options. diff --git a/designdocs/commerce.pod b/designdocs/commerce.pod index 4029d93b6..dc6b36661 100644 --- a/designdocs/commerce.pod +++ b/designdocs/commerce.pod @@ -170,7 +170,7 @@ don't want to have to deal with coupon magnification effects. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>couponEE<128>E<157>. +"coupon". Field @@ -216,9 +216,9 @@ create Creates a new WebGUI::Shop::Coupon object. Returns a reference to the object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: hashRef EE<128>E<147> a hash reference containing a list +param: hashRef - a hash reference containing a list of the parameters in coupon table, except for couponId. delete @@ -229,7 +229,7 @@ get Returns a duplicated hash reference of this object's data. -param: any field EE<128>E<147> returns the value of a field +param: any field - returns the value of a field rather than the hash reference. getId @@ -240,696 +240,25 @@ new Instantiates a coupon based upon couponId. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: couponId EE<128>E<147> the unique id to instantiate +param: couponId - the unique id to instantiate newByCode Instantiates a coupon based upon coupon code. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: code EE<128>E<147> the coupon code. +param: code - the coupon code. set Update a parameter for the coupon. -param: hashRef EE<128>E<147> a hash reference containing a list +param: hashRef - a hash reference containing a list of the parameters in coupon table, except for couponId. -=head1 Payment Gateway - -Payment gateways are the mechanism by which users can pay for the items -in their shopping cart. - -=head2 Data Dictionary - -The following fields are needed to construct this object's table called -EE<128>E<156>paymentGatewayEE<128>E<157>. - -Field - -Schema - -Description - -paymentGatewayId - -guid - -the primary key - -label - -varchar(100) - -A title for this payment that will be displayed to the user. For -example EE<128>E<156>Pay PalEE<128>E<157> or -EE<128>E<156>Credit CardEE<128>E<157> or -EE<128>E<156>CheckEE<128>E<157> - -className - -varchar(255) - -The plugin classname that will be used for this payment gateway. - -options - -mediumtext - -A json serialized hash reference with configuration data for this -payment gateway. - -=head2 Method Dictionary - -The following methods will be available from the WebGUI::Shop::Pay -class. - -Method - -Description - -_loadDriver - -A method used load a payment gateway driver. - -create - -Creates a new WebGUI::Shop::Pay object. Returns a reference to the -object. - -param: session EE<128>E<147> a reference to the current session - -param: hashRef EE<128>E<147> a hash reference containing a list -of the parameters in coupon table, except for couponId. - -delete - -Deletes this payment gateway. - -get - -Returns a duplicated hash reference of this object's data. - -param: any field EE<128>E<147> returns the value of a field -rather than the hash reference. - -getId - -Returns the payment gateway id. - -getOptions - -Returns a hash reference of paymentGatewayIds as keys, with -EE<128>E<156>labelEE<128>E<157> and -EE<128>E<156>formEE<128>E<157> as subkeys. Label provides -the human readable label for the object, and form provides the HTML -form, that includes the button for the payment gateway option. This is -required since some payment gateways take the user off site and have -very complex forms that need to be created and posted to the remote -site. - -param: cart EE<128>E<147> a reference to the cart object to -generate options for. - -new - -Instantiates a payment gateway based upon paymentGatewayId. - -param: session EE<128>E<147> a reference to the current session - -param: paymentGatewayId EE<128>E<147> the unique id to -instantiate - -set - -Update a parameter for the payment gateway. - -param: hashRef EE<128>E<147> a hash reference containing a list -of the parameters in paymentGateway table, except for paymentGatewayId. - -www_listPaymentGateways - -Returns a list of the payment gateways configured currently. - -www_editPaymentGateway - -The add/edit form for managing a payment gateway. - -www_editPaymentGatwaySave - -Saves the result of www_editPaymentGateway and then displays -www_listPaymentGateways. - -=head1 Payment Gateway Driver - -Payment gateway drivers are used to collect payment. In Perl terms this -is the DBD to DBI. All payment gateway drivers (itransact, paypal, -google checkout, etc) will be derived from this base class. - -=head2 Data Dictionary - -Payment gateway drivers have no database tables, unless they need it on -a one-off basis. - -=head2 Method Dictionary - -The following methods will be available from the -WebGUI::Shop::Pay::Driver class. - -Method - -Description - -definition - -Returns an array reference of hash references of fields that are -defined for this payment gateway driver similar to definition() in -WebGUI::Asset. - -param: definition EE<128>E<147> an array ref of hash refs - -field: - -[ - -name =E EE<128>E<156>Payment TypeEE<128>E<157>, - -fields =E { - -label =E { - -fieldType =E EE<128>E<156>textEE<128>E<157>, - -label =E EE<128>E<156>LabelEE<128>E<157>, - -defaultValue =E EE<128>E<156>Credit CardEE<128>E<157> - -}, - -enabled =E { - -fieldType =E EE<128>E<156>yesNoEE<128>E<157>, - -label =E EE<128>E<156>Enabled?EE<128>E<157>, - -defaultValue =E 1 - -}, - -groupToUse =E { - -fieldType =E EE<128>E<156>groupEE<128>E<157>, - -label =E EE<128>E<156>Who can use?EE<128>E<157>, - -defaultValue =E 1 - -}, - -receiptMessage =E { - -fieldType =E EE<128>E<156>textEE<128>E<157>, - -label =E EE<128>E<156>Receipt Email -MessageEE<128>E<157>, - -defaultValue =E undef - -}, - -} - -], - -getButton - -Returns the HTML postable form that will take the user to check out -using this payment gateway. - -getName - -Return a human readable name for this driver. Never overridden in the -subclass, instead specified in definition. - -new - -Instantiates a driver. - -param: session EE<128>E<147> a reference to the current session - -param: options EE<128>E<147> a hash reference of configurable -parameters for this driver - -=head2 Todo - -=over - -=item 1. - -We need the following payment gateways converted to the new API: - -=over - -=item 1. - -itransact - -=item 2. - -cash - -=item 3. - -check - -=back - -=back - -=head1 iTransact Driver - -This allows for credit card payments via the iTransact payment gateway. - -=head2 Data Dictionary - -Payment gateway drivers have no database tables, unless they need it on -a one-off basis. - -=head2 Method Dictionary - -The following methods will be available from the -WebGUI::Shop::Pay::Driver::Itransact class. - -Method - -Description - -definition - -Returns an array reference of hash references of fields that are -defined for this ship driver similar to definition() in WebGUI::Asset. - -param: definition EE<128>E<147> an array ref of hash refs of -definitions - -[ - -{ - -name =E EE<128>E<156>iTransactEE<128>E<157>, - -fields =E { - -username =E { - -label =E EE<128>E<156>Vendor IDEE<128>E<157>, - -fieldType =E EE<128>E<156>textEE<128>E<157>, - -defaultValue =E undef - -}, - -password =E { - -label =E EE<128>E<156>PasswordEE<128>E<157>, - -fieldType =E EE<128>E<156>passwordEE<128>E<157>, - -defaultValue =E undef - -}, - -useCvv2 =E { - -label =E EE<128>E<156>Use CVV2?EE<128>E<157>, - -fieldType =E EE<128>E<156>yesNoEE<128>E<157>, - -defaultValue =E 1 - -}, - -} - -] - -getEditForm - -Similar to the method of the same name in WebGUI asset, but uses the -definition from this module. - -getButton - -Returns the HTML postable form that will take the user to check out -using this payment gateway. - -new - -Instantiates a driver. - -param: session EE<128>E<147> a reference to the current session - -param: options EE<128>E<147> a hash reference of configurable -parameters for this driver - -www_collectPaymentInfo - -Collects payment info from the user. - -www_displayStatus - -Displays a status message to the user after collecting payment info. -The status may be a success message along with a printable receipt, or -an error message like EE<128>E<156>Credit card -declined.EE<128>E<157> - -=head1 Shipper - -This is the master class to manage shipper drivers. In Perl terms the -DBI to DBD. - -=head2 Data Dictionary - -The following fields are needed to construct this object's table called -EE<128>E<156>shipperEE<128>E<157>. - -Field - -Schema - -Description - -shipperId - -guid - -The unique id for this shipper. - -label - -varchar(100) - -A title for this shipper that will be displayed to the user. For -example EE<128>E<156>Flat RateEE<128>E<157> or -EE<128>E<156>FedEx OvernightEE<128>E<157> - -className - -varchar(255) - -The plugin classname that will be used for this shipping module. - -options - -mediumtext - -A json serialized hash reference with configuration data for this -shipper. - -=head2 Method Dictionary - -The following methods will be available from the WebGUI::Shop::Ship -class. - -Method - -Description - -_loadDriver - -A method used to load a shipping driver. - -create - -Creates a new WebGUI::Shop::Ship object. Returns a reference to the -object. - -param: session EE<128>E<147> a reference to the current session - -param: hashRef EE<128>E<147> a hash reference containing a list -of the parameters in shipper table, except for shipperId. - -delete - -Deletes this object. - -get - -Returns a duplicated hash reference of this object's data. - -param: any field EE<128>E<147> returns the value of a field -rather than the shippingId. Automatically converts the options json -into a hash reference. - -getId - -Returns the shipperId. - -getOptions - -Returns a hash reference of shipperIds as keys, with -EE<128>E<156>labelEE<128>E<157> and -EE<128>E<156>priceEE<128>E<157> as subkeys. Label -provides the human readable label for the object, and price provides -the calculated price for shipping. - -param: cart EE<128>E<147> a reference to the cart object to -calculate for. - -new - -Instantiates a Shipper object based upon shipperId. - -param: session EE<128>E<147> a reference to the current session - -param: shipperId EE<128>E<147> the unique id to instantiate - -set - -Update a parameter for the ship object. - -param: hashRef EE<128>E<147> a hash reference containing a list -of the parameters in coupon table, except for shipperId. Automatically -convert the options parameter into json. - -www_listShippers - -Returns a list of the shippers configured currently. - -www_editShipper - -The add/edit form for managing a shipper. - -www_editShipperSave - -Saves the result of www_editShipper and then displays www_listShippers. - -=head1 Shipper Driver - -Shipping modules are used to calculate shipping costs. Shipping modules -are not allowed to have a user interface. Instead, they plug their data -into the shopping cart screen if any items in the shopping cart have -shipping. In Perl terms this is the DBD to DBI. All shipping drivers -(flat rate, fedex, ups, dhl, usps, etc) will be derived from this base -class. - -=head2 Data Dictionary - -Shipping drivers have no database tables, unless they need it on a -one-off basis. - -=head2 Method Dictionary - -The following methods will be available from the -WebGUI::Shop::ShipDriver class. - -Method - -Description - -calculate - -Returns a shipping price. - -param: cart EE<128>E<147> a reference to the cart object. - -definition - -Returns an array reference of hash references of fields that are -defined for this ship driver similar to definition() in WebGUI::Asset. - -param: definition EE<128>E<147> an array ref of hash refs - -field: - -[ - -name =E EE<128>E<156>Shipper TypeEE<128>E<157>, - -fields =E { - -label =E { - -fieldType =E EE<128>E<156>textEE<128>E<157>, - -label =E EE<128>E<156>LabelEE<128>E<157>, - -defaultValue =E undef - -}, - -enabled =E { - -fieldType =E EE<128>E<156>yesNoEE<128>E<157>, - -label =E EE<128>E<156>Enabled?EE<128>E<157>, - -defaultValue =E 1 - -}, - -} - -], - -getName - -Return a human readable name for this driver. Never overridden in the -subclass, instead specified in definition. - -getEditForm - -Similar to the method of the same name in WebGUI asset, but uses the -definition from this module. - -new - -Instantiates a driver. - -param: session EE<128>E<147> a reference to the current session - -param: options EE<128>E<147> a hash reference of configurable -parameters for this driver - -properties - -Accessor for the internally stored configurable parameters. Returns -a safe copy of the hash. - -=head1 Flat Rate Shipper - -This allows for basic shipping calculations without any tie-ins to -external shippers. - -=head2 Data Dictionary - -Shipping drivers have no database tables, unless they need it on a -one-off basis. - -=head2 Method Dictionary - -The following methods will be available from the -WebGUI::Shop::ShipDriver::Flat class. - -Method - -Description - -calculate - -Returns a shipping price. Calculates the shipping price using the -following formula: - -total cart price * percentageOfPrice - -+ - -flatFee - -+ - -total weight of shippable items * pricePerWeight - -+ - -total quantity of shippable items * pricePerItem - -param: cart EE<128>E<147> a reference to the cart object. - -definition - -Returns an array reference of hash references of fields that are -defined for this ship driver similar to definition() in WebGUI::Asset. - -param: definition EE<128>E<147> an array ref of hash refs of -definitions - -[ - -{ - -name =E EE<128>E<156>Flat RateEE<128>E<157>, - -fields =E { - -percentageOfPrice =E { - -fieldType =E EE<128>E<156>floatEE<128>E<157>, - -label =E EE<128>E<156>Percentage Of -PriceEE<128>E<157>, - -defaultValue =E 0 - -}, - -flatFee =E { - -fieldType =E EE<128>E<156>floatEE<128>E<157>, - -label =E EE<128>E<156>Flat FeeEE<128>E<157>, - -defaultValue =E 0 - -}, - -pricePerWeight =E { - -fieldType =E EE<128>E<156>floatEE<128>E<157>, - -label =E EE<128>E<156>Price Per WeightEE<128>E<157>, - -defaultValue =E 0 - -}, - -pricePerItem =E { - -label =E EE<128>E<156>Price Per ItemEE<128>E<157>, - -fieldType =E EE<128>E<156>floatEE<128>E<157>, - -defaultValue =E 0 - -}, - -} - -] - -new - -Instantiates a driver. - -param: session EE<128>E<147> a reference to the current session - -param: options EE<128>E<147> a hash reference of configurable -parameters for this driver =head1 Taxes @@ -939,7 +268,7 @@ where an order is being shipped to. This class deals with that. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>taxEE<128>E<157>. +"tax". Field @@ -984,16 +313,16 @@ add Adds an item to the tax table. -param: field EE<128>E<147> choose from -EE<128>E<156>countryEE<128>E<157>, -EE<128>E<156>stateEE<128>E<157>, or -EE<128>E<156>codeEE<128>E<157>. +param: field - choose from +"country", +"state", or +"code". -param: value EE<128>E<147> the value to match against field. For +param: value - the value to match against field. For example, for state it might be -EE<128>E<156>WIEE<128>E<157>. +"WI". -param: taxRate EE<128>E<147> the rate to apply to this locale in +param: taxRate - the rate to apply to this locale in percent. calculate @@ -1017,13 +346,13 @@ total weight of shippable items * pricePerWeight total quantity of shippable items * pricePerItem -param: cart EE<128>E<147> a reference to the cart object. +param: cart - a reference to the cart object. delete Deletes an item from the tax table. -param: taxId EE<128>E<147> the id of the item to delete +param: taxId - the id of the item to delete exportTaxData @@ -1041,14 +370,14 @@ importTaxData Deletes all the existing records in the tax table, and replaces them with the values in the file. -param: path EE<128>E<147> the path to the tab delimited file to +param: path - the path to the tab delimited file to import. See the export() method for details. new Instanciates the tax object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session www_add @@ -1101,7 +430,7 @@ be used by other subsystems, but it will first be used by commerce. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>addressEE<128>E<157>. +"address". Field @@ -1120,8 +449,8 @@ label varchar(100) A label for this address like -EE<128>E<156>homeEE<128>E<157>, -EE<128>E<156>workEE<128>E<157>, etc. +"home", +"work", etc. name @@ -1180,9 +509,9 @@ create Creates a new WebGUI::Shop::Address object. Returns a reference to the object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: hashRef EE<128>E<147> a hash reference containing a list +param: hashRef - a hash reference containing a list of the parameters in address table, except for addressId. delete @@ -1193,7 +522,7 @@ get Returns a duplicated hash reference of this object's data. -param: any field EE<128>E<147> returns the value of a field +param: any field - returns the value of a field rather than the hash reference getId @@ -1204,15 +533,15 @@ new Instantiates a address based upon addressId. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: addressId EE<128>E<147> the unique id to instantiate +param: addressId - the unique id to instantiate set Update a parameter for the address. -param: hashRef EE<128>E<147> a hash reference containing a list +param: hashRef - a hash reference containing a list of the parameters in address table, except for addressId. =head1 Transaction History @@ -1224,7 +553,7 @@ time of sale, because things change over time. =head2 Data Dictionary The following fields are needed to construct this object's table called -EE<128>E<156>transactionEE<128>E<157>. +"transaction". Field @@ -1249,7 +578,7 @@ transactionCode varchar(100) The transaction id or code received from the payment gateway. In -iTransact it is called EE<128>E<156>xidEE<128>E<157>. +iTransact it is called "xid". statusCode @@ -1433,7 +762,7 @@ float The final sale price. The following fields are needed to construct this object's table called -EE<128>E<156>transactionItemsEE<128>E<157>. +"transactionItems". Field @@ -1570,11 +899,11 @@ create Creates a new transaction object. Returns a reference to the object. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: hashRef EE<128>E<147> a hash reference containing any/all +param: hashRef - a hash reference containing any/all of the fields from the transaction table minus the -EE<128>E<156>transactionIdEE<128>E<157> field. +"transactionId" field. delete @@ -1584,7 +913,7 @@ get Returns a duplicated hash reference of this object's data. -param: any field EE<128>E<147> returns the value of a field +param: any field - returns the value of a field rather than the hash reference getId @@ -1601,7 +930,7 @@ new Instantiates a WebGUI::Shop::Transaction object using transactionId. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session param: transactionId @@ -1609,26 +938,26 @@ set Updates a transaction object. -param: hashRef EE<128>E<147> a hash reference containing any/all +param: hashRef - a hash reference containing any/all of the fields from the transaction table minus the -EE<128>E<156>transactionIdEE<128>E<157> field. +"transactionId" field. setStatus -Default status is EE<128>E<156>pendingEE<128>E<157> as +Default status is "pending" as items are being added to it. -param: status EE<128>E<147> The status to set: +param: status - The status to set: -pending EE<128>E<147> default +pending - default -pending payment EE<128>E<147> waiting on payment to complete +pending payment - waiting on payment to complete -pending shipment EE<128>E<147> waiting on shipment to be marked +pending shipment - waiting on shipment to be marked -complete EE<128>E<147> order has been paid and shipped +complete - order has been paid and shipped -returned EE<128>E<147> order has been cancelled +returned - order has been cancelled =head2 Todo @@ -1668,7 +997,7 @@ project is to prove variable pricing. =head2 Data Dictionary The following fields are needed to construct this assets table called -EE<128>E<156>DonationEE<128>E<157>. +"Donation". Field @@ -1717,8 +1046,8 @@ Write a subscription asset. =item 1. -Move the EE<128>E<156>redeem a subscription -codeEE<128>E<157> functionality from the user account to the +Move the "redeem a subscription +code" functionality from the user account to the subscription asset. =back @@ -1732,7 +1061,7 @@ Convert all subscriptions into subscription assets. =item 1. Create subscription assets in the import node under a folder called -EE<128>E<156>SubscriptionsEE<128>E<157>. +"Subscriptions". =item 2. @@ -1772,7 +1101,7 @@ Make new templates that look good, and throw out the old ones. =head2 Data Dictionary The following fields are needed to construct this assets table called -EE<128>E<156>SubscriptionEE<128>E<157>. +"Subscription". Field @@ -1815,7 +1144,7 @@ Make the URL of the new products the skew. =item * Place all the new products in the import node under a -EE<128>E<156>ProductsEE<128>E<157> folder. +"Products" folder. =item * @@ -1845,7 +1174,7 @@ Make new templates that look good, and throw out the old ones. =head2 Data Dictionary The following fields are needed to construct this assets table called -EE<128>E<156>ProductEE<128>E<157>. +"Product". Field diff --git a/designdocs/pay.pod b/designdocs/pay.pod new file mode 100644 index 000000000..75c8d5d50 --- /dev/null +++ b/designdocs/pay.pod @@ -0,0 +1,257 @@ +=head1 Payment Gateway + +Payment gateways are the mechanism by which users can pay for the items in their shopping cart. + +=head2 Data Dictionary + +There is no table for this class. + +=head2 Method Dictionary + +The following methods will be available from the WebGUI::Shop::Pay class. + +=head3 _loadDriver + +A method used load a payment gateway driver. See WebGUI::Pluggable. + +=head3 create + +A class method. + +Creates a new WebGUI::Shop::PayDriver object. Returns a reference to the object. + +param: session - a reference to the current session + +param: class - the classname of the driver for the gateway you want to configure + +param: hashRef - a hash reference containing a list of the parameters in coupon table, except for couponId. + +=head3 getOptions + +A class method. + +Returns a hash reference of paymentGatewayIds as keys, with "label" and "form" as subkeys. Label provides the human readable label for the object, and form provides the HTML form, that includes the button for the payment gateway option. This is required since some payment gateways take the user off site and have very complex forms that need to be created and posted to the remote site. + +param: cart - a reference to the cart object to +generate options for. + +=head3 new + +A class method. + +Instantiates a payment gateway based upon paymentGatewayId. + +param: session - a reference to the current session + +param: paymentGatewayId - the unique id to instantiate + +=head3 www_listPaymentGateways + +Returns a list of the payment gateways configured currently. + +=head3 www_editPaymentGateway + +The add/edit form for managing a payment gateway. + +=head3 www_editPaymentGatwaySave + +Saves the result of www_editPaymentGateway and then displays +www_listPaymentGateways. + + + + +=head1 Payment Gateway Driver + +Payment gateway drivers are used to collect payment. In Perl terms this +is the DBD to DBI. All payment gateway drivers (itransact, paypal, +google checkout, etc) will be derived from this base class. + +=head2 Data Dictionary + +The following fields are needed to construct this object's table called "paymentGateway". + + Field Schema Description + paymentGatewayId guid the primary key + label varchar(100) A title for this payment that will be displayed to the user. For example "Pay Pal" or "Credit Card" or "Check" + className varchar(255) The plugin classname that will be used for this payment gateway. + options mediumtext A json serialized hash reference with configuration data for this payment gateway. + +=head2 Method Dictionary + +The following methods will be available from the WebGUI::Shop::PayDriver class. + +=head3 create + +A class method. + +Creates a new WebGUI::Shop::PayDriver object. Returns a reference to the object. + +param: session - a reference to the current session + +param: hashRef - a hash reference containing a list of the parameters in coupon table, except for couponId. + +=head definition + +A class method. + +Returns an array reference of hash references of fields that are +defined for this payment gateway driver similar to definition() in +WebGUI::Asset. + +param: definition - an array ref of hash refs + +field: + + [ + { + name =E "Payment Type", + fields =E { + label =E { + fieldType =E "text", + label =E "Label", + defaultValue =E "Credit Card" + }, + enabled =E { + fieldType =E "yesNo", + label =E "Enabled?", + defaultValue =E 1 + }, + groupToUse =E { + fieldType =E "group", + label =E "Who can use?", + defaultValue =E 1 + }, + receiptMessage =E { + fieldType =E "text", + label =E "Receipt Email Message", + defaultValue =E undef + }, + } + } + ], + +=head3 delete + +Deletes this payment gateway. + +=head3 get + +Returns a duplicated hash reference of this object's data. + +param: any field - returns the value of a field rather than the hash reference. + +=head3 getId + +Returns the payment gateway id. + +=head3 getButton + +Returns the HTML postable form that will take the user to check out +using this payment gateway. + +=head3 getName + +Return a human readable name for this driver. Never overridden in the +subclass, instead specified in definition. + +=head3 new + +A class method. + +Instantiates a driver. + +param: session - a reference to the current session + +param: options - a hash reference of configurable parameters for this driver + +=head2 Todo + +We need the following payment gateways converted to the new API: + +=over + +=item 1. + +itransact + +=item 2. + +cash + +=item 3. + +check + +=back + +=head3 set + +Update a parameter for the payment gateway. + +param: hashRef - a hash reference containing a list +of the parameters in paymentGateway table, except for paymentGatewayId. + + + +=head1 iTransact Driver + +This allows for credit card payments via the iTransact payment gateway. + +=head2 Data Dictionary + +Payment gateway drivers have no database tables, unless they need it on +a one-off basis. + +=head2 Method Dictionary + +The following methods will be available from the +WebGUI::Shop::PayDriver::Itransact class. + +=head2 definition + +Returns an array reference of hash references of fields that are +defined for this ship driver similar to definition() in WebGUI::Asset. + +param: definition - an array ref of hash refs of definitions + + [ + { + name =E "iTransact", + fields =E { + username =E { + label =E "Vendor ID", + fieldType =E "text", + defaultValue =E undef + }, + password =E { + label =E "Password", + fieldType =E "password", + defaultValue =E undef + }, + useCvv2 =E { + label =E "Use CVV2?", + fieldType =E "yesNo", + defaultValue =E 1 + }, + } + } + ] + +=head3 getButton + +Returns the HTML postable form that will take the user to check out +using this payment gateway. + +=head3 www_collectPaymentInfo + +Collects payment info from the user. + +=head3 www_displayStatus + +Displays a status message to the user after collecting payment info. +The status may be a success message along with a printable receipt, or +an error message like "Credit card +declined." + +=cut diff --git a/designdocs/shipper.pod b/designdocs/shipper.pod new file mode 100644 index 000000000..8ac059be0 --- /dev/null +++ b/designdocs/shipper.pod @@ -0,0 +1,242 @@ +=head1 Shipper + +This is the master class to manage shipper drivers. In Perl terms the +DBI to DBD. + +=head2 Data Dictionary + +There is no table for this object. + +=head2 Method Dictionary + +The following methods will be available from the WebGUI::Shop::Ship class. + +=head3 _loadDriver + +A method used to load a shipping driver. See WebGUI::Pluggable. + +=head3 create + +A class method. + +Creates a new WebGUI::Shop::ShipDriver object. Returns a reference to the object. + +param: session - a reference to the current session + +param: class - the classname of a driver to create + +param: hashRef - A hash reference of properties. See WebGUI::Shop::ShipDriver->set for details. + +=head3 getDrivers + +A class method. + +Returns an array reference of the driver classes enabled in the config file. + +=head3 getShippers + +A class method. + +Returns an array reference of the configured shipping objects. + +=head3 getOptions + +A class method. + +Returns a hash reference of shipperIds as keys, with "label" and "price" as subkeys. Label provides the human readable label for the object, and price provides the calculated price for shipping. + +param: cart - a reference to the cart object to calculate for. + +=head3 new + +Instantiates a WebGUI::Shop::ShipDriver object based upon shipperId. + +param: session - a reference to the current session + +param: shipperId - the unique id to instantiate + +=head3 www_listShippers + +Returns a list of the shippers configured currently. + +=head3 www_editShipper + +The add/edit form for managing a shipper. + +=head3 www_editShipperSave + +Saves the result of www_editShipper and then displays www_listShippers. + + +=head1 Shipper Driver + +Shipping modules are used to calculate shipping costs. Shipping modules +are not allowed to have a user interface. Instead, they plug their data +into the shopping cart screen if any items in the shopping cart have +shipping. In Perl terms this is the DBD to DBI. All shipping drivers +(flat rate, fedex, ups, dhl, usps, etc) will be derived from this base +class. + +=head2 Data Dictionary + +The following fields are needed to construct this object's table called "shipper". + + Field Schema Description + shipperId guid The unique id for this shipper. + label varchar(100) A title for this shipper that will be displayed to the user. For example "Flat Rate" or "FedEx Overnight" + className varchar(255) The plugin classname that will be used for this shipping module. + options mediumtext A json serialized hash reference with configuration data for this shipper. + +=head2 Method Dictionary + +The following methods will be available from the WebGUI::Shop::ShipDriver class. + +=head3 calculate + +Returns a shipping price. + +param: cart - a reference to the cart object. + +=head3 create + +A class method. + +Creates a new WebGUI::Shop::ShipDriver object. Returns a reference to the object. + +param: session - a reference to the current session + +param: hashRef - A hash reference of properties. See WebGUI::Shop::ShipDriver->set for details. + +=head3 definition + +A class method. + +Returns an array reference of hash references of fields that are +defined for this ship driver similar to definition() in WebGUI::Asset. + +param: definition - an array ref of hash refs + +field: + + [ + name =E "Shipper Type", + fields =E { + label =E { + fieldType =E "text", + label =E "Label", + defaultValue =E undef + }, + enabled =E { + fieldType =E "yesNo", + label =E "Enabled?", + defaultValue =E 1 + }, + } + ], + +=head3 delete + +Deletes this object. + +=head3 get + +Returns a duplicated hash reference of this object's data. + +param: any field - returns the value of a field +rather than the shippingId. Automatically converts the options json +into a hash reference. + +=head3 getId + +Returns the shipperId. + +=head3 getName + +Return a human readable name for this driver. Never overridden in the +subclass, instead specified in definition. + +=head3 getEditForm + +Similar to the method of the same name in WebGUI asset, but uses the +definition from this module. + +=head3 new + +A class method. + +Instantiates a driver. + +param: session - a reference to the current session + +param: options - a hash reference of configurable +parameters for this driver + +=head3 set + +Update a parameter for the ship object. + +param: hashRef - a hash reference containing a list of the parameters in coupon table, except for shipperId. Automatically convert the options parameter into json. + + +=head1 Flat Rate Shipper + +This allows for basic shipping calculations without any tie-ins to external shippers. + +=head2 Data Dictionary + +Shipping drivers have no database tables, unless they need it on a one-off basis. + +=head2 Method Dictionary + +The following methods will be available from the WebGUI::Shop::ShipDriver::Flat class. + +=head3 calculate + +Returns a shipping price. Calculates the shipping price using the following formula: + + total cart price * percentageOfPrice + + flatFee + + total weight of shippable items * pricePerWeight + + total quantity of shippable items * pricePerItem + +param: cart - a reference to the cart object. + +=head4 definition + +A class method. + +Returns an array reference of hash references of fields that are +defined for this ship driver similar to definition() in WebGUI::Asset. + +param: definition - an array ref of hash refs of definitions + + [ + { + name =E "Flat Rate", + fields =E { + percentageOfPrice =E { + fieldType =E "float", + label =E "Percentage Of Price", + defaultValue =E 0 + }, + flatFee =E { + fieldType =E "float", + label =E "Flat Fee", + defaultValue =E 0 + }, + pricePerWeight =E { + fieldType =E "float", + label =E "Price Per Weight", + defaultValue =E 0 + }, + pricePerItem =E { + label =E "Price Per Item", + fieldType =E "float", + defaultValue =E 0 + }, + } + } + ] + + +=cut diff --git a/designdocs/sku.pod b/designdocs/sku.pod index 3a1f518a8..0e43267dd 100644 --- a/designdocs/sku.pod +++ b/designdocs/sku.pod @@ -6,7 +6,7 @@ needs to be simple so it can be extended to fit any need. =head2 Data Dictionary The following fields are needed to construct this assets table called -EE<128>E<156>SKUEE<128>E<157>. +"SKU". Field Schema Description assetId guid The unique id assigned to this sku that may never change. It's with all assets @@ -26,11 +26,11 @@ Adds this sku to the shopping cart. =head3 applyOptions Accepts a configuration data hash reference that can configure a sku a -certain way. For example, EE<128>E<156>a size XL red -t-shirtEE<128>E<157> instead of just EE<128>E<156>a -t-shirtEE<128>E<157>. +certain way. For example, "a size XL red +t-shirt" instead of just "a +t-shirt". -param: options EE<128>E<147> a hash reference containing the +param: options - a hash reference containing the configuration properties returned from getConfiguration() =head3 getOptions @@ -60,15 +60,15 @@ By default return 0. Should be overridden by subclasses. Instanciates based on an existing sku, rather than an assetId. -param: session EE<128>E<147> a reference to the current session +param: session - a reference to the current session -param: sku EE<128>E<147> the sku to instanciate +param: sku - the sku to instanciate =head3 processStyle Looks up the style from the container and and wrappers the product in it. -param: html EE<128>E<147> the HTML output to be wrapped by the +param: html - the HTML output to be wrapped by the style