I’ve come to the conclusion that Magento is very annoying to develop for if you know nothing about the platform. Yes the platform is open source but they also have a commercial version, therefore it seems they have tried to make it hard for you to know the complete ins and outs of the system. I.E. if something seems like too much of a task to develop, a company would likely purchase the commercial version and get it developed by the platform developers rather than do it themselves.

You also have to remember that Magento is built on top of the Zend framework, so when you are developing for it documentation does not all reside on the Magento site, you will have to look into how the Zend framework works as well.

Finally, note that by default the Magento checkout process uses AJAX to submit the form, making this a very annoying module to debug. Thankfully Magento makes it easy to log values and throw exceptions which ‘pause’ the checkout process.

After much searching online, it seems that any available tutorials for custom payment methods either don’t work, are incomplete or worked in previous versions but are now updated. I developed this using version 1.3.2.2 of Magento.

I’m writing this tutorial with the intention of it being the definitive guide to creating a custom payment method.

* You’ll notice that I’m using PHP comments in XML code snippets. This is because WordPress isn’t letting me post normal XML comments You’ll have to change/remove them if you plan to copy and paste.

Prerequisites

1. Creating the module

2. Configuration through the admin

4. Payment adapter model class

Prerequisites

There are a few things you need to note now to avoid confusion later down the line.

For your module, you need the main name and a simpler alias for it. I.E. if your module was called MyPaymentMethod, your alias could be mypayment. Keep the full name and the alias in mind. The full name will be used in class and folder names but the alias will be used when referencing the module anywhere else.

For this tutorial I will be using ModuleName for the full name, modulename for the module alias, and MyModules as the module namespace.

Magento names it’s classes after their path. I.E. you are going to have a class which handles all of this payment method logic, and it’s path will be something like app/code/local/MyModules/ModuleName/Model/PaymentLogic.php. It’s class name will be MyModules_ModuleName_Model_PaymentLogic. Remember this as it helps when trying to figure out where to find a referenced class etc.

1. Creating the module

OK so first we need to create the initial module and make sure Magento knows that it exists. Lets create the folder structure;

app/
---- code/
-------- local/
------------ #1 MyModules
---------------- #2 ModuleName
-------------------- #3 Block
-------------------- #4 etc
-------------------- #5 Model


#1 In Magento terms, MyModules would be the module’s namespace. I.E. you’ll likely have one namespace for multiple modules. The namespace can be called anything but should be UpperCamelCase. If you take a look in app/code/core you will see a folder called Mage – this is the namespace for most of Magento’s core modules.

#2 This is your actual module name. This should be UpperCamelCase.

#3 This folder is used to contain block classes that are used in your module.

#4 This is where your module configuration will go.

#5 The class that handles all of your payment gateway logic will go here. This is also a good place to put any third party libraries or custom classes you may use.

config.xml

Create the file config.xml in app/code/local/MyModules/ModuleName/config. This file is the main module configuration file. For now, you want it to look like this;

<?xml version="1.0" encoding="UTF-8"?>
<config>

    /**
     * register the full module name and it's
     * version
     */
    <modules>
        <MyModules_ModuleName>
            <version>0.1.0</version>
        </MyModules_ModuleName>
    </modules>

    /**
     * global module configuration
     */
    <global>

        /**
         * register the module's model group
         * note that we use the module's alias
         * mentioned in the prerequisites
         */
        <models>
            <modulename>
                <class>MyModules_ModuleName_Model</class>
            </modulename>
        </models>

        /**
         * set which resources the module will
         * use when setting up, writing to the db
         * and reading from the db. we're going
         * to use the core connections.
         */
        <resources>
            <modulename_setup>
                <setup>
                    <module>MyModules_ModuleName</module>
                </setup>
                <connection>
                    <use>core_setup</use>
                </connection>
            </modulename_setup>
            <modulename_write>
                <connection>
                    <use>core_write</use>
                </connection>
            </modulename_write>
            <modulename_read>
                <connection>
                    <use>core_read</use>
                </connection>
            </modulename_read>
        </resources>
    </global>
</config>

Now the module has it’s basic configuration but Magento doesn’t care because the module is not yet registered.

MyModules_All.xml

Create the file MyModules_All.xml in app/etc/modules. This is where we register the module. You want this file to look like this;

<?xml version="1.0"?>
<config>
    <modules>
        <MyModules_ModuleName>
            <active>true</active>

            /**
             * for now we're telling the system that
             * this module is just local, it's not a core
             * or community module and resides in
             * app/code/local.
             */
            <codePool>local</codePool>
        </MyModules_ModuleName>
    </modules>
