For advanced users it is possible build what we call composite components. Just like xaps are built with dataflow, each component has its own internal dataflow where it can hold its own set of components and connections. This dataflow is only visible from within the component. A component author can create a single component which looks like any other component as far as the xap builder s concerned, while under the hood, it is actually a combination of multiple other components managed by its internal dataflow. This is analogous to encapsulating complex logic in a class or a module in programming. 


This article covers the API for creating these composite components.




This API is used to manipulate the internal dataflow of the component. In the internal dataflow, components are identified by a unique component path. In general, the component path can be any string as long as it is unique within the same dataflow layer. There are a few special rules:

  • The null value (not a null string) is a special path used in some methods, such as addConnection(). It refers to the enclosing component itself.
  • If the component is a child of a group, then it needs to be prefixed by its parent group's path (see the Group section below).

 

this.api.dataflow
  .addComponent("myTextBox", "e287abe0-fc7a-11e5-83a4-b571d99c18b5")
  .addComponent("myView", "77ecd2b0-ea5f-11e5-aafd-bbb0c7508c91")

  // Connect myTextBox:onChange -> myView:setValue
  .addConnection("myTextBox", "onChange", "myView", "setValue")

  // Set input myTextBox:setValue = "Hello"
  .sendInEvent("myTextBox", "setValue", "Hello")  // Add a new port to the enclosing component.  .addPort("output", {    name: "OnTextChange",    valueType: "string"  })  .addConnection("myTextBox", "onChange", null, "onTextChange"); 

 

addComponent          this.api.dataflow.addComponent( compPath, uuid )

Adds a component in the internal dataflow. This function takes two arguments, compPath and uuid. The first argument, compPath, represents a unique component path, and uuid represents a component class unique id. 


removeComponent          this.api.dataflow.removeComponent( compPath )

Removes a component from the internal dataflow. This function takes one argument, compPath. This argument, compPath, represents a unique component path.

 

sendInEvent           this.api.dataflow.sendInEvent( compPath, inputName, value )

Sends a value to the input of a component. This function requires three arguments, compPath, inputName, and value. The first argument, compPath, must be a string, and it represents the component receiving the input. The next argument, inputName, must be a string, and it represents the name of the receiving input. The final argument, value, is the value being sent.

 

addConnection          this.api.dataflow.addConnection( outPath, outputName, inPath, inputName )

Adds a connection between two components. This function requires four arguments: outPath, outputName, inPath and inputName. The first and third arguments, outPath and inPath, can be either a string value or null. These two arguments represent the source component and the destination component, where null would indicate the enclosing component. The arguments, outputName and inputName, represent the output on the source component and the input on the destination component. These arguments require string values.


NOTE: The components need to exist before they are connected. 


removeConnection          this.api.dataflow.removeConnection( outPath, outputName,inPath, inputName )

Removes a connection between two components. This function requires four arguments: outPath, outputName, inPath and inputName. The first and third arguments, outPath and inPath, can be either a string value or null. These two arguments represent the source component and the destination component, where null would indicate the enclosing component. The arguments, outputName and inputName, represent the output on the source component and the input on the destination component. These arguments require string values.


NOTE: The components need to exist before they are connected. 

 

addPort          this.api.dataflow.addPort( type, spec )

Adds a new port to the enclosing component. This function takes two arguments, type and spec. The first arguments must be a string and should be either input or output. The spec argument must be an object representing the spec for the new port.

 

removePort         this.api.dataflow.removePort( type, name )

Removes a port from the enclosing component. This function takes two arguments, type and name. The first arguments must be a string and should be either input or output. The name argument must be a string matching the name of the port that is being removed.

 

Grouping in the dataflow


A group is yet another dataflow within the internal dataflow of the component. A typical use of this is encapsulating complex dataflow logic dynamically. Wrapping the dataflow in a component is 

one way to encapsulate complexity as mentioned above, but if this internal dataflow itself is complicated, then a component author may want to further split it into smaller internal encapsulations, but without having to create new components for this purpose. Instead, one would want to be able to create encapsulations on the fly, just for internal use in that component. A group is useful here. A group is identified by its group path, which is a unique string like the component path. A child component of a group is identified by prefixing the child's path with the parent group's path. For instance, if the group path is myGroup, then a child component in this group must have a path of the form myGroup.<compPath>.

 

this.api.dataflow  // create group
  .addGroup("myGroup")
  .addPort("myGroup", "input", {
    name: "setText",
    valueType: "string"
  })

  // add child
  .addComponent("myGroup.myView", "e287abe0-fc7a-11e5-83a4-b571d99c18b5")
  // connect myGroup:setText -> myGroup.myView:setValue
  .addParentToChildConnection("setText", "myGroup.myView", "setValue")   // use group  .sendInEvent("myGroup", "setText", "Hello");

 

 

addGroup          this.api.dataflow.addGroup( groupPath )

Adds a group. This function takes one argument for the path to the group that is being added.


removeGroup          this.api.dataflow.removeGroup( groupPath )

Removes a group. This function takes one argument for the path to the group that is being removed.

 

addGroupPort          this.api.dataflow.addGroupPort( groupPath, type, spec )

Adds a port to a group. This function takes three arguments. The first argument, groupPath, must be a string representing the group that receive the new port. The next argument, type, should be a string of either 'input' or 'output'. The last argument should be an object representing the new port's spec.

 

removeGroupPort          this.api.dataflow.removeGroupPort( groupPath, type, name )

Removes a port from a group. This function takes three arguments: groupPath, type and name. The first argument, groupPath, must be a string representing the path to the group that is having the port removed. The next argument, type, should be a string of either input or output. The final argument, name, should be a string matching the name of the port that should be removed.

 

addParentToChildConnection          this.api.dataflow.addParentToChildConnection( groupInputName, childCompPath, inputName )

Connects a group's input to a child component's input. This component takes three arguments: groupInputName, childCompPath, and inputName. The first argument, groupInputName, must be a string representing the group's input to connect from. The next argument, childCompPath, must be a string value for the child component to connect to. The last argument, inputName, must be a string representing the child component's input to connect to.

 

addChildToParentConnection           this.api.dataflow.addChildToParentConnection(childCompPath, outputName, groupOutputName)

Connects a child component's output to its parent group's output. This component takes three arguments: childCompPath, childCompPath, and inputName. The first argument, childCompPath, must be a string value for the child component to connect from. The next argument, outputName, must be a string representing the child component's output to connect from. The last argument, groupOutputName, must be a string representing the group's output to connect to.