Configuring a Search Box

Not supported by TWC

The Search Box has numerous properties available for configuration in the Properties pane. The following topic describes a basic workflow for configuring this control. The specific appearance and functionality of the object you create depends on your needs and implementation of the control's properties, each of which is described below.

  1. In design mode, create a new Canvas screen or object.
  2. Find the Search Box on the Toolbox pane and drag a desired object to your screen.

  3. Use the Settings pane to apply common settings (sizing, grouping, alignment, etc.) to this object (and others) on your screen.

  4. Optionally, use the Name property to rename the object if you plan to reference it in another screen or control, or plan to script this control.
  5. Configure the Style property.
  1. Style —

    Not supported by TWC The Style property defines the style sheet applied to an object on a screen. A style sheet consists of a predetermined list of properties and property values configured for a particular control type.

    • Click Down arrow to reveal a drop-down menu of predetermined styles configured for the selected control.
    • Select a desired style and its properties will be applied to the control.
    • Alternately, you can create a new style based on other property values configured for the control.
    • Or you can select <None> to remove subscription to any style.

    Styles are created in two ways:

    • In the control's Properties pane. Click Add a new style (Add a new style based on this control) next to the Style property, after you have configured property values in the Properties pane. See Add a new style based on a control for more information.
    • In the Canvas Settings in the Backstage view. The default style for any control is configured in the Backstage view. See Manage style sheets in the Backstage view for more information.

    Tip: You can also change a control's Style on the Controls view of the Screen pane.

  1. Configure the Location properties. See To configure location, size, resizing, layer, and visibility properties below.
  2. Configure the Script property.
  1. Include in script —

    Scripting is not supported by TWC The Include in script check box indicates that the control will appear in the objects collection of the screen (if scripting is enabled). To optimize performance, best practice dictates that you only include the controls you need to manipulate via script. Other controls should be excluded. When you add an event to a control, it will be automatically added to script and the Include in script property (and the In Script check box on the Controls view) will be set to True.

    Tip: You can also change the Include in Script setting on the Controls view of the Screen pane.

  1. Configure the Search properties. There are a variety of searches you can configure with the Search Box, see the following depending on the type of search:

Facility Search

