SWX: SWF Data Format

Although I have implemented quite a few usability enhancements to it, there are still a few gotchas to watch out for when using the SWX Service Explorer in Beta 1.2.

One of these is that you must encode the values that you pass in JSON format yourself. This is a limitation in the original Amfphp service browser that the Explorer is based on. Mostly, this limitation will not affect you with simple data types but there are times when you will get erroneous results unless you this.

For example, if you are passing a string that begins with a number, you must surround it in double quotes to pass it as a string (or else it will be passed as a number and the string portion will be ignored).

To be safe, surround all string values in quotes. In other words, pass "hello, world" instead of hello, world.

You must also be aware of this limitation if you are passing arrays or objects as a value.

The next version of the SWX Service Explorer (Beta 1.3) will handle this encoding for you.

Another gotcha is that leaving an optional parameter's value empty in the Explorer will actually result in that parameter having an empty value, not the default value that's set in the service method. The workaround to this, currently, is to manually enter the default value in Explorer. The next version of Explorer will handle this properly.

Also, Folkert informed me today that the Results panel doesn't automatically close when you change methods. I just updated the Explorer in SVN to implement that and updated the SWX Service Explorer on the SWX public gateway to the latest version.

Finally, you can find the source for the SWX Service Explorer, which you can also use for your Amfphp projects as an updated version of the service browser (just change the gateway to point to gateway.php instead of amf.php) in SVN at http://svn1.cvsdude.com/osflash/swx/trunk/flex/Explorer/. (When I get a moment, I will make an Amfphp-specific build too).

In the past few days, I've been working on making the SWX Service Explorer a friendlier beast. Today, prompted by the error Kelvin Luck reported, I added better error handling that should help with a common issue that people may run into with Beta 1.1: The problem with the incorrect default gateway URL.

The problem

The error that Kelvin ran into happens when the SWX Service Explorer cannot find the AMF gateway that it uses. This can occur due to two reasons: Firstly, if your server is down or you are disconnected from your server/Internet/etc., and secondly, if the the SWX Service Explorer is configured with the wrong URL to the AMF gateway. The latter is the default case with the Explorer in Beta 1.1 because I couldn't obtain the source for it (it's based on the service browser in AMFPHP) in time for that release. It means that you have to configure the SWX Service Explorer to the correct Gateway URL (change gateway.php to amf.php) before you can use it. Otherwise, you currently get the cryptic error message that Kelvin got.

The solution

I now have the source and have begun to implement improvements to the Explorer, including changing the default Gateway URL in the SWX MAMP Bundle so that it now points to the AMF gateway in SWX (which is the file amf.php in the php folder, as opposed to the file gateway.php in AMFPHP.) So, hopefully, starting with Beta 1.2, this issue should become much less common (at least when running SWX using the SWX MAMP Bundle).

However, because the same error can surface if the server is not running (and if the Gateway URL is not configured properly when running SWX on your own server, without the SWX MAMP Bundle), I also added better handling for the error.

Specifically, you now receive the following error message if the gateway cannot be reached:

Beyond stating the problem in a simple manner, it also shows you the Gateway URL (which you can click on to test if the gateway is reachable in the browser) and also provides easy access to the Preferences window so you can change the Gateway URL if you need to.

I hope this helps makes working with the SWX Service Explorer easier for you guys.

I took today to implement further usability enhancements to the SWX Service Explorer (formerly the PHP Service Browser) and the SWX Data Analyzer (formerly the SWX Analyzer) and to give them both a new, more streamlined and consistent look and feel.

You can see the results here:

• SWX Service Explorer
• SWX Data Analyzer

Here are the changes I made to the SWX Service Explorer:

• Replaced the methods data grid with a combo box (usability enhancement). It is now much faster to browse the methods in a service class/API and to go to the one you want (you can press the first letter of a method to jump to it, for example.)
• All action buttons have been moved into control bars at the bottom of the sections that they affect (usability enhancement).
• Defaults to the correct gateway (amf.php not gateway.php) and will work out of the box with the SWX MAMP Bundle without requiring any configuration.
• Added labels to the buttons to make their purpose clearer.
• Reduced size of the header and made it consistent with the one in the SWX Data Analyzer.

