Velo Tutorial: Adding Collection Data Search Functionality

Visit the Velo by Wix website to onboard and continue learning.

This article assumes some understanding of database collections and datasets and how they are used in Velo. 

With Velo you can add a database collection to your site and display the data in many ways. Visitors to your site can also search that data. You can add this search functionality to your site by adding user input elements to the page and then adding some code to enable the search.

There are different ways you can let your visitors search your collection. This article covers the following options:

  • Adding an input field where visitors enter a search string.
  • Adding a dropdown list where visitors select a value from a list.

While the results can be displayed however you want them to appear on the page, in this article we'll cover how to display the data in a table. At the end of the tutorial we'll also cover how to optionally collapse the table until you are ready to display the results.

Search Using an Input Element

Let's say you have a list of recipes in your collection and you want users to be able to search for them by entering their name in a user input element. Once the visitor clicks a search button, the results are displayed in a table on the same page. To do this, you add to your page an input element where the user enters a search term, a button that enables the search, and a table to display the results. Then you add code to make the table only display data that matches the user input. In this example, the table is not connected to a dataset, so code is needed to set up the table columns to match the data structure.

1. Add the input, button, and table elements to the page

  1. Add an input box, a button, and a table to your page. 

    You can customize them as you like. For example, you could change the text of the button to "Search" and configure the placeholder text of the input box to read "Search recipes."

  2. Consider changing the IDs of each element that you just added to make them meaningful. 

2. Add the code for inputting a search string

Now configure the search button so that when it's clicked, the search is performed on the collection based on what a user entered into the input box. Then you need to have those results populate the table you added.

  1. Add the import statement for the Wix Data API to the top of your code:

    Copy
    1
    import wixData from "wix-data";

  2. Add an onClick event to the button. The following code is added to your page.

    Copy
    1
    export function searchButton_click(event) {
    2
    //Add your code for this event here: 
    3
    }

  3. Replace existing text with the following code:

    Copy
    1
    // Runs a query on the "recipes" collection
    2
    wixData.query("recipes") 
    3
      // Query the collection for any items whose "Name" field contains  
    4
      // the value the user entered in the input element
    5
      .contains("name", $w("#searchBox").value)
    6
      .find()  // Run the query
    7
      .then(res => {   
    8
        // Set the table data to be the results of the query     
    9
        $w("#resultsTable").rows = res.items; 
    10
      });

3. Define the table columns

Because your table isn't connected to a dataset, you need to define the columns using the API for tables. You do this by defining a JSON object that lists the properties for each column and their values. The code is placed in the onReady function and looks like this:

Copy
1
$w.onReady(function () {    
2
    $w("#resultsTable").columns = [
3
      {
4
        "id": "col1",       // ID of the column for code purposes
5
        // The field ID in the collection whose data this column displays  
6
        "dataPath": "field1", 
7
        "label": "Field 1", // The column header
8
        "width": 100,       // Column width
9
        "type": "string",   // Data type for the column
10
        // Path for the column if it contains a link  
11
        "linkPath": "link-field-or-property"  
12
      },
13
      {
14
        "id": "col2",
15
        "dataPath": "field2",
16
        "label": "Field 2",
17
        "visible": true,
18
        "type": "image",
19
        "linkPath": "link-field-or-property"
20
      } //,
21
      // more column objects here if necessary
22
      // ...
23
      // ...  
24
    }];
25
});

For example, the column definitions of a table that shows the results of a search on your recipes collection might look like this:

Copy
1
$w.onReady(function () {
2
 $w("#resultsTable").columns = [{
3
  "id": "col1",
4
  "dataPath": "title",
5
  "label": "Recipe",
6
  "type": "string",
7
 }, {
8
  "id": "col2",
9
  "dataPath": "course",
10
  "label": "Course",
11
  "type": "string",
12
 }, {
13
  "id": "col3",
14
  "dataPath": "meal",
15
  "label": "Meal",
16
  "type": "string",
17
 }];
18
});

