Other than the JavaScript, every block needs to have an XML document that describes it. This information is used to describe how other blocks can interact with the block, what methods can be called, and the parameters for these methods. The information is used to describe what the block is about: keywords, a description, and some logos. An XML schema file (BlockSchema.xsd) is included in this kit. It contains the definition of the allowed structured for the XML and should be used to validate the XML that you write.
EditMetadata Structure
There is a simple sample below that covers the basics. It should be noted that all values and nodes are case sensitive, so make sure the casing matches what you have in the JavaScript.
Line number 1 needs to be the XML header. This is required and should look identical to the line below.
<?xml version="1.0" encoding="utf-8"?>
EditBlock Node
The top level (root) element of the XML document is the block node it has one attribute class
<block class="SoapBoxClass">
class - The name of the JavaScript function which defines the block.
Below the block node there are four children that contain literal values and have no children of their own.
providerName Node
<providerName>SoapBox</providerName>
The providerName should be the name of the service or company that is providing the information (only for data blocks)
providerUrl Node
<providerUrl>http://soapbox.msn.com/</providerUrl>
The providerUrl should be an absolute URL to the provider’s homepage i.e. http://soapbox.msn.com.
providerLogoUrl Node
<providerLogoUrl>http://www.popflycreator.com/content/components/icons/soapBoxLogo.png</providerLogoUrl>
The providerLogoUrl should be an absolute URL to the provider’s logo, don’t forget you might need permission to use their logo...
<operations>
This node has no attributes and is solely used as the parent for the operation nodes.
operation Node
Each operation you want exposed to users through the designer needs to have an operation node. The node itself has only one attribute: name.
<operation name="search">
name - The name of the JavaScript function that this node is describing.
The operation node has three children: description, inputs, and outputs.
description Node
This node’s value is used by the editor to show a human readable description of this operation/function so that the user knows what to expect when it’s invoked. It should be written in human friendly terms.
<description>
Search SoapBox to find videos that you want to watch.
</description>inputs Node
The inputs node is the parent for each of the input nodes. Each input should map directly to a parameter on the function being described in this operation node. The input nodes must appear in the same order as their corresponding parameters do in the JavaScript function.
<inputs>
input Node
The input node has three attributes (name, required, and type) and three children: description, defaultValue and constraints. All attributes and children are required, but can be left empty.
<input name="searchTerm" required="true" type="string">
name - The name of the JavaScript parameter.
required - Is the parameter required or not, allowed values are true/false.
type - The type of value that is expected (see MetaData Type System).
description Node
The description node describes what the input is for in human terms.
<description>The term to search on.</description>
defaultValue Node
The defaultValue node should contain a value that will work with your block. When a user drags a block to the design surface, the editor will place the default value into the inputs. This way a user can just preview your block and get a result – a user will see how it is supposed to work.
<defaultValue>comedy</defaultValue>
constraints Node
The constraints node should be used when you want to limit the values that are valid for this input. For example, you might want to limit it so the user can only enter the name of a state.
ouputs Node
The outputs node is the parent for the output node. There should be only one output node. It represents the return value of the function that the operation node is describing.
<outputs>
output Node
The output node describes the return type from the function so that any blocks that it might be mashed with can have a better understanding of what to expect. The output node has 3 attributes and no children.
<output isArray="true" type="custom" object="SoapBoxVideo" />
isArray - Does the function return an Array? If it does, then true, otherwise, false.
type - The type of value that is expected (see MetaData Type System), if you use the type custom there needs to be a corresponding object node with a name that matches object attributes value.
object - If you return a custom object the name of the object should be the value of this attribute. The object also needs to be described in the objects node.
objects Node
The last child of the block node is objects. This node is the parent for all the object nodes. Each object node describes a custom class you use in your JavaScript. This allows the editor to figure out how to mash blocks together, and provides the user with more information about the JavaScript classes you use. The objects node itself has no attributes and only children named object.
object Node
The object node has only one attribute, name, and has children named field for each property the JavaScript class has.
<object name="SoapBoxVideo">
name - The name of the JavaScript class this object node represents
field Node
The field node represents a property on the JavaScript class. Ideally, every property you have should be represented here, unless you want to hide some from the user. The node has three attributes and no children.
<field name="Title" type="title" isArray="false" />
name - The name of the JavaScript property this field node represents.
type - The type of value that is expected (see MetaData Type System), if you use the type.
isArray - Is the property an Array? If it does, then true, otherwise, false.
properties Node
The properties node of the document represent values that should be applied to a block regardless of the function that a user wants to use. Examples of these would be setting the default zoom level in virtual earth or setting the color of the frames in carousel. In Popfly properties are implemented as two methods a getter and setter (or accessor and mutator) when Popfly wants to read you’re the current value of your property it will call the getter and when it wants to change the value it will call the setter passing in the value. Because of this your getter function shouldn’t need any parameters and the setter should only take one parameter which is the new value of the property. In Popfly the mashup designer will never need to read your property so you don’t strictly need to provide a getter, it’s only really useful for mashup authors who want to use custom code.
In Javascript an implementation of the property might look something like:
CarouselClass.prototype.setMaxItems = function(num)
{
this._maxItems = num;
};
This is the setter function for the property maxItems in carousel. The name of the function is set in the XML manifest, only convention has it to be set<property name>. Clearly the code for the property is trivial in this case just setting a variable. The tricky part is where it is used in the case of carousel every time an image is added the number of images is compared to _maxItems and if it is equal to or greater than than oldest item is removed.
The XML element for the property in the manifest looks like:
<property name="maxItems">
<description>
The maximum number of items to display.
</description>
<setter>
<operation name="setMaxItems">
<inputs>
<input name="num" required="true" type="nonNegativeInteger">
<defaultValue>20</defaultValue>
</input>
</inputs>
</operation>
</setter>
</property>description Node
<description>A description</description>
This node should contain a plain text description of the purpose of the property, the description will be shown in the tool tip on the mashup designer.
setter Node
<setter>
This node described the setter function, it is child operation is identicall to the operation node for blocks discussed earlier. For more information please see the section operation Node. One thing to keep in mind is that the setter function will be invoked after the class is initialized and before any part of the users mashup runs.