</config>

The module is now registered and Magento knows about it. But what can you do with it? Well, this is a payment method module, so we need to register it as a usable payment method. We also need to be able to set what fields are configured in the administration section that can be used when authenticating with the payment gateway etc.

2. Configuration through the admin

system.xml

Create the file system.xml in app/code/local/MyModules/ModuleName/etc. Here we will tell Magento to have a new section in the payment methods configuration area for configuring this module. We also set what fields we want there. For every field, we have an element like this;

<field_name translate="label">
    <label>Field name</label>
    <frontend_type>field type</frontend_type>
    <source_model>field source model class</source_model>
    <sort_order>1</sort_order>
    <show_in_default>1</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>0</show_in_store>
</field_name>

As you will see below. To start with, have the file looking like this;

<?xml version="1.0"?>
<config>
    <sections>

        /**
         * here we're telling the system we
         * we want to add a new config section
         * in the payment method area
         */
        <payment>
            <groups>
                <modulename translate="label" module="paygate">

                    /**
                     * human readable module name
                     * which appears as the name of the
                     * payment method in the admin section
                     */
                    <label>My Payment Module</label>

                    /**
                     * set where this method should appear
                     * in comparison to the other methods
                     * within the admin
                     */
                    <sort_order>670</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>0</show_in_store>
                    <fields>

                        /**
                         * you need this field if you want the user to
                         * be able to disable/enable this payment
                         * method. leave this out if you don't want
                         * this to be optional
                         */
                        <active translate="label">
                            <label>Enabled</label>
                            <frontend_type>select</frontend_type>

                            /**
                             * we want to use the standard Magento
                             * yes/no select options
                             */
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>1</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </active>

                        /**
                         * the below two fields are an example
                         * of fields you may need if integrating with
                         * a payment gateway's API. you will see how
                         * to retrieve these values in your code later
                         */
                        <api_key translate="label">
                            <label>API Key</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>2</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </api_key>
                        <api_secret translate="label">
                            <label>API Secret</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>3</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </api_secret>

                        /**
                         * having this field here allows the user
                         * to set whether we want payments to be
                         * authorised or authorised AND captured
                         * if you don't want the user to choose you
                         * can leave this field out
                         */
                        <payment_action translate="label">
                            <label>Payment Action</label>
                            <frontend_type>select</frontend_type>

                            /**
                             * we're using the source from the paygate
                             * module as it has the options we want. this
                             * is safe because the paygate module is a core
                             * Magento module and therefore will be there
                             * with any default install. if it makes you feel
                             * safer you can create your own field source model
                             * but that isn't covered in this tutorial
                             */
                            <source_model>paygate/authorizenet_source_paymentAction</source_model>
                            <sort_order>4</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </payment_action>

                        /**
                         * what do you want the status to be of
                         * new orders made using this payment
                         * method?
                         */
                        <order_status translate="label">
                            <label>New order status</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_order_status_processing</source_model>
                            <sort_order>5</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </order_status>

                        /**
                         * this field lets the user choose the
                         * name of the payment method as it
                         * appears to the normal user on your site
                         */
                        <title translate="label">
                            <label>Title</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>6</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </title>
                    </fields>
                </modulename>
            </groups>
        </payment>
    </sections>
</config>

Default configuration values

Before we go and test this, we should set some default values for the configuration fields we just created.

Open app/code/local/MyModules/ModuleName/etc/config.xml and add the following section;

<config>

    ...

    <default>
        <payment>
            <modulename>

                /**
                 * is this payment method enabled?
                 */
                <active>0</active>

                /**
                 * this is where we tell the system what
                 * class to use to handle all of the payment
                 * logic. we call this class the payment
                 * adapter model class. you can change the
                 * paymentLogic bit to be what you want
                 * but it has to be lowerCamelCase and
                 * the class name will have to be changed later
                 * on as you will see
                 */
                <model>modulename/paymentLogic</model>

                <order_status>pending</order_status>
                <title>Credit Card (My Payment Method)</title>

                <api_key>1234</api_key>
                <api_secret>1234</api_secret>

                /**
                 * this is the default set of allowed credit
                 * card types. leave this as it is for now
                 */
                <cctypes>AE,VI,MC,DI,SS</cctypes>

                /**
                 * this should be authorize or authorize_capture
                 * you can probably guess that authorize just
                 * authorizes the payment but authorize_capture
                 * processes it as well
                 */
                <payment_action>authorize_capture</payment_action>

                /**
                 * this field is used to say whether you only
                 * want this method to be used for certain
                 * countries but that is not covered by this
                 * tutorial
                 */
                <allowspecific>0</allowspecific>
            </modulename>
        </payment>
    </default>