The only changes to the SWX Data Analyzer are aesthetic changes. Both apps now use a custom background color for the preloader too (what can I say, I'm a sucker for pretty things!)

The URL of the SWX Service Explorer on the public SWX gateway will change to http://swxformat.org/php/explorer with the release of SWX Beta 1.2 this week. The http://swxformat.org/php/browser URL will forward to the new one so old links don't break.

I will be recording new screencasts for Beta 1.2 featuring the new Analyzer and Explorer.

I hope you like the new tools and here's to Beta 1.2!

I just updated the service browser on the public SWX gateway to the latest version in SVN.

There are a few minor usability improvements:

• Changed the default gateway URL so that it points to the correct gateway (amf.php instead of gateway.php) and will work out of the box with the MAMP Bundle without requiring configuration.
• Moved the Call button so that it is always present on the screen and doesn't scroll.
• Added a Hide Results/Show Results toggle button to make it easier to go back and forth between viewing returned results and altering method paramaters.

This version of the service browser will be included in Beta 1.2, to be released this week.

One thing I forgot to mention in the SWX screencast is that you have to change the gateway URL in the PHP Service Browser from gateway.php to amf.php when you first start it. This setting is saved locally so that you only have to set it once.

You can change the setting in subsequent uses of the PHP Service Browser by accessing the Configuration panel using the first icon at the top-left of the application.

I do apologize for the unnecessary extra step in configuring the PHP Service Browser. It should come pre-defined with the correct URL but I have not been successful in getting the source for the PHP Service Browser from Patrick Mineault (the service browser is the one that is in Amfphp). I will keep trying and hopefully, once I have the source code, I will be able to make this change.

Worst case scenario, if I can't get the source, I will have to fork the service browser using the latest publicly available source (which is not for the latest version of the service browser in Amfphp) and lose time recreating some of the great functionality in the latest version.

I'm off to send Patrick another email...

SWX Beta 1.1, which will be released shortly, contains a couple of API changes for the SWX Twitter API. These changes are currently in the trunk of the SWX SVN repository.

• friends() method now requires a password and returns all friends (even those marked as private).
• The old friends method (that doesn't require a password) has been renamed friendsNoAuth(). This method will not return friends who only give updates to friends.
• New method: followersWhoAreNotFriends() returns a list of your followers who you have not added as a friend. This is a utility method that uses the friends() and followers() methods.

Additionally, thanks to code contributed by Wouter, the SWX Twitter API no longer requires cURL. It will use cURL if it is available but if not, it will fall back to use a non-cURL method.

Thanks to Larry Mahony, who reported the bug, I've now fixed SWX so that it should work correctly on PHP 4.4.3. The fix is in the trunk of the SWX SVN repository and will be incorporated into the next Beta release too.

Thanks again, Larry!

I'm updating the SWX gateway on swxformat.org to the latest Beta 1 version that I am about to release within the next hour or so. This change should not require any client-side changes in your SWX applications.

The main changes here are that your applications will not need to call System.security.allowDomain() on the loaded SWX SWF data files. Instead, if you are not using the SWX API, you will need to pass a url parameter into your data holder movie clip and set its value to _url. The SWX server, after validating that this is a valid URI, will use it in the allowDomain() statement it places in the SWX data SWF to allow your application to access its data. This is a much better way of doing things than the previous method which used (_parent._url) and meant that your application had to allow the SWX data SWF access to itself also. Although you should never place any sensitive data in a SWF, this approach makes more sense in terms of security.

If you do not set a url parameter in your data holder, SWX will function as it did before and you will need to specifically allow domain the data holder movie clip (i.e., your existing apps should continue to work regardless of whether you use the new method or the old.) The Full API in the Beta release uses the new method.

Also, there is now a cancelAllCalls() method in the Full API that you can use to cancel all outstanding SWX calls in the queue.

I deployed the Beta 1 SWX gateway to swxformat.org yesterday and my twitter badge on aralbalkan.com promptly stopped working. This was because I had mistakenly removed the System.security.allowDomain call in the main SWF. This call is currently necessary because, if allowDomain is on in the SWX server config file, the created data SWF using _parent._url in its own allowDomain call. Of course, it needs access to the parent SWF for this call to succeed so the parent SWF has to, in turn, grant it access. That's not really ideal as the data SWF doesn't otherwise need access to the parent SWF. I'm looking into a better way of doing this by actually writing out the URL of the parent SWF into the returned data SWF and want to include this in Beta 1.

In the meanwhile, though, if you have deployed examples that stopped working yesterday, please either add System.security.allowDomain(gatewayUrl); to your examples (if you didn't already have it) or update from svn and use the full API, which will do this for you automatically.

In a few moments, and ahead of the Beta 1 package release, I will be deploying the Beta 1 build of the SWX server to swxformat.org in order to make sure that those sample files that use the public gateway work correctly.

There is one big API change in Beta 1 that will affect all existing SWX applications that are running off the public SWX gateway on swxformat.org (http://swxformat.org/php/swx.php).

The arguments property for your data holder movie clips is now args. This change was made for two reasons: One, arguments is a reserved word and, although it doesn't clash with the built in arguments object (for method calls), I still didn't feel right using it. The second reason is to make it consistent with the new SWX full API in Beta 1. See this post for an example of the full API (note: I just updated that post to reflect this API change so it will be slightly different to how it was yesterday).

I will amend this post with an update once this is done. Please update your applications accordingly once the public gateway is upgraded.

This change (of course) will not affect any local development versions of the SWX gateway you may have until you upgrade to SWX Beta 1.

Update: I'm still updating all the sample apps (of which there are multiple versions to demonstrate usage without the api, with the minimal api and the full api) so this, along with the beta release, is going to be delayed to tomorrow).

Update: I've updated the gateway on swxformat.org to the Beta 1 version. Please implement the API change outlined above in your applications if you are hitting the public gateway here.