Custom Search

  1. Configure the Generic properties:
  1. String — Not supported by TWC The String property specifies a generic string property that can be used when scripting this control. Type a string and reference it in your script as necessary.
  2. Yes/No — Not supported by TWC The Yes/No property specifies a generic Boolean yes/no property that can be used when scripting this control. Click the check box to enable the property and reference it in your script as necessary.
  1. Configure other search properties.
  2. Save the screen.
  3. Run the screen to test your configuration.
  1. Find the Location properties and configure the size and location properties for the control:
  1. Height —

    The Height property specifies the height of the control (or screen).

    Tip: You can also change the height of a control using the Settings pane (click on the Settings icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

  2. Horizontal resize mode —

    The Horizontal resize mode property specifies whether and how the control dynamically moves or resizes horizontally when the screen is resized in run mode. Options include:

    • None — No resizing occurs.
    • Shift — The object will shift horizontally.
    • Expand — The object will expand or shrink horizontally the same number of pixels as the screen.
    • Proportional — The object expands or shrinks proportionally to the screen.

    The default value is None.

  3. Layer —

    Not supported by TWC The Layer property specifies the name of the layer to which this object is assigned. Layers can be used to show, hide, and edit multiple controls on one layer without affecting controls on another layer.

    • Type the name of the layer into the Layer field (the name can be a previously created layer or a new layer).
    • All layers are listed on the Layers pane, where you can manage the layers for the screen in design mode and run mode.

    Tip: You can also edit a control's Layer on the Controls view of the Screen pane.

    Note: Layer visibility can be controlled at runtime via the AddLayer, HideLayer, SetLayerVisibility, and ShowLayer methods on the Screen object.

  4. Lock —

    Not supported by TWC The Lock property indicates whether the control is locked to the current position. A locked control cannot be moved via click and drag, or nudged with the arrow keys, or resized.

    Tip: You can also toggle the lock setting of a control using the Settings pane (click on the Settings icon (Settings) to the right of the control in design mode).

  5. Vertical resize mode —

    The Vertical resize mode property specifies whether and how the control dynamically moves or resizes vertically when the screen is resized in run mode. Options include:

    • None — No resizing occurs.
    • Shift — The object will shift vertically.
    • Expand — The object will expand or shrink vertically the same number of pixels as the screen.
    • Proportional — The object expands or shrinks proportionally to the screen.

    The default value is None.

  6. Visible —

    Not supported by TWC The Visible check box indicates whether the control is visible in run mode.

    Tip: You can also change a control's Visible setting on the Controls view of the Screen pane.

  7. Width —

    The Width property specifies the width of the control (or screen).

    Tip: You can also change the width of a control using the Settings pane (click on the Settings icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

  8. X —

    The X property specifies the location of the control along the horizontal axis. Use the up, down, left, and right arrow keys to nudge a control by 1 pixel. Arrow moves a control by 1 pixel. Ctrl+Arrow moves a control by 10 pixels. Ctrl+Shift+Arrow moves a control by 100 pixels.

    Tip: You can also change the location of the control using the Settings pane; click on the Settings icon (Settings) to the right of the control in design mode.

  9. Y —

    The Y property specifies the location of the control along the vertical axis. Use the up, down, left, and right arrow keys to nudge a control by 1 pixel. Arrow moves a control by 1 pixel. Ctrl+Arrow moves a control by 10 pixels. Ctrl+Shift+Arrow moves a control by 100 pixels.

    Tip: You can also change the location of the control using the Settings pane; click on the Settings icon (Settings) to the right of the control in design mode.

  10. Z index —

    The Z index property is used to determine the order in which controls are layered on top of each other. Controls with higher values will draw on top of those with lower values. The newest control added to a screen will always have the highest value and will be the top layer. Two or more controls can be on the same index (layer).

    Tip: You can also change the Z index of a control using the Settings pane (click on the Settings icon (Settings) to the right of the control in design mode) or on the Controls view of the Screen pane.

  1. Configure any other Search Box properties.
  2. Save the screen.
  3. Run the screen to test your configuration.

When a full or partial facility name is entered, the Search Box will query all facilities in the provided service's associated Facility service and return any matching facility names. Select a facility from the search results and the Search Box will function as a facility sender and send the facility to any controls on the screen configured to receive it. This type of search does not require any scripting.

  1. Add a Search Box to your screen and make a note of the control's Name.
  2. Configure the following properties in the Properties pane:
  1. Enabled — Click to enable. The Enabled check box indicates whether the control is enabled. The default value is True. When set to False, the control is visible in run mode, but grayed out and disabled from use.
  2. Facility filter — Add a filter if you want to limit the search results.

    Use the Facility filter property to limit the data presented in the control to any CygNet facility attribute set up for your CygNet installation. A search will be executed against the facilities that are described by this filter. Click Open dialog box to open the Facility Filter dialog box where you can create a custom filter rule. The filter rule is displayed in the property label; you do need to open the Facility Filter dialog box to edit the rule.

  3. Facility attribute: Primary — The Facility attribute: Primary property specifies the facility attribute that will be displayed as text in the left position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Description.
  4. Facility attribute: Secondary — The Facility attribute: Secondary property specifies the facility attribute that will be displayed as text in the right position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Site.Service.

    5. Search Box Results

    Search Results

  1. Properties to search —

    Use the Properties to Search property to select the facility properties (attributes) that will be searched in the Search Box. Click Open dialog box to open the Properties to Search dialog box and select the facility attributes to use. Searching many attributes and searching non-indexed attributes may negatively impact performance. The default attributes are Facility Description and Facility ID.

  2. Search facilities — Click to enable. The Search facilities check box indicates whether to search for facilities based on facility attributes, filter settings, and SiteService. The default value is True. This property works in conjunction with the Facility filter, Properties to search, and SiteService properties.
  3. Selection action — Select the Facility sender option. The control acts as a facility sender and sends the selected facility to any controls configured to receive it. This only works if the selected result includes a facility.
  4. SiteServices — Select the desired service(s). The SiteServices property specifies the current value or facility service(s) to search. Resolution will be against all facilities in the provided service's associated facility service. Options include:
    • Source — Options include <Self> or Screen.
      • <Self> — Select <Self> to explicitly configure the SiteService for this control or screen element. A SiteService selector is displayed:
        • SiteService — The SiteServices property specifies the service(s) for which the search box is to display data. Click Open dialog box to select a service(s) using the Select Services dialog box.
      • Screen — Select Screen to receive the SiteService from the screen for this control or screen element. By default, the sender is the Screen control if no other senders have been configured.
  5. Use grayscale icons —

    The Use grayscale icons check box indicates whether to display grayscale versions of the default themed icons. Facilities are designated with configurable icons:

    Icon typeFacility - Diamond
    DefaultFacility icon default
    Grayscale darkFacility icon grayscale dark
    Grayscale lightFacility icon grayscale light

    Grayscale icons are available for use with the dark or light color theme. See themes for more information.

  1. Add other controls to your screen that will receive the facility from the Search Box.
  2. On the receiving control(s) configure the source of the facility, and any other necessary properties:
  1. Find the Point configuration or CygNet configuration property depending on the control.
  2. In the Facility Source drop-down menu, select the Name of the Search Box that is sending the facility.

    3. Search Box - Facility Sender

    Facility Receiver

  1. Configure the relative facility properties (if necessary), the UDC, and other required properties.
  1. Configure any other Search Box properties.
  2. Save the screen.
  3. Run the screen to test your configuration.

Search Box - Facility Sender

A Search Box sending ASH_WL facility

to a Detail control

When a full or partial facility name is entered, the Search Box will query all facilities in the provided service's associated Facility service and return any matching facility names. Select a facility from the search results and the Search Box will navigate to the selected facility's associated screen or the selected screen.

The navigation mode for the targeted screen is determined by the Facility navigation mode setting on the screen displaying the Search Box. There are six facility navigation modes for linking to associated screens; see Navigation by Facility for more information about navigating from a Search Box results. Most of the navigation modes do not required any scripting, although the Script event option does.

  1. Create the associated Canvas screen to link to from the search results and save it to an APPS or BSS folder.
  2. Add a Search Box to your screen.
  3. Configure the following properties in the Properties pane:
  1. Enabled — Click to enable. The Enabled check box indicates whether the control is enabled. The default value is True. When set to False, the control is visible in run mode, but grayed out and disabled from use.
  2. Facility filter — Add a filter if you want to limit the search results.

    Use the Facility filter property to limit the data presented in the control to any CygNet facility attribute set up for your CygNet installation. A search will be executed against the facilities that are described by this filter. Click Open dialog box to open the Facility Filter dialog box where you can create a custom filter rule. The filter rule is displayed in the property label; you do need to open the Facility Filter dialog box to edit the rule.

  3. Facility attribute: Primary — The Facility attribute: Primary property specifies the facility attribute that will be displayed as text in the left position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Description.
  4. Facility attribute: Secondary — The Facility attribute: Secondary property specifies the facility attribute that will be displayed as text in the right position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Site.Service.

    5. Search Box Results

    Search Results

  5. Properties to search —

    Use the Properties to Search property to select the facility properties (attributes) that will be searched in the Search Box. Click Open dialog box to open the Properties to Search dialog box and select the facility attributes to use. Searching many attributes and searching non-indexed attributes may negatively impact performance. The default attributes are Facility Description and Facility ID.

  6. Search facilities — Click to enable. The Search facilities check box indicates whether to search for facilities based on facility attributes, filter settings, and SiteService. The default value is True. This property works in conjunction with the Facility filter, Properties to search, and SiteService properties.
  7. Selection action — Select the Navigate option. The control will navigate to the selected facility's associated screen or the selected screen. The navigation mode is determined by the Facility navigation mode property setting on the screen displaying the control. See Navigation by Facility for more information.
  8. SiteServices — Select the desired service(s). The SiteServices property specifies the service(s) for which the search box is to display data. Click Open dialog box to select a service(s) using the Select Services dialog box.
    • Source — Options include <Self> or Screen.
      • <Self> — Select <Self> to explicitly configure the SiteService for this control or screen element. A SiteService selector is displayed:
        • SiteService — The SiteServices property specifies the service(s) for which the search box is to display data. Click Open dialog box to select a service(s) using the Select Services dialog box.
      • Screen — Select Screen to receive the SiteService from the screen for this control or screen element. By default, the sender is the Screen control if no other senders have been configured.
  9. Use grayscale icons —

    The Use grayscale icons check box indicates whether to display grayscale versions of the default themed icons. Facilities are designated with configurable icons:

    Icon typeFacility - Diamond
    DefaultFacility icon default
    Grayscale darkFacility icon grayscale dark
    Grayscale lightFacility icon grayscale light

    Grayscale icons are available for use with the dark or light color theme. See themes for more information.

  1. On the screen where the Search Box is located, find the Facility navigation mode property and select the desired mode for linking to the associated screen.
  2. Configure the other facility navigation settings, as described in the Navigation by Facility topic:
  1. Configure any other Search Box properties.
  2. Save the screen.
  3. Run the screen to test your configuration.

Search Box - Facility Navigation

A Search Box sending ASH_WL facility to an associated screen

via the Hyperlink - Open navigation mode

When a full or partial facility name is entered, the Search Box will query all facilities in the provided service's associated Facility service and return any matching facility names. Select a facility from the search results and the Search Box will execute a script event to perform some other action.

  1. Add a Search Box to your screen.
  2. Configure the following properties in the Properties pane:
  1. Enabled — Click to enable. The Enabled check box indicates whether the control is enabled. The default value is True. When set to False, the control is visible in run mode, but grayed out and disabled from use.
  2. Facility filter — Add a filter if you want to limit the search results.

    Use the Facility filter property to limit the data presented in the control to any CygNet facility attribute set up for your CygNet installation. A search will be executed against the facilities that are described by this filter. Click Open dialog box to open the Facility Filter dialog box where you can create a custom filter rule. The filter rule is displayed in the property label; you do need to open the Facility Filter dialog box to edit the rule.

  3. Facility attribute: Primary — The Facility attribute: Primary property specifies the facility attribute that will be displayed as text in the left position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Description.
  4. Facility attribute: Secondary — The Facility attribute: Secondary property specifies the facility attribute that will be displayed as text in the right position of a search result. Click Down arrow to reveal a drop-down menu of all available facility attributes. Select an attribute from the list. The default attribute is Facility Site.Service.

    5. Search Box Results

    Search Results
  5. Properties to search —

    Use the Properties to Search property to select the facility properties (attributes) that will be searched in the Search Box. Click Open dialog box to open the Properties to Search dialog box and select the facility attributes to use. Searching many attributes and searching non-indexed attributes may negatively impact performance. The default attributes are Facility Description and Facility ID.

  6. Search facilities — Click to enable. The Search facilities check box indicates whether to search for facilities based on facility attributes, filter settings, and SiteService. The default value is True. This property works in conjunction with the Facility filter, Properties to search, and SiteService properties.
  7. Selection action — Select the Script option.

    Executes a script event (Search Results Selected) when selecting a facility or custom item from the search results.

    Notes for the Search Box:

    • If you are setting up a facility search, and want to script the selection action, you also need to enable the Search facilities check box.
    • If you are setting up a custom search to query some other object, for example, a SQL database, a .csv file, even a website, you also need to enable the Search custom check box.
    • See Scripting Custom Searches for more information.
  8. SiteServices — Select the desired service(s). The SiteServices property specifies the service(s) for which the search box is to display data. Click Open dialog box to select a service(s) using the Select Services dialog box.
    • Source — Options include <Self> or Screen.
      • <Self> — Select <Self> to explicitly configure the SiteService for this control or screen element. A SiteService selector is displayed:
        • SiteService — The SiteServices property specifies the service(s) for which the search box is to display data. Click Open dialog box to select a service(s) using the Select Services dialog box.
      • Screen — Select Screen to receive the SiteService from the screen for this control or screen element. By default, the sender is the Screen control if no other senders have been configured.
  9. Use grayscale icons —

    The Use grayscale icons check box indicates whether to display grayscale versions of the default themed icons. Facilities are designated with configurable icons:

    Icon typeFacility - Diamond
    DefaultFacility icon default
    Grayscale darkFacility icon grayscale dark
    Grayscale lightFacility icon grayscale light

    Grayscale icons are available for use with the dark or light color theme. See themes for more information.

  1. On the Events pane enable the Search Result Selected event.
  2. On the Script view write appropriate script to fire an event for the selected facility search result.
  3. Configure any other Search Box properties.
  4. Save the screen.
  5. Run the screen to test your configuration.

Custom searching is supported via script to allow you to query whatever you want, for example, a SQL database, a .csv file, even a website. When a full or partial search term is entered in the Search Box, a custom script method is fired to search a specified item or object, and any matching terms are returned in a search results list. Further custom actions can be executed when selecting a search result.

  1. Add a Search Box to your screen.
  2. Configure the following properties in the Properties pane:
  1. Include in script —

    Scripting is not supported by TWC The Include in script check box indicates that the control will appear in the objects collection of the screen (if scripting is enabled). To optimize performance, best practice dictates that you only include the controls you need to manipulate via script. Other controls should be excluded. When you add an event to a control, it will be automatically added to script and the Include in script property (and the In Script check box on the Controls view) will be set to True.

    Tip: You can also change the Include in Script setting on the Controls view of the Screen pane.

    Click to enable.
  2. Enabled — Click to enable. The Enabled check box indicates whether the control is enabled. The default value is True. When set to False, the control is visible in run mode, but grayed out and disabled from use.
  3. Search custom — Click to enable.

    The Search custom check box indicates whether a custom search will be performed.

    This property invokes the CustomSearch script property, a delegate that references a custom search method, when a user searches for a string.

    Example

    Copy
    CustomSearch property
    private void Search2_Initialize(object sender, EventArgs args)
    {
        Objects.Search2.CustomSearch = DoCustomSearch;
        ParseCsvFile(@"C:\Temp\List.csv");
    }

    See Scripting Custom Searches for more information about this property.

  4. Selection action — Select the Script option.

    Executes a script event (Search Results Selected) when selecting a facility or custom item from the search results.

    Notes for the Search Box:

    • If you are setting up a facility search, and want to script the selection action, you also need to enable the Search facilities check box.
    • If you are setting up a custom search to query some other object, for example, a SQL database, a .csv file, even a website, you also need to enable the Search custom check box.
    • See Scripting Custom Searches for more information.
  1. On the Events pane enable the Initialize and SearchResultSelected events.
  2. On the Script view write appropriate script to define the custom search method, perform the custom search, return the search results or error message, format the search results, and fire an event for the selected search result. See the script example sample code below.
  1. Configure any other Search Box properties.
  2. Save the screen.
  3. Run the screen to test your configuration.

Search Box - Custom Search

A Search Box scripted to search a .csv file.
Selecting the search results pops a message.

See Scripting Custom Searches using a Search Box for the full script example.