Customizing Connection Builders

You can write custom code for connection builders to specify the source and target classes for the connection, define the type of connection to be made, and take other actions associated with the creation of a connection.

There are four checkboxes in the user interface that define different types of customization of connection builders:

• the Custom accept check box on a source or target role directive

• the Custom connect check box on a source or target role directive

• the Uses custom connect check box on a connect directive

• the Is Custom property of the connection builder

Custom Code for Connection Builders

In each link connect directive, the Source role directives tab defines from what types you can drag. Similarly, the Target role directives tab defines to what types you can drag. For each type, you can further specify whether to allow the connection (for that link connect directive) by setting the Custom Accept flag and then supplying the extra code.

You can also customize what occurs when the connection is made. For example, you can customize just the case where the drag occurs to or from a particular class, all the cases that one link connect directive governs, or the whole FlowBuilder connection builder. For each of these options, you can set custom flags at the appropriate level. When you transform all templates and try to build the solution, error messages direct you to comments that are in the generated code. These comments identify what you must supply.

In the Components Diagram sample, the connection builder for the Connection domain relationship is customized to restrict the connections that can be made between ports. The following illustration shows that you can make connections only from OutPort elements to InPort elements, but you can nest components inside each other.

Connection Coming in to an OutPort from a Nested Component

Therefore, you might want to specify that a connection can come from a nested component to an OutPort. To specify such a connection, you set Uses Custom Accept on the InPort type as source role and the OutPort type as target role in the DSL Details window as shown in the following illustrations:

Link Connect Directive in DSL Explorer

Link Connect Directive in DSL Details Window

You must then provide methods in the ConnectionBuilder class:

  public partial class ConnectionBuilder
  {
    /// <summary>
    /// OK if this component has children
    /// </summary>
    private static bool CanAcceptInPortAsSource(InPort candidate)
    {
       return candidate.Component.Children.Count > 0;
    }

    /// <summary>
    /// Only if source is on parent of target.
    /// </summary>
    private static bool CanAcceptInPortAndInPortAsSourceAndTarget                (InPort sourceInPort, InPort targetInPort)
    {
      return sourceInPort.Component == targetInPort.Component.Parent;
    }
// And similar for OutPorts…

You can use similar code, for example, to prevent users from creating loops with parent-child links. These restrictions are considered ‘hard’ constraints because users cannot violate them at any time. You can also create ‘soft’ validation checks that users can bypass temporarily by creating invalid configurations that they cannot save.

Good Practice in Defining Connection Builders

You should define one connection builder to create different types of relationships only if they are conceptually related. In the task flow sample, you use the same builder to create flows between tasks and also between tasks and objects. However, it would be confusing to use the same builder to create relationships between comments and tasks.

If you define a connection builder for multiple types of relationships, you should ensure that it cannot match more than one type from the same pair of source and target objects. Otherwise, the results will be unpredictable.

You use custom code to apply ‘hard’ constraints, but you should consider whether users should be able to temporarily make invalid connections. If they should, you can modify the constraints so that connections are not validated until users try to save changes.

See Also

Other Resources

Models and Model Elements

Domain-Specific Language Tools Glossary

Change History

Date	History	Reason
July 2008	Rewrote and refactored project.	Content bug fix.