CMS Made Simple 1.6: Orders and Payments in an E-commerce Website

Exclusive offer: get 50% off this eBook here
CMS Made Simple 1.6: Beginner's Guide

CMS Made Simple 1.6: Beginner's Guide — Save 50%

Create a fully functional and professional website using CMS Made Simple

$26.99    $13.50
by Sofia Hauschildt | March 2010 | Beginner's Guides Content Management Open Source Web Development

In the article CMS Made Simple 1.6: Getting Started with an E-commerce Website, we covered Products module. In this article by Sofia Hauschildt, author of CMS Made Simple 1.6: Beginner's Guide, we will learn about a solution made of following modules:

  • Cart
  • SelfRegistration (optional)
  • Orders
  • PaypalGateway (optional)

Module Cart

This  module will add simple cart functionality to the Products module. Once installed, the Cart module will be automatically displayed in the detailed view of the product. The visitor of the website will then be able to put one or more products in the basket along with the desired quantity. There are other modules that you can use instead of the Cart module, like GiftBaskets. For our example Shop, it is enough to use the simple functionality of the Cart module.

Install the module Cart from the list of available modules in the Module Manager. The admin area of this module will be added to Extensions | Cart in the admin console of CMS Made Simple.

Time for action – connecting products and cart

If you now look at your Shop page and open a detailed view of any product, you will discover that there is still no cart functionality in it. The reason for it is that the Products module does not know that the Cart module has been installed and is ready for use. Let's connect two modules.

  1. Open the admin area of the Products module (Content | Product Manager).
  2. Click on the Preferences tab.
  3. Select the Cart module from the field Cart Module.
  4. Click on Submit and open detailed view of any product. You should see the but on Add to My Cart in the detailed view of the product. If the product has some attributes additionally to the quantity field, then the attributes are displayed in a drop-down field besides it.
  5. CMS Made Simple 1.6: Beginner's Guide

What just happened?

You have told the Products module what module has to be used for cart functionality. Test it and add some products to the cart right now. The products will be added, but there is no possibility to display the content of the cart for the visitor yet.

Create a new content page called Cart and add the following Smarty tag as the content of the page:

{Cart action="viewcart"}

Save the page, then open the admin area for the Cart module (Extensions | Cart) and switch to the Preferences tab. Select the newly created page in the list of pages, so that the visitor is automatically redirected to the page after he has added the product to it.

There are four templates that you can customize for the module:

Template

 

Description

 

AddToCart

This template controls how the quantity field, the button Add To My Cart (see the preceding screenshot) and optionally product attributes with price adjustment look like.

MyCart

This template is used to display the cart status. It is displayed at the place where the Smarty tag {Cart action="mycart"} is placed. It shows the number of items currently saved in the cart and the link to the cart page.

Viewcart

This template is used for extended display of all products saved in the cart. It shows all products with their quantities and prices and the total order price. Additionally it offers the possibility to start the checkout order process if the module Orders is installed.

Product Summary

This template is used to format the output used for each product summary in the Viewcart template. It allows customizing the product label based on the attributes, product name, and price.

