com.smartgwt.client.docs

Interface DataPath

public interface DataPath

String specifying a nested data field structure.

Each dataPath string is a slash-delimited set of field identifiers, for example "id1/id2/id3". DataPaths may be applied directly to a component, and/or to a databound component field specification. A datapath denotes a path to a nested field value in a hierarchical structure, giving developers the opportunity to easily view or edit nested data structures. Specifically:

• if the component is viewing or editing a record, the value for fields will be derived from a nested structure of records
• if the component is bound to a dataSource, field attributes may be picked up by following the dataPath to a field definition on another dataSource

Examples:
If a dynamicForm is defined with the following fields:

     [
       { name:"name" },
       { name:"street", dataPath:"address/street" }
     ]
  

If the "name" field is set to "Joe Smith" and the "street" field is set to "1221 High Street", when the values for this form are retrieved via a getValues() call they will return an object in the following format:

     {name:"Joe Smith", address:{street:"1221 High Street"}}
  

For databound components, dataPath also provides a way to pick up field attributes from nested dataSources. Given the following dataSource definitions:

   isc.DataSource.create({
       ID:"contacts",
       fields:[
           {name:"name"},
           {name:"email"},
           {name:"organization"},
           {name:"phone"},
           {name:"address", type:"Address"}
       ]
   });
  
   isc.DataSource.create({
       ID:"Address",
       fields:[
           {name:"street"},
           {name:"city"},
           {name:"state"},
           {name:"zip"}
       ]
   });
   

and a databound component bound to the 'contacts' dataSource, specifying a field with a dataPath of "address/street" would ensure the field attributes were derived from the "street" field of the 'Address' dataSource.

dataPaths are also cumulative. In other words if a component has a specified dataPath, the dataPath of any fields it contains will be appended to that component level path when accessing data. For example the following form:

  isc.DynamicForm.create({
      dataPath:"contact",
      fields:[
           {dataPath:"address/email"}
      ]
  });
  

Might be used to edit a data structure similar to this:

{contact:{name:'Ed Jones', address:{state:"CA", email:"ed@ed.jones.com"}}}

Nested canvases can also have dataPaths specified, which will similarly be combined. See the Canvas.dataPath attribute for more information and examples of this.