AMF Protocol handling
From Snapp CMS Developer Documentation
SnappCMS has built in support for the | AMF data format. This is a binary format used for the transmission of ActionScript data between SWFs and the server. When using Flex or Flash, this format is the recommended method of transferring data as data payloads are much smaller (compared with XML or JSON) and the client does not need to convert between a foreign format and native ActionScript objects. The net result is Flash applets that use this format will generally run much faster than those using another format to accomplish the same task.
SnappCMS's implementation of AMF handling uses the Zend Framework's AMF stack.
Contents |
Setup
In order to use AMF you need to activate it for your site and configure your Flash applet to communicate with your site's AMF gateway.
On your site
In order to enable AMF handling, the following entry must be made to your site's config.ini file, in the [Site] section:
amf=1
In your Flash applet
AMF requests should all be sent to:
http://<Your Site Name>/cms/amf/gateway.php. Consult your Flash documentation for instructions on how to set up AMF
handling on the client side.
Development Environment
You'll want to do your testing using Firefox, with Firebug and the AMF Explorer extension.
When running tests, open Firebug to the Net tab, each AMF request will show up as a POST to gateway.php.
To see the contents of the request and response, click on a request and select the AMF Request Response tab respectively
to see a hierarchical representation of the transferred data.
The Classes
AMF classes are accessible from:
/cms/amf/services/Snapp - SnappCMS-supplied core classes (e.g. AMFGallery, AMFContent)
DOCUMENT_ROOT/custom/amf - Project-specific classes
Rather than allowing AMF clients direct access to all of Snapp core, we create gateway classes in the locations above. These can have their own specific functionality, or can simply be an extension of an existing module. We are adding new AMF classes to Snapp all the time. For a list of currently available classes, see the SnappAMF documentation in the SnappCMS API.
Note that AMF classes make use of PHPDocs. Use class level and method level comments in valid PHPDoc format to make these classes developer-friendly (and tester friendly - see below)
e.g. if we create a site-specific module in DOCUMENT_ROOT/custom/moduleSpecial.php:
<?php
/**
* @copyright 2006-2010 SnappCMS Pty Ltd
* @package myproject
*
*/
/**
* moduleSpecial
*
* My fancy special module that does cool things
*
* Backend configuration is performed using the "Special" CMS tab.
*
* Front-end pages usually access the module via <code>DOCUMENT_ROOT/modules/special/index.php</code>
*
*
* DB Tables
* - custom_special_table_1
* - custom_special_table_2
*
* CMS Admin Modules
* - Special
*
* Site-specific files
* - modules/special
*
* @package myproject
* @subpackage special
*
*/
/**
*
*
* @author DanM
*/
class moduleSpecial extends moduleBase {
/**
* Say hello to the world
*
* @param array $params
* @return string a fancy string
*
* $params options:
*
* - str (string): The string you'd like to say
*/
public function specialFunction($params = array()) {
if (array_key_exists('str', $params)) {
return "Hello World, your string is ".$params['str'];
} else {
return "Hello world, you said nothing!";
}
}
}
We then create an AMF wrapper class in DOCUMENT_ROOT/custom/amf/Custom/Special.php. Note the package annotation in the PHPDocs:
<?php
/**
* @copyright 2006-2010 SnappCMS Pty Ltd
* @package SnappAMF
*
*/
/**
* Custom_Special
*
* AMF wrapper class for moduleSpecial
*
* {@inheritdoc}
*
* @package SnappAMF
* @see moduleSpecial
*/
/**
* Special AMF wrapper for moduleSpecial
*/
class Custom_Special extends moduleSpecial {
// This class empty
}
The fact that a class has been created in a sub-folder of DOCUMENT_ROOT/custom/amf/ folder means that all the publicly accessible
methods of the custom module class are now exposed to AMF clients.
If you are writing a module that is only ever accessed via AMF and never by regular HTTP requests, you could simply create the
Custom_Special class as a base class and forget about moduleSpecial altogether, but standard practice is to put
the model code into a module class and have the AMF class wrap it.
Class Naming Conventions
By convention, place custom classes in DOCUMENT_ROOT/custom/amf/Custom/. There may be some shared code between
projects that we don't want to put into core. In this case, the code can be bundled into a package folder
DOCUMENT_ROOT/custom/amf/MyPackageName/, and classes would be named MyPackageName_MyClass.
Note that as we are using Zend Framework's implementation of AMF, we need to use Zend-style class naming conventions to work with the Zend autoloader Class names must be prefixed the package name followed by an underscore, and use camel case with first letter in upper case.
i.e.:
- If an AMF class file is stored in
DOCUMENT_ROOT/custom/amf/Custom/MyClassName.php, the class name must beCustom_MyClassName.
WARNING: Package folder names must begin with an UPPER CASE letter, as per Zend's class naming conventions.
e.g.
DOCUMENT_ROOT/custom/amf/MyPackage/MyClassName.php // This is good
DOCUMENT_ROOT/custom/amf/myPackage/MyClassName.php // This is bad - lowercase package folder name
DOCUMENT_ROOT/custom/amf/myPackage/myClassName.php // This is bad - lowercase class filename
Debugging
In Browser
You'll want to do your testing using Firefox, with Firebug and the AMF Explorer extension.
When running tests, open Firebug to the Net tab, each AMF request will show up as a POST to gateway.php. To see the contents
of the request and response, click on a request and select the AMF Request Response tab respectively to see a hierarchical
representation of the transferred data.
The AMF Gateway has a debug mode, which is activated by setting debug=1 in config.ini.
If the mode is enabled, than any error messages are relayed back to the AMF client, and these can be viewed in Firebug using the AMF Explorer plugin. If debug mode is turned off, error objects will be returned to the client as empty strings, to hide sensitive system information from the end user.
A successful AMF call will return a response with targetURI=/x/onResult
A failed AMF call will return a response with targetURI=/x/onStatus
ZamfBrowser
ZamfBrowser is a tool that allows you to explore the published methods available to a project and test the calls. It requires Adobe Air to run, and is available for download at: http://www.zamfbrowser.org/
Once installing it, ensure that debug = 1 is set in config.ini, then point it at the gateway
URL you want to test (usually http://<site_name>/cms/amf/gateway.php) and figure out the rest!
