It’s pretty easy to use and the requirements are basic. It’s hosted on Google Code so feel free to play around with it. More details and usage instructions etc can be found on it’s project page and Wiki.

s3Cinch on Google Code

There are a number of big features that I’ll be looking at implementing over the coming weeks so the script should be improving quite regularly.

Stephen.

Update: version 1.1

Added the ability to back up MySQL databases from remote servers.

Update: version 1.2

Added ability to control when backups are scheduled, either hourly, daily, weekly or monthly.
Added commenting to instruction files.

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.

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.

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;

1
2
3
4
5
6
7
8

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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?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.

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;

1
2
3
4
5
6
7
8
9

<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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

<?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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

<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.

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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

<?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.

1
2
3
4
5
6
7
8
9

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.

1
2
3
4
5
6
7
8
9
10

$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:

1
2
3
4
5
6
7
8
9

# 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

1
2
3

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

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

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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
}

Then I began to think about it. We already know that a client-side MVC is possible, but I can now see why it would be useful. But it wouldn’t be the traditional MVC architecture, it would really only be VC, the view and controller layers. And that’s all it can ever really be. Javascript can never directly access the model in a web application environment.

I decided that a VC client-side system would still be useful and I’m probably going to develop one for future use. I haven’t got round to doing this yet but these are my ideas.

Firstly, looking at a few of our sites, I could quickly see that there were many javascript files being loaded per page as they were needed. The number of files could range from 5 to 10 or even more. So we need a way of dynamically loading javascript files onto the page as and when they are needed, on the fly. I initially thought that it wasn’t possible to dynamically load javascript files from within a javascript page but I Googled around a bit and when I found the solution it was painfully obvious: you simply load more tags in the section of the HTML.

So with that in mind, lets create a simple front controller. What does it need to do? It needs to have some basic configuration for the MVC; where the root of the files are etc. It needs to have the aforementioned function to load external javascript files into the current page. It needs to have an initialisation function which kicks the MVC off:

mvc.init.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

/**
 * client MVC initialiser
 */
 
/**
 * wheres are the MVC files?
 *
 * @access public
 * @var    string
 */
var MVCRoot = '/js/';
 
/**
 * initialise the controller
 */
$(document).ready(function()
{
    loadJS('mvc.controller');
    Controller.init();
});
 
/**
 * load an external js file by appending
 * script tag as child to <head> section
 *
 * @var    fileName name of file to load
 * @return bool true on success, false on no fileName given
 */
function loadJS(fileName = null)
{
    if (fileName != null)
    {
        $('<script type="text/javascript" src="'+MVCRoot+fileName+'.js"></script>').appendTo('head');
        return true;
    }
    else
    {
        return false;
    }
}

Ok most of that should make sense. The loadJS() function is fairly straight forward, it simply builds a HTML <script> tag for the new javascript file and appends it to the <head> tag of the HTML. The $(document).ready function then uses this function to ‘include’ the main controller file (which will be /js/mvc.controller.js according to the current config). Now that the init function can call methods of the Controller class it calls the main controller’s initialisation method.

As an initial idea, the main controller could start off looking like this:

mvc.controller.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

/**
 * client main controller
 */
 
var Controller = 
{
    /**
     * holds the current page's type
     * used for loading required js files etc
     *
     * @var    string
     * @access protected
     */
    var _pageType : null,
 
    /**
     * main controller init function
     * gets current page type
     * includes required js files
     */
    var init : function()
    {
        loadJS('mvc.controller.ajax');
        Controller._getPageType();
 
        /**
         * logic to include required files dependent on page
         * type etc etc
         */
        ...
    }
 
    /**
     * returns the page type for current URI
     *
     * @return void
     */
    var _getPageType : function()
    {
        var currentURI = window.location;
        Controller._pageType = ControllerAjax.getPageType(currentURI);
    }
}

Again this is mostly basic stuff and it definitely hasn’t been tested but I think the general idea is in the right direction. I think now that I can visualise how to seperate out javascript objects more clearly I can see how this would benefit a javascript heavy web site/application.

Even though web frameworks have been gaining more and more popularity over recent years I hadn’t thought of applying the same methodical approach to client side coding until my colleague suggested this idea. I think if you think about it and you’re thinking like I was, you can quickly warm to the idea as I have. Almost every day you can read a new article about how in development, we need to be separating out our different types of logic and our layers. Javascript is of course just another language, so why should it not get the same treatment?

