com.smartgwt.client.docs
Interface ComponentSchema


public interface ComponentSchema

Component Schema

A component schema is a special type of DataSource that describes a custom component.

Declaring a component schema for your custom component allows you to:

Example of a Component Schema

It's most basic form, a component schema for a custom subclass of ListGrid called "MyListGrid" looks like this:

 <DataSource
 serverType="component" ID="MyListGrid" 
             inheritsFrom="ListGrid"
 instanceConstructor="MyListGrid"/>
 
With this definition saved as "MyListGrid.ds.xml" in the project dataSources directory ([webroot]/shared/ds/ by default), you can now create an instance of MyListGrid with just:
 <MyListGrid width="500"/>
 
Note: you may need to restart your servlet engine/J2EE container before this example will work.

The attributes set directly on the DataSource tag have special meaning for a component schema definition:

Declaring custom properties

Custom properties are declared via 'fields' as for an ordinary DataSource. As with ordinary DataSources, it is legal to redeclare inherited fields in order to modify properties such as 'field.editorType'.

The following DataSourceField properties have special significance when a component schema is used to process 'component XML':

When a component is edited within Visual Builder, the DataSource properties that normally influence databound forms will influence the Component Editor (for example, field.title, field.editorType). In addition, the following properties have special signficance in component editing and component drag and drop:

Declaring Events and Actions

Events and Actions are declared via a methods array. In order for a method to be considered an event, it needs to have a method definition in the methods array (or be publicly documented in the Smart GWT reference) and have been added to the class as a 'StringMethod' via com.smartgwt.client..Class#registerStringMethods.

In order for a method to be considered an action, it needs to have a method definition in the methods array and have the action property set to true. For example, the following is a definition of the 'hide' action available on any Canvas, as copied from Canvas.ds.xml:

     <methods>
         <method name="hide"
 title="Hide" action="true"/>
     </methods>
 
For custom component actions, an array of expected parameters may be specified using the params attribute. Each entry in this array should have a specified type. By doing this, you allow the visual builder to pass parameters through to actions when setting up events that call actions (possibly on another component). For example if you had a component with a custom action that expected to be passed a single parameter of type ListGridRecord you could define it as follows:
     <method
 name="showRecordDetails" title="Show Record Details" action="true">
         <params>
            
 <param type="ListGridRecord"/>
         <params>
     </method>
 
If a user working within the visualBuilder then added ListGrid to the page and used the "+" icon to associate the ListGrid.addRecordClickHandler(com.smartgwt.client.widgets.grid.events.RecordClickHandler) event with this custom method, the Visual Builder logic would automatically associate the parameters available in the fired event (in this case recordClick) with the expected parameters for the action to fire by type. So the record parameter of the event (known to be of type ListGridRecord) would be passed through to this custom showRecordDetails action as the first parameter.

See Also:
DataSourceField.getXmlAttribute(), DataSourceField.getMultiple(), DataSourceField.getChildTagName(), DataSourceField.getPropertiesOnly(), DataSourceField.getInapplicable(), DataSourceField.getGroup()