</config>

Of course, if you have any of the fields in the above file configurable as set in system.xml, the user set value will be used.

Test progress so far

OK so now if you log into the Magento administration and go to System -> Configuration -> Payment methods you should see your new payment method somewhere in that list.

If you enable it it should then also be available if you checkout on your site as normal. Don’t complete any orders using it yet as there will be problems because we haven’t finished! We still need to create the most important part, the class which will handle all of the logic.

If you don’t see your payment method, please make sure you have completed the above steps correctly. Check for any simple mistakes and try clearing the Magento cache as well. The basic rule is; if it doesn’t appear in the payment method list in the administration section, there’s a problem with system.xml. If it doesn’t appear as a usable payment method when checking out, there could be a problem with config.xml.

4. Payment adapter model class

Create the file PaymentLogic.php in app/code/local/MyModules/ModuleName/Model/. This is where we will put all of our payment gateway logic. First, the contents of the file;

<?php
class CompanyName_NewModule_Model_PaymentLogic extends Mage_Payment_Model_Method_Cc
{
    /**
     * unique internal payment method identifier
     */
    protected $_code = 'newmodule';

    /**
     * this should probably be true if you're using this
     * method to take payments
     */
    protected $_isGateway               = true;

    /**
     * can this method authorise?
     */
    protected $_canAuthorize            = true;

    /**
     * can this method capture funds?
     */
    protected $_canCapture              = true;

    /**
     * can we capture only partial amounts?
     */
    protected $_canCapturePartial       = false;

    /**
     * can this method refund?
     */
    protected $_canRefund               = false;

    /**
     * can this method void transactions?
     */
    protected $_canVoid                 = true;

    /**
     * can admins use this payment method?
     */
    protected $_canUseInternal          = true;

    /**
     * show this method on the checkout page
     */
    protected $_canUseCheckout          = true;

    /**
     * available for multi shipping checkouts?
     */
    protected $_canUseForMultishipping  = true;

    /**
     * can this method save cc info for later use?
     */
    protected $_canSaveCc = false;

    /**
     * this method is called if we are just authorising
     * a transaction
     */
    public function authorize (Varien_Object $payment, $amount)
    {

    }

    /**
     * this method is called if we are authorising AND
     * capturing a transaction
     */
    public function capture (Varien_Object $payment, $amount)
    {

    }

    /**
     * called if refunding
     */
    public function refund (Varien_Object $payment, $amount)
    {

    }

    /**
     * called if voiding a payment
     */
    public function void (Varien_Object $payment)
    {

    }
}
?>

If the payment_action option of ‘Authorise’ has been selected, then only the authorize() method will be called and no payment can be taken automatically. If however the payment_action ‘Authorise and Capture’ was selected, then only the capture() method will be called and that method should probably authorise the payment before capturing the funds. A bit confusing and not explained anywhere but that’s how it works!

The Varien_Object $payment object holds all data to do with the transaction and also the order.

So that’s it! That’s the method I used to add a custom payment gateway to Magento. Please note: I don’t work with Magento anymore so if you have a complicated question which requires looking into Magento code, I probably won’t be able to answer it – but ask anyway just in case!

AJAX calls are obviously asynchronous. jQuery has a ‘async: false’ option in AJAX calls but it is ignored by most (maybe all?) browsers. Using this method you can force a synchronous request and retrieve that data.

function myFunction()
{
    var myVariable = $.ajax(
    {
        url: 'someScript.php',
        async: false
    }).responseText;
    alert(myVariable);
}

So .responseText retrieves the text value of the response from the AJAX call. And because we’re assigning to a variable we are forcing a synchronous request. You can now use that variable as you see fit.

This causes an issue when you are trying to retrieve a JSON object from an AJAX call into the function scope. The best way I’ve found so far is to retrieve the JSON as a string and use a jquery JSON plugin to convert it into an accessible object. Or you could just use the ‘eval’ method.

Stephen.

    $conn = Propel::getConnection();
    $query = 'SELECT * FROM `my_table`;';

    $statement = $conn->prepare($query);
    $statement->execute();

    while ($rowObj = $statement->fetch(PDO::FETCH_OBJ))
    {
        echo var_dump($rowObj);
    }