“XML namespaces are used for providing uniquely named elements and attributes in an XML instance. They are defined by a W3C recommendation called Namespaces in XML. An XML instance may contain element or attribute names from more than one XML vocabulary. If each vocabulary is given a namespace then the ambiguity between identically named elements or attributes can be resolved.”

So they provide a way of differentiating between similar, or same named XML elements/attributes in an XML document. How do you use them? Here’s an example:

<?xml version="1.0" encoding="utf-8"?>
<root xmlns:prod="http://www.my-site.com/namespaces/product" xmlns:ship="http://www.my-site.com/namespaces/shipping">
    <prod:items>
        <prod:item>
            <prod:name value="My product" />
            <prod:code value="123321" />
            <prod:price prod:currency="GBP" value="11.99" />
        </prod:item>
    </prod:items>
    <ship:method ship:postCode="CR3 4FT">
        <ship:name value="Next day AM" />
        <ship:price ship:currency="GBP" value="3.99" />
    </ship:method>
</root>

The first thing you’ll probably notice is the use of the xmlns attributes of the root node. This is used to declare a namespace. It can be used on any node and only child nodes of a node with the xmlns attribute will be able to use that namespace.

The part after the colon – in one of our cases ‘prod’ – is the alias for the namespace. All elements and attributes of that namespace have to be prefixed with this alias. The URL that the xmlns attribute points to doesn’t actually have to contain anything, it doesn’t even really have to exist. Your standard browser XML parser doesn’t take any information from this URL, it’s just there for usability. Some people use this URL to give information on what the namespace in question is used for and what it’s attributes/elements are. Oh, and it can’t be an empty string (”")!

Of course, there are lots of tutorials around for this, this is mainly for reference

$.fn.myFunction = function()
{
    // use the following loop to iterate through all objects
    // returned by the jQuery selector which was used
    return this.each(function()
    {
        // here we can access any properties using
        // the normal jQuery selectors
        alert($(this).html());
        $(this).addClass('red');
    });
};

So this function alerts the HTML of the selected element(s) and adds a new class ‘red’. You can then call the new function using:

$('#myElement').myFunction();

Another example of how easy and powerful jQuery is Look here for more information.

There are quite a number of tutorials covering change event triggers for RadioButton controls but this is slightly different.

Say you have a form and you want to process the RadioButton value after submitting the form instead of when the value of it changes.

To do this you actually have to create a RadioButtonGroup MXML tag for the radio buttons and select the value using the ’selectedValue’ property of that RadioButtonGroup:

<mx:RadioButtonGroup id="myRadioButtonGroup" enabled="true" />
<mx:RadioButton label="I like RadioButtons" groupName="{myRadioButtonGroup}" left="505" top="64" selected="true" value="true"/>
<mx:RadioButton label="I don't like RadioButtons" groupName="{myRadioButtonGroup}" left="348" top="62" value="false"/>

Notice the {} around the groupName attributes of the RadioButton controls. You can then do this to select the value:

Alert.show(myRadioButtonGroup.selectedValue.toString());

I’m going to cover two scenarios;

Assigning XML results as a dataProvider:

This is by far the simplest of the two:

// The initialisation function
protected function init():void
{
    var serviceObj:HTTPService = new HTTPService();
    serviceObj.resultFormat = 'e4x';
    serviceObj.method = 'GET';
    serviceObj.useProxy = false;
    serviceObj.addEventListener(ResultEvent.RESULT, processResult);
    serviceObj.url = 'myScriptURL.php';
    serviceObj.send();
}

// The result processing function
protected function processResult(response:ResultEvent):void
{
    // make sure the response is cast as the correct data type
    var XMLResults:XML = response.result as XML;
    MyDataGrid.dataProvider = XMLResults.user;
}

// Sample XML sent from the server
<?xml version="1.0" encoding="utf-8" ?>
<users>
    <user>
        <id>1</id>
        <username>stephen</username>
        <email>stephen@example.com</email>
    </user>
</users>

You’ll notice I’ve set the resultFormat attribute of the HTTPService object to be ‘e4x’. In my experience I’ve found e4x more useful to work with XML in Flex. e4x stands for ECMAScript for XML and you can find out more about it here. e4x allows you to use XML as a primitive data type in your actionscript. I.E. you can do:

var myXML:XML = <root>
                    <myNode>
                        <myChildNode />
                    </myNode>
                </root>;

When using e4x as the result format, you don’t have to reference the root node when processing the XML, which is why I use the line

MyDataGrid.dataProvider = XMLResults.user;

instead of

MyDataGrid.dataProvider = XMLResults.users.user;

Creating a new XML dataProvider from an existing RPC result

This method is slightly more complicated but isn’t really needed as much. There’s really only a few situations that this would come in handy but I’ve had to use it on a recent project so I thought I may aswell post it.

Say you are making a call to a preexisting web service which is out of your control. In my situation, the web service WAS in my control, but it was already being used for other means so changing the output now wasn’t really an option. I wanted to process the XML, perform some logic on it and then add a new variable or two into the XML before assigning it to my DataGrid control.

The method I used in the end is quite simple and quick to do. You basically create a new empty XML document, loop through the results of the web service call, perform your logic and rebuild the new values into the new XML document. You then assign it to your control:

protected function processResult(response:ResultEvent):void
{
    // make sure the response is cast as the correct data type
    var XMLResults:XML = response.result as XML;
    // create the new XML document
    var newXML:XML = new XML('<users></users>');
    // loop through previous results
    for (var i:String in XMLResults.users)
    {
        // userXML is going to be our new user XML record
        var userXML:XML = new XML();
        // status is the new variable I want to add to the dataProvider
        var status:String;
        // perform some logic on the previous results
        if (XMLResults.users.activated[i] == 1)
        {
            status = 'Active';
        }
        else
        {
            status = 'Inactive';
        }
        // build the new XML record for this user
        // we can use {XMLResults.user.field[i]} to keep any previous elements in tact that we want to keep
        // use the {} parenthesis to put actionscript variables into the XML datatype
        userXML =
                <user>
                    {XMLResults.user.username[i]}
                    {XMLResults.user.email[i]}
                    <status>{status}</status>
                </user>;
        // add the new user record to the XML document
        newXML = newXML.appendChild(userXML);
    }
    MyDataGrid.dataProvider = newXML;
}

Of course there are a large number of tutorials around for this but again, this is just for reference.

Also, a lot of these commands will work for other database engines which support SQL, but I mainly work with MySQL

I might possibly add a more advanced reference at a later date.

Creating a table

CREATE TABLE `table_name`
(
    `id` INT(11) AUTO_INCREMENT NOT NULL,
    `field_1` VARCHAR(50) NOT NULL,
    `field_2` VARCHAR(255) NOT NULL,
    `field_3` TEXT,
    PRIMARY KEY (`id`)
)

So the lines for adding fields are in the format:

`field_name` FIELD_TYPE EXTRA_OPTIONS

You can get a list of all supported field types in MySQL here.

Extra options that I’ve used here are;

AUTO_INCREMENT – This tells MySQL that this field is going to be this table’s auto incremented field. This means the field will go up by one for each new row. There can only be one auto incremented field per table. This is usually used for primary keys / row identification fields.

NOT NULL – This tells MySQL to not default to NULL values for these fields as there will always be a value inserted here.

I’ve also added a PRIMARY KEY instruction to this query. It’s good practice for every table to have a primary key, even if you see no obvious use for one. This is usually an id field as shown above. To have a field set as auto incremented, it must also be a primary key, otherwise MySQL will throw an error.

Removing or emptying a table

DROP TABLE `table_name`;

DELETE FROM `table_name`;

TRUNCATE TABLE `table_name`;

DROP TABLE will completely remove the table from the database. It will be as if this table never existed and it will have to be created to be used again. I’ve only really had to use DROP TABLE when I’ve made a mistake in creating the table and it’s easier to completely remove it and re-create it instead of amending it.

DELETE FROM `table` will do exactly that. It will delete all rows from the table but leave the table structure in tact. This is useful for a quick clean up of something like test entries but keep in mind that an auto incremented field will keep the last auto incremented value after this query. I.E. if you had 400 rows and you run a DELETE query as shown above, the next time you enter a row into this table, the auto incremented field value will be 401, not 1.

TRUNCATE TABLE does the same as DELETE FROM except that instead of deleting all records, it resets the table. I.E. all rows are removed and auto incremented field value is reset to 0.

Amending a table

ALTER TABLE `table_name` RENAME `new_table_name`;

ALTER TABLE `table_name` ADD `new_field` FIELD_TYPE OPTIONS [FIRST/AFTER `field_name`];

ALTER TABLE `table_name` CHANGE `field_name` `new_field_name` NEW_FIELD_TYPE NEW_OPTIONS;

The first query simple renames a table to a different table name.

The second query is used to add new fields to an existing table. The FIELD_TYPE and OPTIONS can be the same as noted above. You can use the FIRST/AFTER part to add the field to a particular place in the table, I.E.:

ALTER TABLE `table_name` ADD `field_name` VARCHAR(255) NOT NULL AFTER `id`;
ALTER TABLE `table_name` ADD `another_field_name` VARCHAR(255) NOT NULL FIRST;

The third query can be used to alter an existing field’s values. I.E. you want to change a field from VARCHAR(255) NOT NULL to VARCHAR(50).

There is also a way to re-arrange the column order in a table but this isn’t every really needed. If you would really like to do it, you can read more about it here.

Insert, updating and removing specific rows

INSERT INTO `table_name` VALUES ('value_1', 'value_2', 'value_3','value_4');

UPDATE `table_name` SET `field_name` = 'new value', `another_field_name` = 'another new value' WHERE `id` = 56;

DELETE FROM `table_name` WHERE `id` = 56;

The first query is used to insert a new record into a table. If you insert a new record this way, without specifying which fields you are giving values for, you HAVE to give values for every field. If you only want to insert values for certain fields, you can use the following query:

INSERT INTO `table_name` (`field_1`, `field_2`, `field_5`) VALUES ('field_1_value', 'field_2_value', 'field_3_value');

If you want to insert multiple rows at once you can have a comma separated list of values, I.E.:

INSERT INTO `table_name` VALUES ('value_1', 'value_2', 'value_3','value_4'),('value_1', 'value_2', 'value_3','value_4'),('value_1', 'value_2', 'value_3','value_4');

INSERT INTO `table_name` (`field_1`, `field_2`, `field_5`) VALUES ('field_1_value', 'field_2_value', 'field_3_value'),('field_1_value', 'field_2_value', 'field_3_value'),('field_1_value', 'field_2_value', 'field_3_value');

If you are inserting a value for an auto incremented field, you should enter NULL.

The UPDATE query above is for updating an existing row, it consists of a comma separated list of field = value pairs and a WHERE clause to specify which row(s) to update. The list of field = value pairs can contain as many fields as you want.

The DELETE query above is the same as the one mentioned before for emptying a table except it now has a WHERE clause which is used to delete one selection of rows.

There are lots of tutorials on how to handle them in Flex 2 but this doesn’t apply for Flex 3, as Flex 3 natively handles double click events and Flex 2 did not.

There are also a lot of tutorials on how to amend functionality so that you have to double click to edit a row instead of the default single click. This tutorial does not cover this, this tutorial covers functionality of double clicking a row and then triggering something. I.E. a table of products, you want to double click a row to view product details etc.

First off, we need to make a slight amendment to our DataGrid (or AdvancedDataGrid, same applies to both):

<mx:DataGrid id="MyDataGrid" doubleClickEnabled="true" itemDoubleClick="functionName(event);">
...

There are obvious meanings to both of these new attributes; doubleClickEnabled is used to tell Flex we want to allow/handle double click events on this DataGrid and itemDoubleClick tells Flex which function to use.

The above function should look something like:

protected function functionName(event:ListEvent):void
{
    var selectedRow:Object = event.currentTarget.selectedItem;
    Alert.show(selectedRow.myVariableName);
}

You can directly access the selected row from the DataGrid using the event.currentTarget.selectedItem reference. You can then access any variable that exists in the DataGrid’s dataProvider for that row.

Of course to get the above working you’ll need to:

import mx.controls.Alert;
import mx.events.ListEvent;

Stephen.

This is the first tutorial on my blog. We’re going to start with something simple and it’s only useful if you use jQuery.

When I started using jQuery I found it hard to find information on using wildcards when selecting DOM elements.

After a while you get to understand that jQuery allows the use of regular expressions in a lot of places, I.E. when selecting like this:

$('#myElement').html();

So with this in mind, you can use \\S* to make wildcard selections, I.E.:

$('#myEle\\S*').each();

Stephen.