Scripting Custom Searches using a Search Box

The Canvas Search Box supports numerous actions on selected search results: facility sender, facility navigation, facility scripted, and custom searches. This topic describes how to script a custom search using the Search Box control.

• See To configure a Search Box as a facility sender
• See To configure a Search Box to navigate to another screen
• See To configure a Search Box to execute a scripted selection action

Custom Searches

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. Add a Search Box to your screen. Configure the following properties in the Properties pane: Include in script — 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. 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. 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 1 2 3 4 5 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. 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. On the Events pane enable the Initialize and SearchResultSelected events. 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. Configure any other Search Box properties. Save the screen. Run the screen to test your configuration.

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

Custom Search Example

The following code example shows how to query a .csv list of meeting attendees to find any results that match a Primary and Secondary value, as shown in the image above.

• The script defines the custom search method DoCustomSearch which is passed as an argument to the Objects.Search2.CustomSearch property.
• When a full or partial string is entered in the Search Box, the DoCustomSearch method is fired parsing the specified .csv file.
• The custom search results CustomSearchBoxResult are returned in a list, or if the search results are empty, an error message (No results found) is returned.
• When one of the search results is selected, a MessageBox is popped displaying the Primary value (Name).

Copy

Custom Search Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
namespace Screen
{
    public class Attendee
    {
        public string Name { get; set; }
        public string Company { get; set; }
        public string Title { get; set; }
    }
    public class ScreenClass
    {
        private List<Attendee> Attendees { get; set; } = new List<Attendee>();
        public bool DoCustomSearch(string query, out List<CustomSearchBoxResult> results, out string error)
        {
            error = string.Empty;
            results = new List<CustomSearchBoxResult>();
            var queryResults = Attendees.Where(x => x.Name.ToUpper().Contains(query.ToUpper()) ||
                x.Company.ToUpper().Contains(query.ToUpper()) ||
                x.Title.ToUpper().Contains(query.ToUpper()));
            foreach (var result in queryResults)
            {
                results.Add(new CustomSearchBoxResult() { Primary = result.Name, Secondary = result.Company });
            }
            return true;
        }
        private void ParseCsvFile(string path)
        {
            Attendees.Clear();
            using (TextFieldParser parser = new TextFieldParser(path))
            {
                parser.SetDelimiters(new string[] { "," });
                // Skip over header line.
                parser.ReadLine();
                while (!parser.EndOfData)
                {
                    string[] fields = parser.ReadFields();
                    Attendees.Add(new Attendee()
                    {
                        Name = fields[0] + " " + fields[1],
                        Company = fields[3],
                        Title = fields[4]
                    });
                }
            }
        }
         
        public static void Main()
        {
            ScreenClass c = new ScreenClass();
        }
        /// <summary>
        /// Constructor for screen. Used to hook-up event handlers and for any custom initialization code
        /// </summary>
        public ScreenClass()
        {
            // control event handler code goes here -- do not modify
            Objects.Search2.Initialize += new EventHandler(this.Search2_Initialize);
            Objects.Search2.SearchResultSelected += new EventHandler(this.Search2_SearchResultSelected);
            // add your custom initialization code here
        }
        #region Search2
        private void Search2_Initialize(object sender, EventArgs args)
        {
            Objects.Search2.CustomSearch = DoCustomSearch;
            ParseCsvFile(@"C:\Temp\RSVPs.csv");
        }
         
        private void Search2_SearchResultSelected(object sender, EventArgs args)
        {
            var searchResultArgs = args as Canvas.Controls.SearchBox.CanvasSearchBoxSearchResultSelectedEventArgs;
            MessageBox.Show(searchResultArgs.Result.Primary);
        }
        #endregion
    }
}