In this 'Hello-World' tutorial, we take a look at the XML wrapper and the constructor of a component. We develop a component with one property label. This component should print a message onto the console of firebug. Furthermore, we show you how to run a component in ActionCenters.
We assume that you are running ActionCenters on a local server and that you are familiar enough with the CACE tool to put together a screen. In addition, we expect you to use Firefox together with Firebug (see Resources for further information)
When implementing a component, you have to develop an XML wrapper
specifying attributes of the component. These attributes can be modified
by a collaboration engineer through the CACE editor. In addition to the attributes defined
in the XML wrapper, every component also has a number of general
attributes. ToDo: Link to a documentation of general attributes of a component
The following listing shows a simple XML wrapper.
<?xml version="1.0" encoding="UTF-8"?>
<ActionCenterElements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://server.actioncenters.org/svn/AC/actioncenters-xml/ActionCenterElements.xsd">
<Component type="Hello_World">
<js>
<code> //Put your code here </code>
</js>
</Component>
</ActionCenterElements>
The root of the XML specification is an ActionCenterElements; the schema file defines its structure. Components are defined as children of ActionCenterElements. Every component has a mandatory property 'type' (here: 'Hello_World'), which serves as both an identifier for the component and a label displayed to the collaboration engineer in the CACE editor. The user interface and the communication with the server are implemented in JavaScript and placed in the node code.
Our Hello World component has one property label. The following listing shows how this property is defined in the XML wrapper:
<Component type="Hello_World">
<Categories>
<Category>
<Name>Hello World Configuration</Name>
<Fields>
<TextField>
<Name>label</Name>
<Label>Header Label</Label>
<HelpText>HelpText</HelpText>
<HoverText>HoverText</HoverText>
<CharacterWidth>20</CharacterWidth>
<MaximumCharacters>30</MaximumCharacters>
<RegularExpression />
<ValidationMessage />
<InitialTextValue>
<DefaultValue>Hi There!</DefaultValue>
<Incremented>false</Incremented>
<Required>true</Required>
</InitialTextValue>
</TextField>
</Fields>
</Category>
</Categories>
Properties can be sorted into categories, each category
contains fields, and each field specifies one property of the component.
For the Hello World component we define one category,
Hello World Configuration, which has a descendant TextField
with the Name label and the initial value of Hi There!.
The label is a required property of the component.
When putting together the Header Panel of the component
we explore how to work with
the configuration in more detail.
The JavaScript part of every component has to provide a specific constructor (see Client Side Plugin). In the following listing we show the implementation of the Hello World component.
var Hello_World = function(superiorContribution, renderer, subrenderers, target) {
var msg = 'hello world';
console.debug(msg);
console.debug("superior contribution");
var supContribMsg = superiorContribution._msg;
console.debug(superiorContribution);//printing out the object
console.debug(Ext.encode(supContribMsg));//printing out the object as a JSON string
console.debug("Component Configuration");
var componentConfig = renderer.getComponentConfiguration()._msg;
console.debug(componentConfig);
console.debug(Ext.encode(componentConfig));
console.debug("Population Rules");
var popRules = componentConfig._msg.populationRules;
console.debug(popRules);
console.debug(Ext.encode(popRules));
};
The name of the constructor of the component
is exactly the same as the type property of the component (see first
listing). For now, the component itself does not display anything in the
browser. Instead, it offers a way to inspect the most important parameters handed over
to the component. The superiorContribution is a ActionCenterContribution
serving as the root contribution for all contributions displayed in this component.
The renderer has the type ComponentRenderer and contains the component configuration, which in turn contains the population rules.
The Hello World component prints the superior contribution, component
configuration and the population rules onto the firebug console, each one
as an object and as a JSON message. We use the function Ext#encode
of the Ext JS library to encode the objects as JSON
messages. This library is already loaded by default into any ActionCenter.
The target is a DOM element into which the component should render itself (see the part Basic Layout of this tutorial). Last, the subrenderer is an array containing objects of type ComponentRenderer. Each renderer is subordinate to the renderer of the Hello World component. (Within this tutorial we won't cover how to handle subrenderers).
<?xml version="1.0" encoding="UTF-8"?>
<ActionCenterElements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://server.actioncenters.org/svn/AC/actioncenters-xml/ActionCenterElements.xsd">
<Component type="Hello_World">
<Categories>
<Category>
<Name>Hello World Configuration</Name>
<Fields>
<TextField>
<Name>label</Name>
<Label>Header Label</Label>
<HelpText>Sets the label displayed in the header of this tool.</HelpText>
<HoverText>Sets the label displayed in the header of this tool.</HoverText>
<CharacterWidth>20</CharacterWidth>
<MaximumCharacters>30</MaximumCharacters>
<RegularExpression />
<ValidationMessage />
<InitialTextValue>
<DefaultValue>Hi There!</DefaultValue>
<Incremented>false</Incremented>
<Required>true</Required>
</InitialTextValue>
</TextField>
</Fields>
</Category>
</Categories>
<js>
<code>
var Hello_World = function(superiorContribution, renderer, subrenderers, target) {
var msg = 'hello world';
console.debug(msg);
console.debug("superior contribution");
console.debug(superiorContribution);
var supContribMsg = superiorContribution._msg;
console.debug(Ext.encode(supContribMsg));
console.debug("Component Configuration");
var componentConfig = renderer.getComponentConfiguration()._msg;
console.debug(componentConfig);
console.debug(Ext.encode(componentConfig));
console.debug("Population Rules");
var popRules = componentConfig._msg.populationRules;
console.debug(popRules);
popRules = Ext.encode(popRules);
console.debug(popRules);
};
</code>
</js>
</Component>
</ActionCenterElements>