You can copy all this code directly into your page code. You need to replace the following element IDs and the collection name with those in your site. Just hover over the element to see its ID.

  • wixData.query("recipes") - Replace recipes with the name of your collection.
  • .contains("name", $w("#searchBox") - Replace name with the field ID of the field in the collection that is being searched. Replace searchBox with the element ID of your input box where visitors enter the string to search.
  • $w("#resultsTable") - Replace resultsTable with the element ID of your table that displays the search results.
  • "dataPath value" - Replace with the field IDs in your collection.

You can now preview your page and check that everything works as expected. 

Filter Using a Dropdown Element

Now let's say you want users to select a value from a dropdown list of courses so they can filter your recipes. The list of courses is already in your collection. First, we add the dropdown and connect it to the collection via a dataset to populate the options directly from the collection. Then we add a table to display the selection, and finally we write the code. 

Tip You can also filter displayed data based on a user selection in a dropdown directly in the editor, without code.

1. Add the dropdown and table elements to the page

  1. Add a dropdown list element and a dataset to your page. Make sure the dataset is set to Read mode or Read & Write mode.
  2. In the Connect Dropdown panel, select Filter content.
  3. Add a table element to your page.

2. Add the code for the dropdown selection to filter the collection

Now add the code so that the user's selection in the dropdown is used to filter your collection.

  1. Add the import statement for the Wix Data API to the top of your code:

    Copy
    1
    import wixData from "wix-data";

  2. Add an onChange event to the dropdown list. The following code is added to your page.

    Copy
    1
    export function searchList_change(event) {
    2
    //Add your code for this event here: 
    3
    }

  3. Replace existing text with the following code:

    Copy
    1
    // Runs a query on the "recipes" collection
    2
    wixData.query("recipes") 
    3
      // Query the collection for any items whose "Name" field contains  
    4
      // the value the user selected in the dropdown
    5
      .contains("course", $w("#myDropdown").value)
    6
      .find()  // Run the query
    7
      .then(res => {   
    8
        // Set the table data to be the results of the query
    9
        $w("#resultsTable").rows = res.items; 
    10
      });

3. Define the table columns

Follow the instructions in the previous example to define the results table. Then preview your page and check that everything is working as expected.

Filter Dropdown Options Distinctly

In the last step, we displayed all recipes for a selected course in a table on the page. We might have many recipes for each course in our collection, so our table displays the course multiple times, once for each recipe. 

We do not, however, want to display duplicate course values in the dropdown's options. We want each dropdown option to be distinct from the others. 

First, we modify the dropdown we already added by disconnecting it from the collection in the editor. We then add code to populate the options directly from the collection.  

1. Disconnect the dropdown from the collection

We will populate the dropdown from the collection but with code. So let's disconnect it from the collection in the editor.

  1. Select the dropdown list element on your page. 
  2. In the Connect Dropdown panel, under the Choose a dataset section, select the option Not connected. 

2. Add code to populate the dropdown with distinct options

We now add a function to populate our dropdown using distinct function. We call this function loadOptions().

The distinct() function queries the collection and returns field values that do not contain duplicates.

To populate the dropdown, the distinct query results have to be formatted as an array of strings in a certain format. loadOptions() calls the buildOptions() function for this purpose.

This example also demonstrates how to insert an extra All Courses option to our dropdown so users can reset the filter from the dropdown.

You can copy the following code for these functions directly into your page code. You need to replace the element IDs and the collection name with those in your site.

Copy
1
function loadOptions() {
2
    
3
 // Run a query that returns distinct items in the collection
4
 wixData.query("recipes")
5


6
   // Set the course as the field that must be distinct
7
   .distinct("course")
8
 
9
   .then(results => {
10


11
     // Call another function to reformat the distinct items
12
     // the way the dropdown element expects
13
     let distinctList = buildOptions(results.items);
14
   
15
     // Use `unshift()` to add another dropdown option at 
16
     // the beginning of the array, in the correct format
17
     distinctList.unshift({ "value": '', "label": 'All Continents'    });
18
   
19
   // Set the options of the dropdown 
20
   $w("#myDropdown").options = distinctList;
21
     
22
  });
23
    
24
}

Let's now code the loadOptions() function. This function takes each distinct item from the collection and reformats the option in the format expected by the dropdown:

{ "label": "uniqueTitle", "value": "uniqueTitle" }

Copy
1
function buildOptions(dropdownItems) {    
2
  return items.map(currentItem => {
3
     return { 
4
       "label": "currentItem", 
5
       "value": "currentItem" 
6
     };
7
  });
8
}

Now call the loadOptions() function in the $w.onReady(), to load the options into the dropdown.

Replace resultsTable with the ID of your table.

Copy
1
$w.onReady(() => {
2
    
3
  loadOptions();
4
    
5
  $w("#resultsTable").columns = [{
6
        ...
7
        ...
8
        ...
9
      
10
    }];
11
     
12
      
13
});

Preview your page and check that everything works as expected. 

Optionally Collapse the Table on Load

The way both searches are set up, an empty table appears when the page loads. You can collapse the table so that it does not take up any space on the page and configure it to expand only after the search is performed.

  1. In the Properties & Events panel for the table, select Collapsed on load.
  2. In the code you added for the search, right below where you instructed the table to be populated with the results of the query on the data collection, add this line to expand the table. 
Copy
1
$w("#resultsTable").expand();

Replace resultsTable with the ID of your table.

For example, the code for performing the search with a dropdown would look like this for a table whose index key is resultsTable:

Copy
1
wixData.query("recipes")
2
    .contains("name", $w("#searchList").value)   
3
    .find()
4
    .then(res => {   
5
      $w("#resultsTable").rows = res.items; 
6
      $w("#resultsTable").expand();
7
    });
8
}

API List

The following APIs are used in the code in this article. To learn more, see the API Reference.

wix-data

Was this helpful?
Yes
No