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.