Search and Filter (Component REST)

Overview

When you add a new REST page, on the Page Layout step you can select "Search & Filter".

 

After you complete the wizard, you will see that you now have 2 new pages - one is Search and one is Results.

A Search page is similar to an Input page.

A Results page is similar to a List page.

 

Wizard steps

Page Name step

Enter a Page Name for both pages - this is what you will see in the platform.

Enter a Display Name for both pages - this is what the app user will see in the app.

REST Service URL step

URL

Enter the Search URL with each query parameter in curly braces, like {this}.  If the URL already has additional curly braces, escape each non-parameter curly brace with a backslash, like \{this\}.

The URL should contain all the search variables you want your app user to be able to use in searching.

Ex: You want to let the app user search by firstName or lastName, and you have a URL like this:

http://25.0.241.191/dev/api/employees?filter={"where":{"or":[{"firstName":{"like":"x"}},{"lastName":{"like":"y"}}]}}

which you would enter as:

http://25.0.241.191/dev/api/employees?filter=\{"where":\{"or":[\{"firstName":\{"like":"{x}"\}\},\{"lastName":\{"like":"{y}"\}\}]\}\}

Click "Check For Variables" and you will see "x" and "y" identified as parameters.  When you design the canvas, you will be able to place input fields labeled "x" and "y".  For this reason, we suggest that you give each parameter an identifiable name - that way you won't have to remember which field is which when designing the canvas.  For the above URL, you might enter this:

http://25.0.241.191/dev/api/employees?filter=\{"where":\{"or":[\{"firstName":\{"like":"{f_name}"\}\},\{"lastName":\{"like":"{l_name}"\}\}]\}\}

Click "Check For Variables" and you will see "f_name" and "l_name" as parameters.  Thus, when designing the canvas, you will have input fields labeled "f_name" and "l_name".

For each parameter, you can mark it as Search, Filter, or Variable.

  • Search - the app user can enter text in a textbox, and the text will be sent as part of the Search URL.
  • Filter - the app user can select an option from a dropdown, and the selection will be sent as part of the Search URL.
  • Variable - the value of this field will come from another page and cannot be edited by the app user.  The value will be sent as part of the Search URL.
    • Ex: Let's say you are creating an employee directory separated by department.  The app user will see a list of departments, tap one, and then see a list of employees in that department.  From here, you want the app user to be able to search for employees within that department.  You could let the app user select the department by marking it as Filter, or you could set the department automatically by marking it as Variable.  If you choose Variable, the app user will not choose the department.  When the app user taps the Get Results action button, the app will use the department tapped by the app user in executing the Search URL.

Sample Value - for every parameter, you can enter a Sample Value.  These values are used when you test your Search URL by executing it in the platform. (see "Send button" below)

Default Value - for every parameter set to Search or Variable, you can enter a Default Value.  These values are used to pre-populate search fields.  When the app user arrives on a Search page, each Search field will display its Default Value, if it has one, which the app user can either edit if desired.  If a Search field has no Default Value, it will display the Placeholder Text (which you can set on the canvas).

 

Custom Headers - check the "Do you need to use Custom Headers?" checkbox if you want to include additional header data in your REST call(s).  If you are not sure if you want to include headers, check with your REST database admin.

 

Option to delete - check the "Does the user need the ability to delete items?" checkbox if you want the app user to be able to delete items returned by the search.  If you check the checkbox, you will then be able to enter the Delete URL.  This URL will be executed when the app user is on the Results page and performs the standard list-item-delete gesture - Swipe Left on iOS and Long Press on Android.

 

Send button - this will execute the Search URL, using the Sample Value for each parameter, and allow you to see the response from your REST server.

 

Filter Options step

This step only shows up if you have one or more fields set to "Filter" on the REST Service URL step.  You will see a table for each such field.  For example, if you want to let the app user filter by gender and department, you could have a search URL like this:

http://25.0.241.191/dev/api/employees?filter=\{"where":\{"and":[\{"gender":"{gender}"\},\{"departmentId":"{dept_id}"\}]\}\}

