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:

  - use simpler XML when creating your custom component: avoid having to specify the `constructor` and `xsi:type` attributes as described under `ComponentXML`
  - use your custom component within `VisualBuilder`

  Example of a Component Schema

  In its most basic form, a component schema for a custom subclass of ListGrid called "com.mycompany.MyListGrid" looks like this:

        <DataSource serverType="component" ID="MyListGrid"
                    inheritsFrom="ListGrid" instanceConstructor="com.mycompany.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 com.mycompany.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:

  - `serverType`="component" indicates this DataSource describes a component, as opposed to a SQL table or other data provider
  - `ID` means the tagName that will be used to create your custom component. This must match the first component of the filename. (ID="MyListGrid" means the filename must be MyListGrid.ds.xml, and typically also matches the name of the class).
  - `DataSource.inheritsFrom`="ListGrid" inherits the ListGrid property definitions via `DataSource.inheritsFrom`.
  - instanceConstructor="com.mycompany.MyListGrid" indicates the SmartGWT class that should be called on to construct an instance.

  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`:

  - `field.type` declares the type of the field, and hence the type of the value your custom class will be initialized with. In order to declare subcomponents, can be set to the name of another component (built-in or custom).
  - `field.multiple` declares that the field should always be array-valued even when only a single value is provided. Also indicates that the field name should be used as a "wrapper tag" in the XML format for the component.
  - `field.propertiesOnly`. For fields that hold subcomponents, suppresses auto-construction to avoid `double drawing` and to allow subcomponents to be modified by their parent component before they are created and drawn
  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 significance in component editing and component drag and drop:
  - `field.inapplicable` indicates that an inherited field is inapplicable in this component.
  - `field.group` indicates what group the property should be placed in when editing in Visual Builder.
  - `field.xmlAttribute`: indicates this field should serialize as an XML attribute. Note that when constructing the component from XML, either an attribute or a subelement will continue to be accepted as means of specifying the field value, so this property is primarily set in order to make code generated by Visual Builder maximally compact or to make it conform to externally set standards.

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