The Smarty tag {Cart action="mycart"} can be added to the navigation of the website, like the link to the Basket in the official shop (http://www.cafepress.co.uk/cmsmadesimple) we are trying to reproduce. It would appear as shown in the following screenshot:

CMS Made Simple 1.6: Beginner's Guide

There is nothing else you should know about the Cart module. The next step will be to integrate the checkout process.

Module Orders

This module is designed for processing orders from the cart. This module handles billing and shipping addresses from the customer and either uses an external payment gateway (such as PayPal) to handle the payment process or performs manual e-mail-based invoicing. This module can also optionally collect credit card information and store it in the database for later offline processing.

Even if the module offers the possibility, never collect credit card information in a low security shared hosting environment!

The Orders module keeps track of all orders, and allows for the specification of items like tracking numbers and confirmation on numbers and sending e-mails to the customers related to a particular order.

The functionality of the module can be extended with even more modules that allow configuring different taxes, shipping costs, and promotion actions (like discount or promotion coupons).

This module has a lot of dependencies:

  • CGExtensions
  • FrontEndUsers
  • Products
  • CGSimpleSmarty
  • CMSMailer
  • CGPaymentGatewayBase

From this list of dependencies, you can learn that it is based on the functionality of the module FrontEndUsers. This means that your website's customers must register before they can start the payment process on your online store. There is no possibility to turn off this registration process and it is required for the checkout step.

Install all modules listed in the preceding dependencies list, then install the Orders module.

Time for action – adding the checkout step

To enable the checkout process provided by the Orders module follow these steps:

  1. Create a new content page (Content | Pages | Add New Content) and name it Checkout.
  2. Add the following Smarty tag to the Content field of the Checkout page: {Orders}
  3. Save and view the page in the browser. This page will display either the billing form if the user is logged in or the warning message if the user is not logged in or does not belong to special user group.
  4. To connect the Cart module with the new Checkout page, in the admin console click on Extensions | Cart.
  5. Select the tab Viewcart Form Templates and click on the Sample template (or your own template, if you have created one).
  6. At the very end of the template in the Template Text field, add the following line of code:
      {cms_selflink page="checkout"}
  7. The parameter page should contain the page alias of the page where the Smarty tag {Orders} has been added to the content.

  8. Open your shop and add one or more products to the cart,find a link to the page Checkout at the very bottom of the screen.

What just happened?

You have connected the module Cart with the module Orders by placing a link from the cart view to the checkout process. To test the link, add some products to the cart and click the Checkout link at the bot  om of the cart view. If you are not logged in, you will see the following message:

The user is not logged in (or not a member of the required group)

This message can be found in the template of the Orders module. But first, let's see an overview of the templates delivered with this module. In the admin console, click on Content | Order Manager and find the Templates link above the list of orders:

Template name

Template description

Billing Form

This template controls the first step in the order processing. It displays the form where the customer can enter billing address and one or more shipping addresses.

Payment Form

This template controls the second step in the order processing and is used to display the payment form for manual e-mail based checkout process. You will need this template if you do not use any payment services like PayPal, EMoney, EWay, or Authorize.net.

Confirm Order

This template controls the third step in the order processing and is used to display any information the customer entered in the first and optionally second step, so that the customer can confirm the shipping and invoice addresses or go back and correct them.

Invoice

This template is used in the admin area of the module Orders to print out the invoice or to send it via e-mail to the customer.

Gateway Complete

This template is used to display the status message after the payment has been made with any 3rd party service like PayPal, EMoney, EWay, or Authorize.net.

User Email

This template is used to customize the e-mail with order confirmation sent to the customer when the new order has been submitted.

Admin Email

This template controls the layout and content of the e-mail that is sent to the authorized administrator of the store when a new order is submitted.

Message

There is no sample template for the messages. Here you can define your custom e-mail notifications that can be manually sent to the customers from the admin area of the module. An example for such message can be an e-mail notification that is sent when the order is shipped.

Now, we know where to start and how to proceed with customizing of the templates according to our requirements and payment configurations. Let's give the customer the possibility to register with or login to the website to be able to complete the checkout process.

Integrating the login screen

The message that indicates that the customer is not logged in is saved in the template Billing Form (the first step in the checkout process).

The user is not logged in (or not a member of the required group).

This is not very user friendly. Whether the user is registered or not we should give him a possibility to log in or to register on this page as shown in the following screenshot:

CMS Made Simple 1.6: Beginner's Guide

The login form for registered customers can be displayed with the module FrontEndUsers.

In the admin area of the Orders module, click on the Templates link and create a new template with the name My Shop on the tab. Scroll down to the very bottom of the suggested template text and the last ELSE condition:

...
{else}
{* user is not logged in, gotta make him *}
<h3 style="color: red;">{$Orders
>Lang('error_notloggedin')}</h3><br/>
{/if}

This is the place where the message that the user is not logged in is shown. Replace this section with the login screen of the module FrontEndUsers, as shown in the following code snippet:

...
{else}

<h1>Already registered?</h1>
{FrontEndUsers}
{/if}

Save the template and do not forget to set it as Default to see changes on the website. Registered customers can now log into start the checkout process.

But, what about customers who do not have an account? They should be able to register themselves with our website. As it gets a bit complicated I have created the following flowchart:

CMS Made Simple 1.6: Beginner's Guide

The billing form checks if the visitor is logged in or not. If yes, he can fill in the billing information; if not, the login form of the FrontEndUsers module (step 3) is displayed. The steps 4 and 5 in the workflow should assist new customers by allowing them to register. These steps can be accomplished with the SelfRegistration module. Read the next section to see how the module can be configured.

Before you continue be sure that:

  • The CMSMailer module is configured and is able to send out messages
  • There is a user property of type Email Address in the module FrontEndUsers (Users & Groups | Frontend User Management, tab User Properties).
  • There is a user group that has the above user properties associated as Required (Users & Groups | Frontend User Management, tab Groups).

Integrating customer registration

This module is designed to allow visitors of the website to register themselves. It optionally sends a confirmation e-mail with an activation link that must be clicked before the registration is complete. Once the registration is complete, a user account is created in the module FrontEndUsers.

Install the SelfRegistration module from the list of available modules in the Module Manager. For the registration page, create a new content page Register and add the following Smarty tag into the content of the page:

{SelfRegistration group="Customers"} 

Pay attention to the part in bold in the above code. The value of the parameter group should exactly reflect the name of user group in the module FrontEndUsers (Users & Groups | Frontend User Management, tab Groups).

Open the Register page of your website and sign in yourself as a new customer with the SelfRegistration module to see how the module works by default. There are some preferences in the module that can make the registration process user friendly. In the admin area of the Self Registration module (Users & Groups | Self Registration Module), click on the Preferences tab.

The SelfRegistration module offers registration with an e-mail verification step or optionally single-step registration without any confirmation. If you do not need the e-mail verificafion, you should deselect the option Require the user to confirm registraion via email on the Preferences tab of the module. The three settings considering the final message work different depending on what registration method you have chosen.

Setting

With verification

Without verification

Don't display the final message after registration

Prevents the registration form to be replaced by the confirmation message after the form is submitted.

Prevents the registration form to be replaced by the final message after the form is submitted.

PageID/Alias to redirect to after registration is complete

N/A

Redirects to the given page, but replaces the whole content of the page with the final message.

PageID/Alias to redirect to after verification step is complete

Redirects to the given page, but replaces the whole content of the page with the final message.

N/A

According to the workflow, let's add a link to the registration page for the new customers (step 4). In the billing template of the Orders module, open the template for the Billing Form again, scroll down and add a link to the registration page for the new customers as shown in the following code snippet:

...
{else}

<h1>Already registered?</h1>
{FrontEndUsers}

<h1>New Customer?</h1>
{cms_selflink page="register"}
{/if}

Pay attention to the parameter page. It should contain the alias of the page where the registration form is displayed. Customize the Registration Template 1 of the SelfRegistration module that displays the registration form. Generally, there are two templates. The first one is for the registration form and the second one (Post Registration Template) contains the message informing the customer that his registration should be confirmed through a link sent to his e-mail address. Other templates that you can customize are as shown in the following table:

Templates

 

Description

 

Registration Template 2

This template contains the form where the username, verification code and password will be added to complete registration.

Confirmation Email

Contains subject of the verification e-mail, the plain text and the HTML version of the e-mail sent out after the customer has registered.

Final Message

The message is shown to customer after the registration process is completed. To build the workflow suggested above (step 5) add link to the billing form in this template, so that the user can carry on with the checkout process. It is also advisable to tick the option Login user after registration, so that the login step can be skipped after registration.

Lost Email

This template contains a form for the customers that have registered but did not get verification e-mail. This template is shown at the place where the Smarty tag {SelfRegistration mode="sendmoremail"} is shown.

CMS Made Simple 1.6: Beginner's Guide Create a fully functional and professional website using CMS Made Simple
Published: March 2010
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

When the user registers with the website and e-mail verification is required, the temporary user account is saved in the SelfRegistration module (not FrontEndUsers!). After e-mail verification is complete, new user account is automatically moved to the FrontEndUsers module. At the same time the temporary account is deleted from the SelfRegistration module.

There is a limit of 250 temporary accounts in the SelfRegistration module. When the number of 250 non-verified accounts is reached, no registration is possible. Therefore you purge from the SelfRegistration module by using the option on the Preferences tab.

After the module SelfRegistration is configured and all required templates are customized, you can go through the whole manual e-mail-based checkout process.

I suggest that you use the workflow to test all three cases:

  • The visitor is registered and logged in
  • The visitor is registered, but not logged in
  • The visitor is not registered

I recommend that you customize the final message in the SelfRegistration module and add two links to assist the user in his further steps. Link to the Checkout page to continue the checkout process and to the Shop page to continue shopping.

Module Paypal Gateway

This module is used by the Orders module to checkout orders using PayPal Website Payments Standard mechanism. In other words, this module allows the order to be paid through the PayPal website. This payment option can be used either additionally to the manual e-mail-based invoicing delivered with the Orders module or as a substitute for manual processing.

Using this module the customer will be redirected to the PayPal website where the order and all payment details are displayed. He has to log in to his PayPal account to confirm the payment. After the payment is made, the PayPal will automatically redirect to your website.

There are several ways PayPal returns payment data to you after the payment is completed. The Paypal Gateway module supports two methods:

  • Payment Data Transfer (PDT)
  • Instant Payment Notification (IPN)

PDT is a way to confirm the payment with the redirection URL from the PayPal website after the payment is complete. However, the payment can be confirmed in the Orders module this way only if the customer is patient and does not close the browser or navigate away before redirection is completed. If the redirect breaks for some reasons, you won't know about the payment and will have to complete the order manually in the admin console of CMS Made Simple.

IPN is independent of the customer's action. It communicates with your website in the backend. If the customer closes the browser or navigates away, you will still receive notifications from PayPal about the payment. IPN also has a built-in retry mechanism. If there's a problem reaching your website, PayPal will retry to inform you about payments for several days. IPN works parallel to the order process and can be slightly desynchronized. It is possible that the customer may return to your page before IPN informs you that the order is paid.

These two methods can be used together to combine their advantages.

Install the module Paypal Gateway from the list of the available modules in Module Manager. The admin area of the module is placed in Extensions | Paypal Gateway. Click on the Preferences tab. There are some fields that are required for module usage, which are shown in the following screenshot:

CMS Made Simple 1.6: Beginner's Guide

While testing e-commerce solutions you are naturally not going to use your real PayPal account. The suggested Paypal URL points to the official testing environment of the PayPal service. This environment simulates the payment process without making real money transfers.

This environment can be found on http://sandbox.paypal.com. It acts the same way as the real PayPal website does.

Time for action – creating test accounts

Before you use this environment, you have to register a developer account on http://developer.paypal.com and create two test accounts.

  1. Open http://developer.paypal.com in your browser and click on Sign Up Now.
  2. Fill in the fields and click Agree and Submit.
  3. Log in to your developer account with your e-mail and password.
  4. Click on Create a preconfigured buyer or seller account.
  5. Select Buyer(Use to represent your customer's experience) and fill in the field with any test data. Click Create Account.
  6. Create another account, but this time choose Seller (Use to represent yourself as the merchant) as the Account type.
  7. After both accounts are created, click on Test accounts on the left hand side. You should see an overview of the test accounts as shown in the following screenshot:

CMS Made Simple 1.6: Beginner's Guide

What just happened?

You have created two test accounts, one for the buyer and one for the seller. The easiest way to create such accounts is to choose the preconfigured ones. Now, you can log in with the buyer account on http://sandbox.paypal.com and act as if you were your own client. You can purchase anything without having to pay real money.

You can also log onto http://sandbox.paypal.com with the seller account to configure it. You have to activate the PDT and IPN features for the account, get your PDT identity token, and make some more settings on your PayPal account, so that instant payment works with the module PayPal Gateway.

Configuring PayPal's seller account

Click on the Profile link in the seller account. There are four sections that you have to customize to set up PayPal payment with the website.

CMS Made Simple 1.6: Beginner's Guide

Payment Receiving Preferences

First of all, decide if you would like to manually accept payments made in other currencies. This applies only if the default currency of your PayPal account is different to the currency set in the Products module on the Preferences tab. For example, if your PayPal currency is Euro but on your webpage you offer the products in USD. Generally, PayPal does not convert any currency automatically. This means that all payments made in other currencies are on hold until you accept them in your PayPal account manually. Once the payment is accepted the order status is set to Paid. If you would like to convert currencies automatically and accept payments in any currency, you have to deselect the setting Block payments sent to me in a currency I do not hold.

Secondly, you can block all payments with the status Pending. This will reject all payments that are not completed instantly after the payment confirmation. Consider that the Paypal Gateway module is able to handle pending payments if IPN is activated.

Instant Payment Notification

We remember that instant payment notification is able to communicate with the website in the backend. It notifies the Orders module about payment, even if the payment was pending first and accepted later. All that PayPal needs to know is the notification URL. This URL waits for the instant payment notificationon, handles the answer from the PayPal website and updates the order status automatically.

This notification URL is concealed in the module Paypal Gateway. To get it, perform the following steps:

  1. Add a product to your cart.
  2. Click on Checkout and fill the billing form.
  3. Click on Submit.
  4. At the bottom of the confirmation page you see the button Checkout w/Paypal.
  5. Open the source view of this page in your browser and look for the hidden input field with the name notification_url that looks like the following code snippet:
      <input name="notify_url" value="http://yourdomain.com/index.php?
      mact=PaypalGateway,cntnt01,ipn,0&amp;cntnt01order_id=15&amp;cntnt0
      1mycustom=05db2efd49ce4195d97efe01d4df00f4&amp;cntnt01returnid=59"
      type="hidden">
  6. You have to copy the value of the field and paste this URL to the PayPal merchant account.
  7. Click on Instant Payment Notification in the Profile of the seller account in PayPal and edit the IPN Settings. Enter the notification URL you have copied from the hidden field above and click on Receive IPN messages (Enabled). Save the settings.

Website Payment Preferences

Click the Website Payment Preferences link, turn on the Auto-Return option, and enter any URL of your website in the field Return URL. It does not matter what you enter here as this URL will be overridden by the Paypal Gateway module. Then turn on Payment Data Transfer and save.

Pay attention to the yellow information message at the top of the PayPal website after you have changed the above setting:

You have successfully saved your preferences. Please use the following identity token when setting up Payment Data Transfer on your website.XXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX

This is your generated PDT identity token that you need to save in the Paypal Gateway module on the Preferences tab.

Language encoding

On this page you should adjust the language encoding. CMS Made Simple uses UTF-8 encoding by default. Click on the More Options button and select UTF-8 in the Encoding field. Leave the same encoding for IPN and save.

Now you have all the information required to configure the Paypal Gateway module. In the admin area of the Paypal Gateway module, click on the Preferences tab and enter your custom values gained from PayPal sandbox environment. The Business Email field in the Paypal Gateway module contains the generated e-mail address of the seller account. The following screenshot shows my custom values:

CMS Made Simple 1.6: Beginner's Guide

Next, connect the Orders module with the Paypal Gateway module. In the admin area of the Orders module, click on the Preferences tab and scroll down to the Payment Gateway Settings section. Choose the Paypal Gateway module in the list of payment modules and click Submit.

Test your order process now. Pay attention to the Email field in the billing form, it must be filled in for the PayPal payment. After the payment is made, you have to control the payment status in the seller PayPal account. It should be completed. In the admin console of CMS Made Simple, click on Site Admin | Admin Log and see the communication protocol with the PayPal website. For each order completed with PDT and IPN you should have five messages, as shown in the next screenshot:

CMS Made Simple 1.6: Beginner's Guide

The reason for the order being pending is the activated IPN feature. The module sets the order to pending status until the IPN message is received from the module. So, the result of these five messages above is a completed and paid order in the admin console of CMS Made Simple.

Once you have tested the module, you should configure your real PayPal account as explained previously, gather all required information like PDT identity token from the real account, and change the PayPal URL to https://www.paypal.com/cgi-bin/webscr.

Optional modules for the e-commerce suite

There are some more modules that you can use together with this e-commerce suite to enrich the functionality:

  • Flat Rate Taxes: Allows you to apply flat rate taxes to any or all products in the module Products.
  • warehouse taxes: Calculates taxes for a product based on the US state the warehouse is in, and the US state the customer is situated.
  • FlatRateShipping: Provides an interface to set up some simple weight shipping rules, and to calculate the cost of shipping based on its total weight.
  • Destination Based Shipping: Allows the calculation of flat shipping costs based on destination country, and number of items. It does not consider weight in calculations.
  • PriceBasedShipping: Allows the calculation of shipping costs based on the pre-tax total order price.
  • Promotions: Allows you to create and manage promotions/sales in the order process. A sale will consist of a start date, end date, a discount or offer, and a set of conditions. Conditions can include total order amount, coupon code, subset of products based on category or hierarchy or user group. Offers can be a percentage of the total order price or a product item, a fix amount reduced from total order price, or a free product given with the order. Discounts will be applied in the order process and shown up as a line item in the invoice.

     

  • GiftBaskets: This module is another Cart module for the e-commerce suite. You can use it instead of the standard Cart module. This module allows the creation of many different gift baskets, with different shipping addresses, and allows you to add different items in each.
  • EMoney Payment Gateway: This is a payment processing gateway module which works with the ETS Corporation payment authorization system (https://www.etsms.com/ASP/home.htm).
  • Authorize.Net AIM: A payment gateway that interacts directly with Authorize.net using their AIM protocol.
  • Attachments: This module requires some programming knowledge to create functionality like related products, so that you can attach some products to others and display them as related products on the detailed view of the product.

Summary

In this article, you learned how to set up basic e-commerce functionality with CMS Made Simple. Even if CMS Made Simple does not pretend to offer fully sophisticated e-commerce features, it offers the most wanted features with delivered modules.

Be sure that you do not use CMS Made Simple for pure e-commerce websites. It is better to use a dedicated e-commerce solution for an online shop rather than CMS Made Simple. However, if your website has a mix of features such as a blog, a shop, a forum, and so on, then you can use third-party modules to implement these features.

Specifically, we covered:

  • The Cart module that adds simple cart functionality to the Products module. It saves its data in the browser session and connects the module Product with the module Orders.
  • The Orders module that starts the checkout process for the items added to the cart. This module saves all orders in the admin area and allows tracking and updating order status for the administrator of the website.
  • The SelfRegistration module that allows your website's visitors to register with your website before making payment. We have also created a small workflow to see how the module is integrated in the checkout process.
  • The PayPal Gateway module that accepts instant payments from the PayPal website and keeps you informed about the status of the payment.

If you have read this article you may be interested to view :

CMS Made Simple 1.6: Beginner's Guide Create a fully functional and professional website using CMS Made Simple
Published: March 2010
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

About the Author :


Sofia Hauschildt

Sofia Hauschildt is a tutor for web mastering and web development, who started designing and developing professional websites in 1995, just before her graduation in computer science. With experience as a Data Warehouse developer and ERP consultant she became a self-employed tutor. During her career she has been contracted by IT and management academies, the German army, several city administrations, and international companies like Siemens. Her work as a tutor is always focused on practical training combined with a theoretical background in order to get fast and handy results.  In her publications she shares not only solid knowledge but her personal experience and shows a simple and powerful way of creating websites for ambitious beginners. Building websites is an amazing chance to communicate with the whole world and to discover it as well.

Books From Packt


Joomla! 1.5 Multimedia
Joomla! 1.5 Multimedia

MediaWiki 1.1 Beginner's Guide
MediaWiki 1.1 Beginner's Guide

iReport 3.7
iReport 3.7

Mahara 1.2 E-Portfolios: Beginner's Guide
Mahara 1.2 E-Portfolios: Beginner's Guide

Grok 1.0 Web Development
Grok 1.0 Web Development

jQuery 1.4 Reference Guide
jQuery 1.4 Reference Guide

SketchUp 7.1 for Architectural Visualization: Beginner's Guide
SketchUp 7.1 for Architectural Visualization: Beginner's Guide

Drupal 6 Performance Tips
Drupal 6 Performance Tips


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software