-- PedroRio - 17 Feb 2011

XEO Web Components - Custom Component Creation

XEO comes bundles with a set of pre-defined componets to help you deal with various situations, but there will always be a situation where you need something so specific that you'll have to create your own custom component.

To create and user a XEO Web Component you need three parts (which will be explained in detail bellow):

• An Implementation class
• A Renderer Class
• Register the component project

_

Implementation Class

To create a new Custom XEO Web Component you'll need to define an implementation class which willbe responsible for declaring the component properties and the component's logic. A custom component must extend the netgest.bo.xwc.framework.components.XUIComponentBase class (or any class that extends from that one, including XEO's own components).

When creating an implementation class you declare the set of properties of the components as class variables (of a particular type) and you can redefine some of the methods that are responsible for component logic (inherited from the XUIComponent Base Class). Read the following paragraphs in order to know how to declare component properties.

Component Properties

Component properties allow you to configure a given component with a certain value (for a certain attribute it had), as such they are extremelly usefull when creating reusable components. The value of a property can be either supplied directly in the xml definition a viewer, or binded to a java bean property. Also, properties can have a notion of state (remembering their previous values). There are four different types of properties (properties are typed):

• XUIBaseProperty (Simple property whose value can only be provided in the XML definition of the component)
• XUIBindProperty (value can be binded to a java bean property)
• XUIStatePropery (property has a state, remembers its previous values)
  • XUIStateBindPropertu (property has a state, remembers its previous value and can be binded to a java bean property)
• XUIMethodBindPropery (property is binded to a method in a java bean)

When declaring properties you'll also need to declare their data type (any type is valid). bellow is an example of declaring a property named text (of type String) and bindable to a java bean.

private XUIBindProperty<String> text = 
        new XUIBindProperty<String>("text", this, String.class);

Notice the use of generics when declaring the property, but also the last parameter of the constructor is the class (this is required) also, the first parameter is the name of property as a string and the second parameter is the component itself. You could also use another constructor which allows you to supply a default value, like the following:

private XUIBindProperty<String> text = 
        new XUIBindProperty<String>("text", this, String.class, "Default Text");

If declaring a simple property without any binding to the bean you can do the following:

private XUIBaseProperty<String> other = 
        new XUIBaseProperty<String>("other", this);

When declaring a property, you should also declare a getter and a setter like the following (if it's a property which it not binded to a java bean property):

public String getOther(){
        return other.getValue();
}
    
public void setOther(String newValue){
        other.setValue(newValue);
}

and like the following if the property is binded to a java bean property.

public void setText( String textExpr ) {
        this.text.setExpressionText(textExpr);
    }
    
public String getText() {
        return this.text.getEvaluatedValue();
}

Check the JavaDoc for further documentation on the API's for the types of properties. ( Será que preciso de mais do que isto)

Component Behavior

Inherited from the XUIComponentBase class are some methods that can be overridden to implement specific behavior of the custom component, like the following:

• preRender - Method that's executed right before the component is rendered to the client allows you to make modifications to the component after the initialization.
• initComponent - Method that's executed after the component is created, it's used to perform the component initialization.
• wasStateChanged - Used to see if the component's state was changed, which may be used to determine in the component renderer if something should be done or not.

Renderer Class

The renderer class is the class that's responsible for generating the HTML/CSS/Javascript necessary to render the component inside a viewer. Each renderer class must extend the netgest.bo.xwc.framework.XUIRenderer class and override a few methods in order to work. One very important step when creating the renderer of a custom component is to create a placeholder for the component. The placeholder should be an html div element having as identifier the identifier of the component (component identifiers are generated automatically if not declared in the xml definition).

XEO's Renderer classes are usually declared as inner classes of the implementation class but they can be declared in a separate class as well. If declared inside the implementation class the should be declared as follows:

public static class XEOHTMLRenderer extends XUIRenderer { }

The renderer class can have any other name, just be sure that when registering the component you use the same name (if using XEO Studio's Web Component Wizard, this step is not necessary).

The skeleton of a renderer class is shown bellow.

public static class XEOHTMLRenderer extends XUIRenderer {
            
        @Override
        public void encodeBegin(XUIComponentBase component) throws IOException {}
        
        @Override
        public void encodeEnd(XUIComponentBase component) throws IOException {}

        @Override
        public void decode(XUIComponentBase component) { super.decode(component); }
        
}

There are three main methods.

_

You can also use the component as a servlet..

aa

Registering the component in the project

Automatically done using XEO Studio, but can be edited manually

aaa

Using the Component in a Viewer

aa

Creating a custom component

aa