Introduction
Installation
Standard Configuration
Reading and Saving Backend Information
Thank you for your purchase of Custom Checkout Step. This document will help you with the standard configuration of your new extension, as well as basic and advance usage.
The Installation section covers installing the extension into your Magento system.
The Standard Configuration section will cover the extension's System -> Configuration Fields, and as a byproduct of this you'll learn how to customize the labels and fields on your new step.
The Reading and Saving Backend Information step will cover where the extension saves your custom step's information, as well as instructions for setting up a custom Magento observer if you need to save the step information to additional database tables and/or storage systems.
Custom Checkout Step is distributed as a packaged Magento Connect extension.
Pulsestorm_Customcheckoutstep.tgz
This tgz package may be used to install the extension via Magento's Connect interface, or used to install the package manually. The Magento Connect interface is located at
System -> Magento Connect -> Magento Connect Manager
Expand the contents of your Pulsestorm_Customcheckoutstep.tgz archive
Copy/Upload the contents of the app, js, and skin folder to the corresponding folders of your Magento system.
Ensure the uploaded files and folders have *nix permissions, ownership and groups identical to the rest of your Magento files and folder
Clear the Magento Cache. This may be done under System -> Cache Management
Log out of the Magento Admin Console Application. This clears your admin ACL session cache.
Also, if you're using compilation, you'll need to re-compile your classes. You may do this via the System -> Tools -> Compilation menu, or via shell/compiler.php
Once installed, you may configure Custom Checkout Step at System -> Configuration -> Checkout -> Custom Checkout Step
After installing the extension, you'll have access to the Custom Checkout Step system configuration at System -> Configuration -> Checkout -> Custom Checkout Step
Here's what each configuration field does.
The Enabled configuration field allows you to turn the custom checkout step on or off. By default, its value is off.
The Step Name/Label configuration field is a descriptive name for your new step. In the default Magento theme design, its used as a step/fieldset label
Magento's one page checkout includes a progress meter in the right hand column. The Step Complete Message configuration field is the text Magento uses in this progress meter when a customer completes your step.
Magento's two checkout methods (one page checkout, multi-address checkout) have different checkout workflows. However, between the two there's four common steps
Enter the Billing/Shipping Address
Enter the Shipping Method
Enter the Payment Information
Review your Order
The Show Before Step configuration field lets you pick where in Magento's checkout process your step shows up. Want your step first? Pick the Billing/Shipping Address option. Want you step right before review? Pick review you Order. This value is the step that your step will appear in front of.
There are two ways to create the form for your custom step, both controlled by this option. If you set the Field Source Type configuration field to Simple Text Fields, then Magento will auto-generate a form based on the values in the Text Fields configuration field. If you set the Field Source Type configuration field to Custom Template, then Magento will use the specified template to render an HTML form.
See the options below for more details.
The Text Fields configuration field is only available if the Field Source Type field is set to Simple Text Fields. The Text Fields configuration field allows you to list, one per line, text field labels for your form.
Field One
Field Two
*Required Field
When Magento reaches your checkout step, it will render each of the above field names as an HTML form input.
If you preface a field name with a * character, Magento will force users to enter a value for this field before continuing.
See the Reading and Saving Backend Information section for more information on how Custom Checkout Step saves these values.
The Theme Template configuration field is only available if the Field Source Type configuration field is set to Custom Template. If you need a form that's more complex than simple text fields, this is the field for you. Simply enter a path to a phtml theme template file (relative from your theme's packagename/themename/template folder), and you'll be able to construct your form using any HTML you want.
To help get you started, Custom Checkout step ships with an example phtml file, located at
app/design/frontend/base/default/theme/pulsestorm_checkoutstep/example-form.phtml
See the Reading and Saving Backend Information section for more information on how Custom Checkout Step saves these values.
By default, the information for your custom step will be available with each order. Just click on the Extra Information tab when viewing an order in the backend of Magento.
Custom Checkout Step saves its information to the pulsestorm_checkoutstep_information table. This table contains a step_data column that contains a JSON encoded version of the saved data. Saving in JSON means you can save any number of fields to the database from your form without a schema change.
This table also contains a quote_id column. Magento "quotes" are how Magento keeps track of an order while it's going through the checkout process. This quote_id will allow you to track which extra information is related to which cart. When a customer places an order, the original quote_id is stored with the order (in the sales_flat_order table). This allows you to track which extra information is related to which completed order.
You may want to customize the look and feel of the Extra Information tab. The tab's default template is located at
app/design/adminhtml/default/default/template/pulsestorm_checkoutstep/order-tab.phtml
And the block's name is pulsestorm_checkoutstep_order_extrainformation. Using this information, you can create a custom controller_action_layout_generate_blocks_after observer to change this template, and customize the display of your custom information.
If you're not familiar with the programming techniques mentioned above, the example Pulsestorm_Extrainformationtab module contains sample code to get you started. This module's app/etc/modules file is disabled by default.
While storing the form information as a generic JSON data structure is flexible, you may want to save the form information elsewhere, or take additional programatic action when a user submits your steps. Custom Checkout Step lets you do this via an event observer. Simply configure an observer for the pulsestorm_checkoutstep_step_save event. This event fires right before Magento saves the step information
Mage::dispatchEvent('pulsestorm_checkoutstep_step_save', array(
'result'=>$result,
'data'=>$post_data,
));
$post_data = $this->_filterPostData($post_data);
$model = Mage::getModel('pulsestorm_checkoutstep/information');
$model->load($quote_id, 'quote_id');
$model->setQuoteId($quote_id)
->setStepData(Mage::helper('core')->jsonEncode($post_data))
->save();
In your observer, you can fetch the post data with the following syntax
public function yourObserverMethod($observer)
{
$data = $observer->getPostData();
}
and perform any programatic action you want.
If you're not not familiar with the programming techniques described above, the sample module Pulsestorm_Saveextrainformation contains sample code to help get you started. This module's app/etc/modules file is disabled by default.