Stephen.

On my first post on this blog I posted a small snippet to use a small regex pattern in jQuery selectors.

You can find the post here: http://colourgray.wordpress.com/2008/08/05/jquery-wildcard-selectors/

I was reading through some comments and posts on some incoming links and it seems it wasn’t working for anyone anymore. I just tested it myself and unfortunately it’s true (at least with with jQuery v1.3.1). However! All is not lost, there is another method which I’ve tested from one of the incoming links to that post which you can find here:

http://ropox.net/archives/1081

Cheers ropox!

Stephen.

It’s definitely been too long since I posted here! I will try and post more regularly over the coming months…

Firstly, we came across this issue after writing a number of plugins for a symfony project. Each of these plugins had their own schema.yml files and therefore we didn’t need our own custom schema.yml file at that time.

Because of this, our config/schema.yml file looked like this:

    propel:

Pretty, right? When we ran symfony propel:build-sql (after the other usual build tasks) we got the error:

    Database "" does not exist.

In symfony’s glorious vibrant red error container. It seems when your schema file looks like ours did above, symfony generates the sqldb.map file for that file without a database name, our data/sql/sqldb.map file looked similar to this:


    # Sqlfile -> Database map
    ...
    lib.model.schema.sql=propel
    plugins.pluginName.lib.model.schema.sql=propel
    plugins.pluginName2.lib.model.schema.sql=propel
    generated-schema.sql=propel
    generated-pluginName-schema.sql=propel
    generated-pluginName2-schema.sql=propel
    ...


The quick fix, especially if you don’t want to have to add a custom table in your schema just to get round this, is to simple add ‘propel’ onto the end of the line that is missing it.

Hopefully there’s a proper fix that I so far haven’t been bothered to find…

Unable to parse default value as date/time value: ’0000-00-00 00:00:00′

Which was stopping the build. After looking at various places, it seems this is a problem with Creole, (propel’s DBAL).

Before PHP v5.2.4, you could do a strtotime on a value of 000-00-00 00:00:00 and you would get a weird date, something in 1999. Not sure why :S Since the 5.2.4 update however this bug has been fixed and you will now get boolean false returned.

The symfony plugin sfGuard, which is widely used, uses 0000-00-00 00:00:00 as a default value in it’s schema for some fields and this will now cause problems. To fix this, edit sfGuard’s schema and change those default values to something like 1970-01-01 and that should do the trick.

Unfortunately Creole isn’t actively maintained anymore so it’s not likely to be updated soon to fix this.

I found out that jQuery has a nice little method for loading external scripts into the page at run time called getScript(). It basically gets the contents of the external file using an AJAX request and then eval()s the code at runtime, which seems like a perfect way of doing it. I reckon it’s much better than appending new <script> tags to the <head> tag as well.

The only issue is that it can take some time to load an external file so you can’t always run functions from within that file straight away. Thankfully there is a workaround for this using another jQuery method. You basically set all AJAX request to be synchronous before you run getScript() and then set AJAX requests to be asynchronous again after the script is loaded. If you end up loading like 20 files at the beginning of a page load this could take a while but hopefully you won’t be doing that

$.ajaxSetup({async: false});
$.getScript(MVCRoot+fileName+'.js');
$.ajaxSetup({async: true});

And here’s some more info on this lovely little function

Yesterday at one of the talks SproutCore was mentioned. I had a look today and it looks very promising. It’s a full framework designed to create full ‘thick client’ javascript applications. The core of it was written in Ruby and I haven’t looked into whether you have to know much Ruby to develop in it or not. It reminds me of symfony because you are given a number of build tools to use on the command line for creating controllers, new projects, models etc etc.

I think I’m falling in love with the general idea and it’s great to see someone has actually implemented it quite well (from the looks of it). I haven’t had the chance to try it out yet but I’m thinking of using it on a number of personal projects so we’ll see how it goes!

We were told there were around 800 people there but with everyone sat down at the morning keynote meeting it didn’t seem like so many. Also, pretty much everyone there had an iPhone! Everywhere you looked someone had an iPhone out. I guess it’s not surprising with so many geeks in one room

The whole experience was good, the talks were in depth and on the most part interesting (we went to the wrong room at one point due to a late room switch and I couldn’t help but get a bit sleepy – the room was hot!).

There was an interesting talk by Dion Almaer on AJAX, Dion is the co-owner of Ajaxian. The session was called ‘The State of AJAX’ and he talked about how AJAX has come along in recent times and about the current popular javascript frameworks and libraries. He made a good summary of the current status of these frameworks and talked about how with each framework’s most recent user interface plug ins they are all very similar in functionality.

