In the previous section of the tutorial we have assembled a simple
layout for a component. Within this section of the tutorial we are
going to develop the header panel for this component. We want a collaboration engineer to be able to configure this panel.
This allows us to explore how to use the configuration of the component.
In general, the header panel should display both a title and the
label of the superior contribution. The collaboration engineer should be able to set the following
properties:
We put all these configuration options into a category labeled header field. The following listing shows this category with an empty configuration of the header panel.
<Component type="Header_Panel">
<Categories>
<Category>
<Name>Header Field</Name>
<Fields>
//put the configuration of the component here
</Fields>
</Category>
</Categories>
In the following section we are implementing fields together with the JavaScript code needed to handle the configurations.
As seen in the hello world tutorial we can use a text field for the configuration of the header title. The following listing shows this initial configuration.
<TextField> <Name>headerTitle</Name> <Label>Header Title</Label> <HelpText>Title that shows up in the header</HelpText> <HoverText>Title for the header above the attachments </HoverText> <CharacterWidth>35</CharacterWidth> <MaximumCharacters>65535</MaximumCharacters> <RegularExpression/> <ValidationMessage/> <InitialTextValue> <DefaultValue>Default Header Title</DefaultValue> <Incremented>false</Incremented> <Required>false</Required> </InitialTextValue> </TextField>
The text value 'headerTitle' in the node Name is a unique identifier for this particular text field. You can configure the label, help text, hover text, as well as some specific properties of a text field. These configurations determine how the text field is displayed in the CACE editor.
Now that we have defined a text field, we need to access the value a collaboration engineer has entered there. We use the renderer to access this text value. The renderer returns a configuration object giving us access to all of the entries made by the collaboration engineer for our component. The following listing shows an example of how to read a text value of the component configuration. We use its function getPropertyValue. This function returns a string containing the value of the property; the identifier for the text field (headerTitle) is used as a key identifying the property.
var componentConfig = = renderer.getComponentConfiguration();
this.getHeaderTitle = function () {
return componentConfig.getPropertyValue("headerTitle");
};
The following listing shows the validation of a string property by a helper function. The string is valid when it is defined, not null, and contains at least one character.
var tud_validName = function (stringToValidate) {
return (stringToValidate && stringToValidate.length > 0);
};
this._hasHeaderTitle = tud_validName(this.getHeaderTitle());
In order to define the height of the head a panel the collaboration engineer has to enter a number. For the header panel we are going to use the entered height to configure an Ext JS object, so that the collaboration engineer does not have to enter any unit. The following listing shows the XML configuration for the height of the header.
<TextField> <Name>headerPanelHeight</Name> <Label>Header Height</Label> <HelpText>The Height of the panel in pixels. Needs to be large enough to hold your title</HelpText> <HoverText>Header Height in pixels</HoverText> <CharacterWidth>35</CharacterWidth> <MaximumCharacters>65535</MaximumCharacters> <RegularExpression/> <ValidationMessage/> <InitialTextValue> <DefaultValue>55</DefaultValue> <Incremented>false</Incremented> <Required>true</Required> </InitialTextValue> </TextField>
The field is a text field. ActionCenters does not provide special fields for numbers. We use the function parseInt to decode the string into an integer (see the following listing).
var panelHeight = parseInt(componentConfig
.getPropertyValue("headerPanelHeight"));
A collaboration engineer should have the option to replace the build in header panel with some customized HTML markup, e.g. through the markup control. For the attachments component this means that the collaboration engineer might not want to use the build in header panel at all. We therefore provide a field isHeaderVisible. This field is a BooleanField displayed as a checkbox. We have to specify labels and string representations for the boolean values. The following listing shows the configuration of the boolean field:
<BooleanField> <Name>isHeaderVisible</Name> <Label>Display header?</Label> <HelpText>Should the header be visible?</HelpText> <HoverText>Should the header be visible?</HoverText> <Type> <CheckBox>true</CheckBox> </Type> <InitialBooleanValue>Y</InitialBooleanValue> <True> <Label>Yes</Label> <Value>Y</Value> </True> <False> <Label>No</Label> <Value>N</Value> </False> </BooleanField>
The property entered in a boolean field can be one of two strings: 'Y' or 'N'. In the JavaScript code we have to decode this property into a boolean value:
/**
* Returns true of the parameter is strictly equal to 'Y' and false otherwise.
* Use to evaluate boolean properties of this component.
*/
var tud_translateToBoolean = function (stringYorN) {
return (stringYorN === 'Y') ? true : false;
};
this.hasHeader = tud_translateToBoolean(componentConfig.getPropertyValue("isHeaderVisible"));
The background gradient of the header panel requires valid colour definitions in RGB. We are going to use a style template to define the background gradient, creating a linear gradient between two colours.
ActionCenters provides a ColorPickerField. The CACE editor will display a colour picker widget to support the collaboration engineer in selecting colours. The following listing shows the configuration of the colour fields.
<ColorPickerField> <Name>headerPanelColorStart</Name> <Label>Header Color Start</Label> <HelpText>The background color of the header panel. This value specifies the start of a gradient color.</HelpText> <HoverText>The background color of the header panel. This value specifies the start of a gradient color.</HoverText> <InitialColorValue> <DefaultValue>#6699CC</DefaultValue> <Required>true</Required> </InitialColorValue> </ColorPickerField> <ColorPickerField> <Name>headerPanelColorStop</Name> <Label>Header Panel Color Stop</Label> <HelpText>The background color of the header panel. This value specifies the stop of a gradient color.</HelpText> <HoverText>The background color of the header panel. This value specifies the stop of a gradient color.</HoverText> <InitialColorValue> <DefaultValue>#99CCFF</DefaultValue> <Required>true</Required> </InitialColorValue> </ColorPickerField>
We use a linear gradient for the background of the header panel. To keep things simple in this tutorial, we only support Firefox. The linear gradient is defined through a Template. This template contains a style with two placeholders, start and stop. The following listing shows how to use this template:
var tpl = new Ext.Template('background: -moz-linear-gradient({start}, {stop});');
var backgroundColor = tpl.apply({
start: componentConfig.getPropertyValue("headerPanelColorStart"),
stop: componentConfig.getPropertyValue("headerPanelColorStop")
});
var extraStyle = 'text-align: center;' + backgroundColor;
So far we have shown you how to read the properties and how to decode them so that they can be used within our code. As a next step, we work on the constructor of the header panel, so that all these configurations are taken into account.
//assemble the header panel
if(this.hasHeader) {
var headerPanel = new Ext.Panel( {// this panel is used to present the header
itemId : 'attachmentHeaderPanel',
region : 'north',
height : panelHeight,//height of the panel
header : false,
bodyCssClass : 'x-outliner-header',
bodyStyle : extraStyle, //background gradient
margins : '2 2 1 2',
html : getHeaderTitle() //title to be displayed
});
panelItems.push(headerPanel);
}
var supName = superiorContribution.getPropertyValue('name');