Textbox with Autosearch

Shows a textbox. When the user types in the textbox a list of search results is shown. The user can choose one value from the list or continue writing. The control only accepts values from the list of search results.

Start value:
Return value: The ID value of the chosen option.
Supported in: NewEdit Parameter page Multirow Editable Grid

Appearance

alt text

  1. If the user types in the textbox, the list will be filtered accordingly.
  2. If the user has not picked something from the list, and the control loses focus, then the item that best fits what the user has typed will be selected. If there is no match at all, then the control will be cleared.
  3. If the user clicks the search icon on an empty control, it will list all the available choices.

SQL

SQL Call: Search (mandatory)

This call is made repeatedly as the user types into the textbox, and returns a list of search results for the entered value.

May modify database: No

Parameters

@TopN int
Max number of suggestions to return.

For better performance it is necessary to limit the number of suggestions sent from the database to the client.

Always use the exact value of @TopN in the TOP clause. Returning more values will cause an immediate exception. Returning fewer values when more values are present can cause unpredictable behavior.

You can use the Control height (rows) setting to control how many rows the list of suggestions contains.
@Value string
The text entered into the textbox.

Resultset: Search results

Table count: repeated exactly once
Row count: zero or more rows
Columns
<column with ordinal 1> mandatory string
ID value.
<column with ordinal 2> mandatory string
Text shown in textbox.
<column with ordinal 3> optional string
Text shown in listbox.
Default: If not present the values from the second column are used.
InfoHtml optional string
Extra informative HTML to display below the field. This is not supported in multirows.
InfoText optional string
Extra informative text to display below the field. This is not supported in multirows.
ListColumn_<xxx> optional string

Each column where the name starts with "ListColumn_" augments the value displayed in the listbox with a left aligned column of text. No headings are shown in the list.

SQL Call: ID Lookup (mandatory)

Gets the value to show in the textbox for a given id.

This call is made first when the page is first loaded and every time the control's value is changed by a default value dependency or a JavaScript.

May modify database: No

Parameters

@Id string
ID-value to get the text for.

Resultset: Friendly value

Table count: repeated exactly once
Row count: zero or one row
Columns
<column with ordinal 1> mandatory string
ID value. Must match the ID value passed to the lookup procedure.
<column with ordinal 2> mandatory string
Text to show.
InfoHtml optional string
Extra informative HTML to display below the field. This is not supported in multirows.
InfoText optional string
Extra informative text to display below the field. This is not supported in multirows.

Default value

SQL Call: Default value

Retrieves the default value for the control.

May modify database: No

Resultset: Default value

Table count: repeated exactly once
Row count: exactly one row
Columns
<column with ordinal 1> mandatory string
The default value

Validation

SQL Call: Validate value

This call is only made if there is a field validation set for the field info and the field has any content. Fields used in an editable grid do not use this call.

Live Validation

Performs field validation when the user leaves the field or one of its dependencies is changed, initial values set by default value and initial values in edit-mode are not validated.

Save Validation

When saving the validation runs server side if the field value has changed. A field value is considered changed if in new mode the value is anything other than NULL. In edit mode it is considered changed if it has a value that was not returned by the GetEditFields procedure.

May modify database: No

Parameters

@Value string
The value of the field, the procedure will not be called if value is NULL.

Resultset: Validation messages (optional)

Table count: repeated zero or one time
Row count: zero or one row
Columns
Error optional string
Error message to display. Blocks the user from saving.
Info optional string
Informative message to display. Does not block saving.
Warning optional string
Warning message to display. Does not block saving.

Examples

Textbox with autosearch

Textbox with autosearch works like a slimmed down version of "Textbox with popup". The popup is opened automatically as the user types. However, only an ID-value and a friendly value is supported, much like a dropdown control.

CREATE PROCEDURE Example.TextboxWithAutosearchTable_TextboxWithAutosearch
	@Id				varchar(max) = NULL,
	@Value			nvarchar(max) = NULL,
	@TopN			int = NULL
AS
BEGIN
	SET NOCOUNT, XACT_ABORT ON;

	-- SQL Call: ID Lookup
	IF @Id IS NOT NULL
	BEGIN
		SELECT
			U.UserId,
			U.Username
		FROM
			SoftadminApi.[User] U
		WHERE
			U.UserId = @Id;

		RETURN;
	END;

	-- If you need to be able to search for %, [], [^], _ - make sure you use the escape function below.
	SELECT @Value = ISNULL(SoftadminUtil.String_EscapeLikeWildcards(@Value), '') + '%';
	
	-- SQL Call: Search
	SELECT TOP (@TopN)
		U.UserId,
		U.Username
	FROM
		SoftadminApi.[User] U
	WHERE
		U.Username LIKE @Value
	ORDER BY
		U.Username;
END;

Best practice

Escape @Value

Always escape searched value even if "Create LIKE pattern" is checked when editing the control. Safety redundancy is considered good practice.

SELECT @Value = SoftadminUtil.String_EscapeLikeWildcards(@Value);