Canvas > Using Relative Facilities in Canvas
Using Relative Facilities in Canvas
Relative Facilities are a powerful way to present data on your Canvas screens. For any given facility you can configure a relationship or syntax to define a path to another facility in your CygNet environment. You can combine data from facilities in multiple Facility services into a single relative facility definition. Relative facilities can also be used to associate a facility in a hierarchy with a closely related facility that is not in the same hierarchy. For example, you could use relative facilities to associate a well facility that is in a hierarchy with a meter facility that is not, so you can build a screen to show data from other facilities without having to hard-code the objects on a screen.
Before you configure relative facilities, be sure that you understand your data model, including the facility types in it, how its facilities are organized, what attributes are associated with the facilities, any ordinal relationships, the types of data points (UDCs) that belong to each facility type, and so on. Based on your data model's organization and components, a relative facility definition provides the rules by which a specific value resolves to a single, terminal relative facility. These rules are filters and paths that apply logic to attributes to resolve to the terminal relative facility. Relative facility resolution returns a facility tag rather than a facility ID.
Canvas controls can be configured to be aware of how data in your site is related and which facility attributes a facility should reference with respect to associated data points. For example, you might have a gas meter that links to a well. You can configure a chart to be associated with a well but set a series in the chart to display a point associated with the related gas meter.
These settings are saved in XML format as part of the global settings file (.gsf) for your Canvas application and applied to all instances of Canvas.
Configure Relative Facilities
Relative facility definitions are configured in the Settings section of the Canvas Backstage view.
All Canvas controls that support point configuration allow the setting of a Relative link when specifying a facility tag to use for the control.
- See the Properties topic for each control. The following table lists the relevant properties that can be configured for each control:
|
Resolve to a relative facility
|
The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed.
See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links.
|
|
Relative link
|
The Relative link property specifies a list of all available relative facility paths. Click  to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.
|
|
Order in type
|
The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box.
|
Design Screens to use Relative Facilities
Some planning is required to implement controls and design screens that resolve to facilities and relative facilities in the desired way.
- See Design Considerations for more information about resolving facilities when using Order in type and how to avoid configuring facilities with multiple parents.
API Integration
The CygNet .NET API includes a CygNet.API.Facilities.Relative namespace, which contains methods and properties required to configure and resolve relative facilities via script.
Facility Resolution
CygNet Studio allows the configuration of relative facilities in its CygNet-aware tools via the [ReferenceFacility] property. However, reference facilities only support a single level of resolution, whereas Canvas allows for multi-level resolution of relative facilities via the CygNet .NET API.
In CygNet Studio, you must configure a screen object to the point level to resolve a reference facility, even if you want to only show facility attributes. For example, in order to have a text box object show a facility description, you need to configure the UDC of the text box for facility attributes to work. While not necessarily related to reference facility configuration, it's important to know that you cannot show facility attributes in a Studio object unless you have a UDC defined for the object. In Studio any facility resolution is done at the point level.
In Canvas, it is possible to configure objects to show facility attributes without the need to configure the UDC. The relative facility methods in the CygNet .NET API do not require the UDC; they just require relative facility definitions, relative facility name, and the source facility tag. In Canvas the resolution is done at the facility level, rather than at the point level.
In this section
This section describes using relative facilities in Canvas and includes the following topics:
