Forums, Knowledge Base and FAQs/Forums/Share Your Custom Widgets

How To: Magento eCommerce Widgets v1.0

Paul Joyce
posted this on October 08, 2010 23:36

magento_logo.pngImagine being able to keep an eye on your important eCommerce metrics on a large screen that auto updates!  That sounds like a perfect candidate for a Geckoboard widget!

To get the ball rolling we're starting with one of the most widely used eCommerce platforms, Magento.  The implementation is a little different to how we usually do it as Magento is self-hosted software, but it gives us the opportunity to really build what people need and it allows them to customise it to their taste.  Right now, the script outputs either the volume or total value of orders between 2 dates, and optionally also outputs the same data from a different period for the sake of comparison.  The periods can be send via URL parameters.

An example of how it would be used with Geckoboard would be to show the volume/value of sales on your Magento store over the past 30 days and compare it to the previous 30 days.   

Warning

magentoWidgets.pngToday we're releasing v1 of the Magento script, it's not perfect but it's a start and with your help and feedback we can make it into something special.  This script was written by me, Paul, while the developers of Geckoboard (the brains behind the whole operation) were working on some major changes to the dashboard.  My PHP skills are poor so see this as a test script and only deploy to production when you're satisfied it doesn't break anything.  You have been warned.

One final thing before we get on to explaining how this works, please do change the script and adapt it to your purpose but please also share those changes with the rest of the community here.  You've nothing to lose and you could make a lot of people very happy :)

The files need to be unzipped and placed in the same directory (I simply used the root of my local Magento test install).  You'll need to make some modifications to gbwidgets.php before you start:
Line 54.  You need to change the URL here to reflect your server.  My Magento root for testing was http://localhost:8888/magento, I don't know a lot about Magento but I reckon if you substitute your shop's home page for that string it should be OK.  So your URL would look something like http://www.yourmagentoshopname.com/api/soap/?wsdl I reckon.
Line 58.  Substitute your values for apiUser and apiKey.  These are the ones you set up in the admin console under System>>Web Services
Line 62.  This is a filter which tells the script what order statuses to ignore.  It's currently ignores order with a status of 'On Hold', 'Canceled', 'Suspected Fraud' and 'Payment Review'.  Change this if you want to.  You can also add any other filters here.
Line 79.  For security this file can only be accessed by a user with a security key.  At the moment it's set to '123', change this here and keep a note of it, you'll need it for the Geckoboard part.
How to use
Assuming you placed the scripts in the root of your Magento install and that's located at "http://www.yourmagentoshopname.com/" here's an example URL you would use:
This would return 2 values; the value of sales in the 30 days to last night and the value of sales in the 30 days previous to that.  The XML that's produced (or JSON if you prefer, see line 12 of gbwidgets.php) is enough to drive the "Number and secondary stat" Geckoboard widget.  See this page for more info on the custom widget types.  This part is lifted from the documentation in the script:
     * ps - period start (days ago incl.) - default 1 
     * pe - period end - default 1
     * pps - prior period start (for comparison purposes) - optional
     * ppe - prior period end - optional
     * m - metric type - 1=order volume, 2=order value (default 1)
     * The default values will return sales yesterday.  To return sales in past 30 days (including today) and compare against previous 30 days use the following:
     * ps=30&pe=1&pps=60&ppe=31
In Geckoboard
Once your scripts are modified and ready to go, fire up your Geckoboard dashboard and add a new widget.  Use Custom Widget>>Number and secondary stat with the following settings:
URL data feed.  Use the url to the script with whatever parameters you want.  E.g. http://www.yourmagentoshopname.com/gbwidget.php?ps=30&pe=1&...
API key.  Use the value you set in step 4 above.  Default 123
Widget type.  Custom
Feed format.  XML
Reload time.  300
Label.  Whatever you want!
Cross your fingers and hope for the best :)
This is only the beginning - you can enhance this script to return different metrics and format the data for different widget types including the newly introduced custom charts.  Once you confirm this is working I'll open it out to others on the Help & Support forum and hopefully you guys can build on it from there.
In the meantime, let me know if anything is unclear or if you're having any difficulty and I'll do my best to help.

Installation

There are two files attached to this post (response.class.php and gbwidget.php, find them at the bottom) that need to be uploaded the same directory on a publicly accessible server capable of executing php (I simply used the root of my local Magento test install).  You'll need to make some modifications to gbwidgets.php before you start:

  1. Line 54:  You need to change the URL here to reflect your server.  My Magento root for testing was http://localhost:8888/magento, I don't know a lot about Magento but I reckon if you substitute your shop's home page for that string it should be OK.  So your URL might look something like http://www.yourmagentoshopname.com/api/soap/?wsdl .
  2. Line 58:  Substitute your values for apiUser and apiKey.  These are the ones you set up in the admin console under System>>Web Services
  3. Line 62:  This is a filter which tells the script what order statuses to ignore.  It's currently ignores order with a status of 'On Hold', 'Canceled', 'Suspected Fraud' and 'Payment Review'.  Change this if you want to.  You can also add any other filters here.
  4. Line 79:  For security this file can only be accessed by a user with a security key.  At the moment it's set to '123', change this here and keep a note of it, you'll need it for the Geckoboard part.

