com.smartgwt.client.docs
Interface ComponentXML

public interface ComponentXML

Component XML

As covered in the QuickStart Guide Chapter 4, Coding, Smart GWT components can be created in either XML or JavaScript format. This section covers some of the details of using the XML format, called "Smart GWT component XML".

Referring to previously created components

To refer to another component by ID in XML, use <Canvas ref=/>. For example:

  <Canvas ID="myCanvas"/>
  <Canvas ID="myCanvas2"/>
  <VLayout>
      <members>
          <Canvas ref="myCanvas"/>
          <Canvas ref="myCanvas2"/>
      </members>
  </VLayout>
  

JavaScript expressions

To embed a JavaScript expression into component XML, use the <JS> tag. For example:

  <VLayout>
      <width><JS>isc.Page.getWidth() - 20</JS></width>
  </VLayout>
  

Note that, like all component XML properties, the width property can be specified either as an XML attribute or as a subelement. Expressing it as a subelement, as shown above, allows the <JS> tag to be used.

Embedding Methods

For StringMethods such as ListGrid.recordClick, JavaScript code can be used as an ordinary element value:

  <ListGrid>
      <recordClick>if (record.age > 65) doSomething()</recordClick>
  </ListGrid>
  

To embed an actual function definition, use the <JS> tag described above. For example:

  <ListGrid>
      <recordClick><JS>function (viewer, record, recordNum, field) {
           if (record.age > 65) doSomething();
      }</JS></recordClick>
  </ListGrid>
  

Unfortunately, characters commonly used in JavaScript code, such as ampersand (&), are not legal inside XML element or attribute values. For example, the expression "record != null && record.age > 65" must be written as shown below, or it is not considered valid XML:

  <ListGrid>
      <recordClick>
          if (record.status != null &amp;&amp; record.age > 65) doSomething()
      </recordClick>
  </ListGrid>
  

An alternative, for larger blocks of code, is to use the XML standard "CDATA" (character data) processing directive, which allows ampersand and other characters to be used without special notation:

  <ListGrid>
      <recordClick><![CDATA[
          if (record.status != null && record.age > 65) doSomething()
      ]]></recordClick>
  </ListGrid>
  

Overall, embedding code in XML can be awkward. Isomorphic generally recommends that significant chunks of JavaScript code, such as non-trivial custom components, be moved to separate, purely JavaScript files, while code embedded in component XML is limited to simple expressions and short functions.

Troubleshooting

XML parsing errors, which happen when XML is not well-formed and would be rejected by any standard XML parser, are reported in the server-side log, and, when possible, also in the client-side log within the "Results" tab of the Developer Console.

Other issues with component XML can result from incorrect use of Smart GWT component XML tags. For example, you may specify a property and it may appear to have no effect even though it clearly works in other, JavaScript-based examples. If you get this symptom, you can troubleshoot by looking at the JavaScript code Smart GWT generates from component XML.

Smart GWT always translates Smart GWT component XML to JavaScript format before execution. This is done automatically by the <isomorphic:XML> tag for XML embedded in a .jsp file, and you can "View Source" with your browser to see the generated XML. You can also use the "Eval XML" section in the "Results" tab of the Developer Console to see the generated JavaScript ("Show JS" button) and to dynamically execute component XML ("Eval XML" button). These facilities will help you troubleshoot issues with incorrectly specified XML.

Custom Properties

If you specify a custom property on a component in XML, for example:

  <Canvas myProperty="false"/>
  

The value of the property will be a JavaScript String. In the above example, it would be the string "false", which is considered a boolean true value in the JavaScript language. If you want a different JavaScript type, you can force a property to be interpreted as a given type by using the "xsi:type" attribute:

  <Canvas>
      <myProperty xsi:type="xsd:boolean">false</myProperty>
  </Canvas>
  

The same notation works when you want to declare that an entire subobject has a given type. For example, this would cause the custom property "myListGrid" to have a live ListGrid instance as it's value. All of the properties on the <myListGrid> tag will be correctly interpreted as ListGrid properties and have the correct types.

  <Canvas>
      <myListGrid xsi:type="ListGrid" width="500" height="600"/>
  </Canvas>
  

If you do not want an actual live ListGrid, but rather a JavaScript Object containing properties for later construction of a ListGrid, use the propertiesOnly attribute. For example, this code would cause the property "listGridProperties" to be a JavaScript Object with properties "width" and "height", whose values would be JavaScript Numbers.

  <Canvas>
      <listGridProperties xsi:type="ListGrid" propertiesOnly="true" 
                           width="500" height="600"/>
  </Canvas>
  

For your reference: "xsi" stands for "XML Schema Instance"; this notation derives from XML Schema standards for explicitly specifying type inline.

Custom Components

If you use defineClass() to define a new component class "MyListGrid" which is a subclass of the built-in component ListGrid, you can create it in XML as shown below:

  <ListGrid constructor="MyListGrid" width="500"/>
  

By using the <ListGrid> tag you advertise that properties should be interpreted as ListGrid properties. By specifying constructor you tell Smart GWT what class to create().

Component Schema

Instead of using the constructor and xsi:type attributes for custom components and custom properties, you can create a ComponentSchema that describes the custom component. Declaring a component schema allows you to use your component just like the built-in Smart GWT components, and also allows your component to be used within VisualBuilder.