So which framework is best to use is now down to personal preference, where as before it was down to which framework was best for what you wanted to do. It certainly made me think about how JavaScript has become a mainstream language and it’s made me think about concentrating on JavaScript as my primary language. It’s strange, as up until recently a lot of people only saw JavaScript as an ‘add-on’ language, if that’s the right way to describe it. But now with the way the web is going, with rich user interfaces and applications, JavaScript is definitely the way forward.

There were also talks on the Google App Engine and Google Web Toolkit. Both of these are very interesting offerings but I’m not sure whether I personally, or the company I work for will have use for either of them. At least for the near future.

The Google App Engine is – in it’s most basic form – another cloud service. Much like Amazon’s EC2 service. Google are now offering the ability to host your web site or application on their existing infrastructure/system architecture. There are the same obvious advantages to using this system as there are with Amazon; large scalability, strong infrastructure, fast up link speeds etc etc. You initially get 500mb of free space, 2GB of bandwidth per day and up to 5 million page views per month for free. After which you need to start forking out the cash. From what I gathered after using your free allowances, the service won’t be charged on a pay as you go service as with Amazon, but you will have to buy ‘blocks’ of extra dish space, bandwidth etc etc. Personally I think I prefer the pay as you go method, but I haven’t done any calculations to see which would be cheaper so I could easily be wrong.

Unfortunately, the only language currently supported on the Google App Engine is Python. They mentioned yesterday that they are committed to adding more language runtimes to the system, but seeing as Python is one of Google’s 3 main languages, it was their obvious first choice. Sites and apps can only be pure Python as well, so no using plug ins/extensions which depend on C++ etc.

Google App engine is obviously still very mature so it wouldn’t be fair to compare it to the other cloud services currently on offer but so far, I think Amazon’s EC2 service is still on top. I won’t go into why here

I was very impressed by the Google Web Toolkit (GWT). The general idea is that you write your Java application in your normal IDE, run the GWT compiler against your Java code and it compiles your normal Java code into JavaScript and HTML files that can be run in any browser. Obviously this is pretty powerful. The example that we got shown was a full GUI application written in Java for viewing or creating complex diagrams. It seemed to run perfectly in the browser, looking just like it would on the desktop. All current popular browsers are automatically supported and the compiler also optimises and obfuscates the generated JavaScript and HTML code. What more could you ask for? The only problem is I don’t currently know Java and I don’t believe my company has any intentions of using Java for anything soon But an impressive product none the less.

Throughout the day there were free refreshments and snacks and we were provided with a free (mostly) healthy lunch. At the end of the day they showed a video summarising the day’s events and then there were drinks and food after which I wasn’t able to stay for My colleague stayed on for a while and told me they had a Wii being played on the huge presentation screens with Guitar Hero, among other things such as retro Atari arcade consoles. It’s a shame I didn’t stay, I’d have been able to say I beat some Google guys at Guitar Hero! Woop

The day was a good experience and I’d go again, although some sessions did seem quite long and the seats weren’t exactly comfortable, but a small price to pay for an event like this

Oh yeah, I didn’t take any photos except for a few of the Wembley pitch (by going through a door I don’t think we were allowed to go through) because I was told I wasn’t allowed. Then we saw lots of other people taking pictures :S Ah well…

So this is just a simple example showing you that. This also applies to the normal DataGrid and standard list controls.

The itemEditEnd event is dispatched (it’s in the name) when a user finishes editing a cell so this is pretty much the best time to save the user’s changes to that field/row.

Here’s our function:

protected function saveChange(event:AdvancedDataGridEvent):void
{
    /**
     * use event.dataField to get the edited field name
     */
    var field:String = event.dataField;

    /**
     * i'm using the following line to get the 'id' of the row being edited
     * because i passed an 'id' field through from my dataProvider.
     */
    var selectedID:String = event.currentTarget.selectedItem.id.toString();

    /**
     * use the itemEditorInstance to get the newly edited value but retrieve
     * the previous value from the existing grid data. i'm using the default
     * textinput itemRenderer so I can retrieve the new value using the
     * itemEditInstance's 'text' property.
     */
    var newValue:String = event.currentTarget.itemEditorInstance.text;
    var prevValue:String = ProductPersonalisationList.selectedItem[event.dataField];

    // run a http service call or something to save the change or validate the data
}