How to use

Assuming you placed the scripts in the root of your Magento install and that's located at "http://www.yourmagentoshopname.com/" here's an example URL you would use:

http://www.yourmagentoshopname.com/gbwidget.php?ps=30&pe=1&pps=60&ppe=31&m=2

This would return 2 values; the value of sales in the 30 days to last night and the value of sales in the 30 days previous to that.  The XML that's produced (or JSON if you prefer, see line 12 of gbwidgets.php) is enough to drive the "Number and secondary stat" Geckoboard widget.  See this page for more info on the custom widget types.  This part is lifted from the documentation in the script:    

  • ps - period start (days ago incl.) - default 1
  • pe - period end - default 1
  • pps - prior period start (for comparison purposes) - optional
  • ppe - prior period end - optional
  • m - metric type - 1=order volume, 2=order value (default 1)
  • The default values will return sales yesterday.  To return volume of sales in past 30 days (including today) and compare against previous 30 days use ps=30&pe=1&pps=60&ppe=31

In Geckoboard

Once your scripts are modified and ready to go, fire up your Geckoboard dashboard and add a new widget.  Use Custom Widget>>"Number and secondary stat" with the following settings:

Custom Widget Settings
URL data feed Use the url to the script with whatever parameters you want.  E.g. http://www.yourmagentoshopname.com/gbwidget.php?ps=30&pe=1&pps=60&ppe=31&m=2
API key Use the value you set in step 4 above.  Default 123
Widget type Custom
Feed format XML
Reload time 300
Label Whatever you want!

Now just hit "Add to dashboard", and you're done!

What now?

This is only the beginning - you can enhance this script to return different metrics and format the data for different widget types including the newly introduced custom charts.  Once you confirm this is working I'll open it out to others on the Help & Support forum and hopefully you guys can build on it from there.
In the meantime, let me know if anything is unclear or if you're having any difficulty and I'll do my best to help.

 

Comments

User photo
Philippe

Tried the widget. And it works !

One thing to know,for periods, today is 0, not 1 (which is default = yesterday)

I added the average amount by order, for metric=3

I'll make a list of Magento needed widgets, and maybe we can work on something nice with pies, charts and lots of nice things !

October 29, 2010 19:16
User photo
Paul Joyce
Geckoboard

Hey Philippe - thanks for your contribution, that sounds great!

You might also want to connect with @choomz who made a Magento contribution here.

October 29, 2010 19:40
User photo
Michael

I tried to install this widget, but to no prevail. I am using 1.4.0.1 of Magento, so that may be the difference. I have done the changes, and looked at the code, but I'm at a loss, i even set it up to localhost seeing that I'm using the same computer.

 

Other Note, LOVE Geckboard!!

January 27, 2011 14:47
User photo
Paul Joyce
Geckoboard

Hi Michael - sorry you're not having any luck with this. Can you tell me where you're encountering problems? For example, what happens when you visit http://localhost:8888/magento/api/soap/?wsdl does it return anything?

January 27, 2011 16:47
User photo
Michael

I get a blank screen.

http://208.100.36.202/api/soap/?wsdl

 

That is the URL

January 27, 2011 16:57
User photo
Paul Joyce
Geckoboard

Unfortunately I'm not a Magento expert. However, I have found an article describing the same problem as you're getting (Magento SOAP WSDL URL returns a blank page), maybe it's worth trying the solution the author used to see if it works for you.

January 27, 2011 17:45
User photo
Michael

Thank you on that. Well i got it to load, but all i see is blank. 

https://mirvine.geckoboard.com/dashboard/54E40F107796EE04/

January 27, 2011 18:04
User photo
Nirav Sheth

Hi Paul,

I'm running Magento enterprise and this is def returning a blank screen to me as well. I know I have my URL correct because if I go to it, it works (http://store.cleanprogram.com/api/soap/?wsdl). And I created my API user and key. And that was entered in correctly. Now when I go to my link, it shows nothing. Look at http://store.cleanprogram.com/gbwidget.php?ps=30&pe=1&pps=6...

I don't think this has to do with the link you shared above because my SOAP URL itself is working. It's not missing a bracket. I think it has to do with the actual gbwidget.php file. 

Would you be able to help??

February 23, 2011 06:15
User photo
Jon Gledhill

Any chance Geckoboard is going to support the new Magento Go Hosted Software?

April 26, 2011 15:19
User photo
Ciara
Geckoboard

Hi Jon,

Thanks for the suggestion. I've added it to our Feature Request forum http://support.geckoboard.com/entries/20062416-magento-go-hosted-so.... It would be great if you could vote on it or let us know what you'd like to see from it so we can see about the possibilities of getting it in.

Thanks

April 28, 2011 15:09
User photo
Ashley Schroder

Not to sound too spammy but OrderPipe.com now provides a range of Geckoboard widgets powered by data from Magento, Amazon and Shopify.Makes the connection process really easy.

You can read more about the widgets and setup here:

http://blog.orderpipe.com/orderpipe-now-integrates-with-geckoboard

Beta is here:

http://www.orderpipe.com

December 22, 2011 22:04