Creating a custom controller

Creating a custom controller

Some customers may wish to perform additional functionality beyond Web Store by use of a custom controller. Most controllers in Web Store are in the xlsws_includes folder, with customer-created controllers in the custom_includes folders. Web Store will look in both locations for these files.

For this example, we will assume that you wish to create a custom controller that will had a product to a cart. This may be useful for an email campaign, for example, where a customer can click a button from an email and be taken to Web Store with the cart pre-populated with an item.

Controllers in Web Store

Each controller is a flle in xlsws_includes. In most cases, the URL contains the name of the controller to be used. For example, the URL

 http://www.example.com?xlspg=checkout

will look for the checkout controller. The filename must match this word, so the actual filename is checkout.php. Furthermore, the actual classname must be xlsws_ followed by the controller name, such as:

 class xlsws_checkout extends xlsws_index 

Existing controllers can be extended, but in this case will be creating our own controller to perform a very specific function. Because we're not replacing any existing functionality, we will be creating a new controller from scratch.

Example: Creating a controller for a single function

Our example controller will add an item to cart that has been passed along a URL, then redirect the customer to the cart viewing page. We will pretend that we have sent email to customers with a "Click here to order a Widget" button. In our email, we will construct a URL to our store that looks like this:

 http://www.example.com?xlspg=specialadd&product=ABC123&qty=1

This sample URL uses a controller we will develop called specialadd, followed by other parameters we will need such as the Product Code and the Quantity.

We will create a blank file in our /custom_includes folder for our controller. All custom controllers should reside in this folder so upgrades of Web Store don't conflict with our custom files.

 <?php


  class xlsws_specialadd extends xlsws_index {


    protected function Form_PreRender() {

	//We get any variables we expect on the command line
	//  http://www.example.com?xlspg=specialadd&product=ABC123&qty=1
	$strProduct = QApplication::QueryString('product');
	$intQty = QApplication::QueryString('qty');

	//Load the current cart (or create it if it doesn't exist)
	$objCart = Cart::GetCart();

	//Get the product we were passed on the command line
	$objProduct = Product::LoadByCode($strProduct);

	//If it's a valid product code, add it to the cart
	if($objProduct)
		$objCart->AddToCart($objProduct , $intQty);

	//Redirect to the cart page
	_rd("index.php?xlspg=cart");
    }
  }

  xlsws_specialadd::Run('xlsws_specialadd', templateNamed('index.tpl.php'));

This is our entire controller. As stated, Web Store controllers should be prefixed with xlsws_ and our controller name, so we have written xlsws_specialadd to match our xlspg= variable on the command line. We also need to name this file specialadd.php so it matches as well, and placed it in /custom_includes. (The missing ?> ending for the PHP file is intentional, per modern PHP recommendations.)

We are using the Form_PreRender() function because this is the first function called by Web Store when a controller is loaded. Because we are adding an item to cart and then redirecting, we don't need anything to display on the screen, we can simply go to the cart page and let Web Store show its default page.

Parse the URL

We can use qCodo's functions to get items passed on the command line. For example, the command

 $strProduct = QApplication::QueryString('product'); 

will get the product variable from the URL http://www.example.com?xlspg=specialadd&product=ABC123&qty=1.

Next, we use Web Store functions to load the cart. If a cart has not already been created (meaning the person has not visited Web Store and this is a new customer), the cart will be automatically created.

 $objCart = Cart::GetCart();

Next, using the passed command line variables, we load the Product from the database.

 $objProduct = Product::LoadByCode($strProduct);

If the object is valid, meaning the Product was located in the database, we add it to the cart with the quantity.

 if($objProduct)
      $objCart->AddToCart($objProduct , $intQty);

Finally, after performing this action, we simply redirect to the cart controller which displays the cart to the user.

 _rd("index.php?xlspg=cart");

The actual command to make the controller run is the very last line.

      xlsws_specialadd::Run('xlsws_specialadd', templateNamed('index.tpl.php'));

This runs our controller against the default template (even though we aren't using the template for display, it's simply required here). Without this line, the controller would be loaded but nothing would actually happen.

What this example doesn't do

This is a very stripped down example. It does not check for available inventory, for example, so even if the item is out of stock, it would be added to cart anyway. However, this can provide a starting point if you wish to do something custom. Additional functionality could easily be added. In the case of our email campaign, if the URL contained a tracking code to track response rate or clickthrough rate, you could easily add this to the controller to update a custom statistics table created for this purpose.

For additional information

You can reference the class files under /includes/data_classes to see model functionality. For full qCodo functionality, you can visit http://www.qcodo.com for API guides.