You would have two variables, "gender" and "dept_id", and you would set both to "Filter" on the REST Service URL step.  When you come to the Filter Options step, you will have a table for "gender" and a table for "dept_id".  Neither table has any rows, and you can add a row by clicking the "Add new record" button in the upper right corner of a table.

Each row is a dropdown option, and you need to enter two fields for each row - the Filter Value and the Display Name.

Filter Value - this is the value that will be sent to your REST server.

Display Name - this is the value that will be displayed to the app user.

You can click a column name to sort the options by Filter Value or Display Name.  You can also grab any row using the far-left column and use drag-n-drop to move it higher or lower.  

 

 

 

 

In the app, the options will appear in the same order as they are on the Filter Options step of the wizard.

Dropdown menu on iPhone


Dropdown menu on Droid


If you want a certain option to be "pre-selected" for a field, click that option under the Default field.  This is not required - a field does not have to have a default option.

 

Select Parent Node step

This step allows you to choose the parent node - this is for the data to be displayed on the Results page.

 

Data Mapping step

This step allows you to choose how you want each field to display on the Results page, which is essentially a List page.

Available Features step

The only feature is Pagination, which may be used for the Results page.

Pagination step

This step allows you to choose your Next Page URL.  This can be useful if your search might return a large number of results.

 

Canvases

After the wizard, you'll have 2 pages, one Search and one Results.

A Search page is similar to an Input page.  You can add input fields which the app user can edit.

A Results page is similar to a List page.  You can add data fields to the top row, and each row will have the same layout.

These 2 pages are tied together - deleting one deletes both.

 

Search Canvas

The Search canvas is essentially an Input canvas.

Be sure to add a Get Results action button.

 

Results Canvas

The Results canvas is essentially a List canvas.  Open the Tool Box on the right, drag your fields onto the canvas, and configure them to display how you want.

As with a List page, you will often want to connect your Results page to a Detail page.  You can make this connection the same way you would from a List page - in the Properties box, on the Navigation tab, select your target AppBlock, then select your page, then select any variable fields needed.  If you have already created a Detail page using the same data, you can connect your Results page to that Detail page.

 

Targeting

Remember to give the app user a way to get to the Search page.

Targeting a Search page from a Home page button


Device Behavior

When the app user navigates to the Search page, the app shows the Search page.

Any fields with a Default Value show that value.  Any fields with no default value show the field's Placeholder Text.

When the app user taps the Get Results button, the app executes the Search URL, filling in each parameter with the data entered/selected by the app user.  For any field that is not on the page, its Default Value is used in the Search URL.

 

 

The data returned is shown on the Results page.

 

You can have multiple Results pages that target the same Detail page:

 

Common Questions

If I have an existing List REST component, can I convert it to a List w/ Search component?

No, you will need to add a new page and select "Search/Filter" as the Page Layout.


Are there best practices for searching with REST?

Yes - check out this link: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries

 

What if the app user leaves a field blank/empty/unselected?

That field will simply have no value in the URL, i.e. if the search URL is:

http://example/api/employees?filter={"where":{"or":[{"firstName":{"like":"{fname}"}},{"lastName":{"like":"{lname}"}}]}}

and the app user leaves firstName blank (and enters "Smith" for lastName), the app will send:

http://example/api/employees?filter={"where":{"or":[{"firstName":{"like":""}},{"lastName":{"like":"Smith"}}]}}

or if it is:

http://example/api/providerSearch/?fn={fn}&ln={ln}

and the user leaves fn blank (and enters "Smith" for ln), the app will send:

http://example/api/providerSearch/?fn=&ln=Smith

 

What if the app user enters a value with a space, such as "John Doe"?

The app will use URL encoding, so if the URL is:

http://example/api/employees?name={name}

the app will send:

http://example/api/employees?name=John%20Doe


Does capitalization matter?

It depends on your REST server.  The MobileSmith app will send whatever the app user types in, and it is up to the REST server to determine which items to return.  Check with your REST database admin.